Getting Started With Cordova

Moved to https://github.com/meteor/meteor/wiki/Meteor-Cordova-integration 

DEPRECATED

Please use the wiki linked above.

Demo App Repository

The app demoed on Meteor Devshop August can be accessed on SoLoMo.Meteor.com and the source code is available on GitHub.

Migration from 0.8.x to a 0.9.2-rcX

To migrate your existing app, you need to migrate to 0.9.x first by typing in your app folder:

This will migrate your tool and core packages to The New Meteor Packaging System (tm)! After that feel free to migrate to a Cordova release:

Note: with 0.9.x releases you no longer use old Atmosphere packages. You use the new and shiny official packaging server.

Installation

iOS

Android

No special installation necessary. The first time a build for Android occurs, Meteor will download and install the necessary toolchain in a bundle (around 300Mb-350Mb depending on your host platform). A preinstalled modern version of Java Runtime Environment (JRE) is required.  

See Device Setup for information on how to debug and run Meteor apps on a physical iOS or Android device.

If you already have Android Development Kit installed on your system and you don’t want Meteor to install another one: be sure to set the `USE_GLOBAL_ADK` environment variable with every command. Ex.:

If you let android SDK download it gets installed into `~/.meteor/android_bundle/sdk`

Command Line Interface

Configuring Android Virtual Devices

Meteor tries to set up a virtual device for you on the first run called ’meteor’ but chances are it can be incorrect or misconfigured for your machine. You can open the Android configuration tool from the ADK environment used by Meteor.  

(You may want to install the "Intel x86 Emulator Accelerator" to speed up your Emulator)

Adding/removing platforms

Every Meteor project targets a set of "platforms". Platforms can be added to a Meteor project with `meteor add-platform`

`meteor add-platform ios` adds the iOS platform to a project.

`meteor add-platform android` adds the Android platform to a project.

`meteor remove-platform ios android`  will remove the iOS and Android platforms from a project.

`meteor list-platforms` lists the targeted platforms of an app.

Running a Meteor mobile app

Once your app has a set of platforms, you can run your app locally, using either a simulator or a physical device. 

  • Simulator
  • `meteor run ios` runs your Meteor app in an iOS simulator and starts the server.

    `meteor run android` runs your Meteor app in an Android simulator and starts the server.

    Both commands will start the Meteor server and an emulator, and connect the emulator to the locally running server. The logs from the emulator will appear in the console where the command is executed.

    When running on iOS,  a black screen may initially appear upon starting the simulator. If this happens, press the "home" button at the bottom of the simulator and then click on your app to start the app.

  • Physical device
  • In order to test on a physical device, you must specify the host and port of the local server. Most likely, this will be the same as the local IP of your computer. Your device and the computer running the server should be connected to the same local network and the network configuration should allow such scenario.

    `meteor run android-device -p <local IP>:<local port>`runs your app on an Android device and spawns a server locally. The Android device will connect to the server at <local IP>. 

    `meteor run ios-device -p <local IP>:<local port>` will open the Meteor Cordova project in Xcode, allowing you to run on your iOS device from the Xcode interface. 

    Your mobile device and computer must be connected to the same network for client-server communication to work.

  • Advanced
  • `meteor run` can optionally take a `--no-server` option which runs the app on the listed platforms but does not spawn a local server.

    For example, `meteor run ios android-device --production --no-server` will spawn a production version of your app on the ios emulator and a USB-connected Android device, and will not start a local server. 

    `meteor run` can also take a `--settings` argument, see settings section for details.

    `meteor run` can also take a `--verbose` argument which prints the full Cordova builds logs.

    Building

    `meteor build <bundle path> -p <host>:<port>` builds your app.

    This will generate a directory at <target bundle path> which includes a server deployment tarball, and the project source for each targeted mobile platform in the `/ios/` and `/android/` directories.

    The <host> and <port> should be the <host> and <port> of the target server environment.

    `meteor build` can also take a `--settings` argument, see settings section for details.

    Testing 

    `meteor test-packages [--ios] [--android] [--ios-device] [--android-device]` runs Tinytests on the specified device(s).

    `meteor test-packages` can also take a `--verbose` argument which prints the full Cordova builds logs.

    Settings

    Some Cordova plugins, such as the "Facebook Connect" plugin, require build-time variables such as an APP_ID or APP_NAME. To include these variables in your Cordova build, pass `--settings [settings-path]` to `run` and `build`.

    The `settings.json` file should have the following format:

    Where the `cordova` object contains a mapping from plugin name to variables.

    Cordova-specific code in your application

    The same way you can use `Meteor.isServer` and `Meteor.isClient` booleans to separate your client-side code and server-side code, you can use `Meteor.isCordova` constant to separate your Cordova-specific code from the rest of code shipped to browsers and mobile devices.

    Any functionality which relies on a Cordova plugin should wrap code in a `Meteor.startup()` block. For example, when using the Cordova geolocation plugin:

    Meteor packages with Cordova dependencies

    A Meteor package can register a dependency on a Cordova plugin with the `Cordova.depends()` syntax. For example, a Meteor package that depends on the Cordova "camera" plugin would add the following JavaScript to its `package.js`:

    Any project that includes this package will now have the`navigator.camera` object in its global scope. Note that this will pollute the global scope, so be careful to include all the necessary plugins when developing a package.

    If the desired plugin version is not published on Cordova Registry yet, you can specify the tarball url for obtaining the plugin:

    Note: be sure to use Cordova plugins functionality after they are fully loaded. i.e. all actual calls should happen after `Meteor.startup`.

    In addition, packages can include a different set of files for Cordova builds and browser builds with `addFiles`:

    `api.addFiles(’foo.js’, ’client.cordova’)`: includes `foo.js` in only Cordova builds.

    `api.addFiles(’bar.js’, ’client.browser’)`: includes `bar.js` in only browser builds.

    `api.addFiles(’baz.js’, ’client’)`: includes `baz.js` in all client builds.

    The same syntax can be used for `api.use`, `api.imply`, and `api.export`.

    Cordova plugins in your application

    You can use Cordova plugins directly in your application without wrapping the plugin into a Meteor package.

    Similar to Meteor packages, you can add them to your application with `meteor add` command prepending the plugin names with the `cordova` namespace:

    Note: right now we don’t resolve any versions conflicts between plugins directly added to your app and plugins used by Meteor packages. One will most likely override another but in not a particularly intelligent way.

    Cordova plugins will expose methods to the global scope.

    Hot Code Push

    By default, Meteor will push new versions of an application to connected clients. 

    Every time the mobile app client notices a new version, the whole source-code of the new version is downloaded to application’s internal storage. After the download is finished, the app reloads.

    Later, when the app boots up, before loading the bundled application code shipped through App Store or Play Store, app tries to load from the internal storage copy. In case of files not being found on disk, app falls-back to the code shipped with the app container.

    XXX explain how can you postpone the reload here?

    Warning: If you push a malformed version of your app to the clients, your clients can get stuck in a state where they cannot download a newer (fixed) version. In that case your best bet is to either push a new version through App Store or Play Store, or tell your users to clean the application data (that’s where the malformed version of the app is stored).

    Warning: If you change the set of used Cordova plugins providing native functionality, there is no way to push such updates to the clients if a Hot Code Push reload. Such updates should be made to the app container and pushed through App Store or Play Store.

    Device Setup

    To test on an iOS device or distribute on the iOS store, you will need an Apple iOS Developer Account: https://developer.apple.com/programs/ios/

    To test on an iOS device, you will also have to provision your device through Xcode: https://developer.apple.com/library/ios/recipes/xcode_help-devices_organizer/articles/provision_device_for_development-generic.html

    To test on an Android device, you may have to enable ’developer tools’ on your phone: http://developer.android.com/tools/device.html

    Advanced build customization

    Sometimes you might need to override parts of the Cordova project maintained by Meteor for you in a disposable `project/.meteor/local/cordova-build` directory. Examples are:

    For these and other advanced purposes we created a special top-level folder called `cordova-build-override`. The whole file tree of this directory will be `cp -R` (copied overwriting existing files) to the Cordova project right before the build and compilation.

    For example: if you want to have a customized `config.xml`, you would put it as `project/cordova-build-override/config.xml`.

    Known Issues