Skip to content

Mobile Configuration

If your Meteor application targets mobile platforms such as iOS or Android, you can configure your app's metadata and build process in a special top-level file called mobile-config.js which is not included in your application and is used only for this configuration.

The code snippet below is an example mobile-config.js file. The rest of this section will explain the specific API commands in greater detail.

js
// This section sets up some basic app metadata, the entire section is optional.
App.info({
  id: 'com.example.matt.uber',
  name: 'über',
  description: 'Get über power in one button click',
  author: 'Matt Development Group',
  email: 'contact@example.com',
  website: 'http://example.com'
});

// Set up resources such as icons and launch screens.
App.icons({
  'iphone_2x': 'icons/icon-60@2x.png',
  'iphone_3x': 'icons/icon-60@3x.png',
  // More screen sizes and platforms...
});

// Before Meteor 2.6 we had to pass device specific splash screens for iOS, but this behavior was dropped in favor of story board images.
App.launchScreens({
    // iOS
    // For most cases you will only need to use the 'ios_universal' and 'ios_universal_3x'.
    'ios_universal': { src: 'splash/Default@2x.png', srcDarkMode: 'splash/Default@2x~dark.png' }, // (2732x2732) - All @2x devices, if device/mode specific is not declared
    'ios_universal_3x': 'splash/Default@3x.png', // (2208x2208) - All @3x devices, if device/mode specific is not declared

    // If you still want to use a universal splash, but want to fine-tune for the device mode (landscape, portrait), then use the following keys:
    'Default@2x~universal~comany': 'splash/Default@2x~universal~comany.png', // (1278x2732) - All @2x devices in portrait mode.
    'Default@2x~universal~comcom': 'splash/Default@2x~universal~comcom.png', // (1334x750) - All @2x devices in landscape (narrow) mode.
    'Default@3x~universal~anycom': 'splash/Default@3x~universal~anycom.png', // (2208x1242) - All @3x devices in landscape (wide) mode.
    'Default@3x~universal~comany': 'splash/Default@3x~universal~comany.png', // (1242x2208) - All @3x devices in portrait mode.

    // However, if you need to fine tune the splash screens for the device idiom (iPhone, iPad, etc).
    'Default@2x~iphone~anyany': 'splash/Default@2xiphoneanyany.png', // (1334x1334) - iPhone SE/6s/7/8/XR
    'Default@2x~iphone~comany': 'splash/Default@2xiphonecomany.png', // (750x1334) - iPhone SE/6s/7/8/XR - portrait mode
    'Default@2x~iphone~comcom': 'splash/Default@2xiphonecomcom.png', // (1334x750) - iPhone SE/6s/7/8/XR - landscape (narrow) mode
    'Default@3x~iphone~anyany': 'Default@3xiphoneanyany.png', // (2208x2208) - iPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max
    'Default@3x~iphone~anycom': { src: 'splash/Default@3xiphoneanycom.png', srcDarkMode: 'splash/Default@3xiphoneanycom~dark.png' }, // (2208x1242) - iPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max - landscape (wide) mode
    'Default@3x~iphone~comany': 'Default@3xiphonecomany.png', // (1242x2208) - iPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max - portrait mode
    'Default@2x~ipad~anyany': 'Default@2xipadanyany.png', // (2732x2732) - iPad Pro 12.9"/11"/10.5"/9.7"/7.9"
    'Default@2x~ipad~comany': 'Default@2xipadcomany.png', // (1278x2732) - iPad Pro 12.9"/11"/10.5"/9.7"/7.9" - portrait mode

    // Android
    'android_universal': 'splash/android_universal.png', // (320x480)
});

// Set PhoneGap/Cordova preferences.
App.setPreference('BackgroundColor', '0xff0000ff');
App.setPreference('HideKeyboardFormAccessoryBar', true);
App.setPreference('Orientation', 'default');
App.setPreference('Orientation', 'all', 'ios');

// Pass preferences for a particular PhoneGap/Cordova plugin.
App.configurePlugin('com.phonegap.plugins.facebookconnect', {
  APP_ID: '1234567890',
  API_KEY: 'supersecretapikey'
});

// Add custom tags for a particular PhoneGap/Cordova plugin to the end of the
// generated config.xml. 'Universal Links' is shown as an example here.
App.appendToConfig(`
  <universal-links>
    <host name="localhost:3000" />
  </universal-links>
`);

App.info

Summary:

Set your mobile app's core configuration information.

Arguments:

Source code
NameTypeDescriptionRequired
optionsObjectYes

Options:

NameTypeDescriptionRequired
id, version, name, description, author, email, websiteString

Each of the options correspond to a key in the app's core configuration as described in the Cordova documentation.

No
js



const result = App.info();
  options
);

App.setPreference

Summary:

Add a preference for your build as described in the Cordova documentation.

Arguments:

Source code
NameTypeDescriptionRequired
nameString

A preference name supported by Cordova's config.xml.

Yes
valueString

The value for that preference.

Yes
platformString

Optional. A platform name (either ios or android) to add a platform-specific preference.

No
js



const result = App.setPreference();
  "name",
"value",

"platform", // this param is optional
);

App.accessRule

Summary:

Set a new access rule based on origin domain for your app. By default your application has a limited list of servers it can contact. Use this method to extend this list.

Default access rules:

  • tel:*, geo:*, mailto:*, sms:*, market:* are allowed and are handled by the system (e.g. opened in the phone app or an email client)
  • http://localhost:* is used to serve the app's assets from.
  • The domain or address of the Meteor server to connect to for DDP and hot code push of new versions.

Read more about domain patterns in Cordova docs.

Starting with Meteor 1.0.4 access rule for all domains and protocols (<access origin="*"/>) is no longer set by default due to certain kind of possible attacks.

Arguments:

Source code
NameTypeDescriptionRequired
patternString

The pattern defining affected domains or URLs.

Yes
optionsObjectNo

Options:

NameTypeDescriptionRequired
typeString

Possible values:

  • 'intent': Controls which URLs the app is allowed to ask the system to open. (e.g. in the phone app or an email client).
  • 'navigation': Controls which URLs the WebView itself can be navigated to (can also needed for iframes).
  • 'network' or undefined: Controls which network requests (images, XHRs, etc) are allowed to be made.
No
launchExternalBoolean

(Deprecated, use type: 'intent' instead.)

No
js



const result = App.accessRule();
  "pattern",
options, // this param is optional
);

For example this Cordova whitelist syntax:

xml
<access origin="https://www.google-analytics.com" />
<allow-navigation href="https://example.com" />

is equivalent to:

js
App.accessRule('https://www.google-analytics.com');
App.accessRule('https://example.com', { type: 'navigation' });

App.configurePlugin

Summary:

Set the build-time configuration for a Cordova plugin.

Arguments:

Source code
NameTypeDescriptionRequired
idString

The identifier of the plugin you want to configure.

Yes
configObject

A set of key-value pairs which will be passed at build-time to configure the specified plugin.

Yes
js



const result = App.configurePlugin();
  "id",
config,
);

Note: When using App.configurePlugin to re-configure a plugin which has been previously configured, the changes may not be reflected without manually clearing the existing Cordova build. To clear the existing Cordova build, remove the .meteor/local/cordova-build directory and re-build the application using either meteor run or meteor build.

App.icons

Summary:

Set the icons for your mobile app.

Arguments:

Source code
NameTypeDescriptionRequired
iconsObject

An Object where the keys are different devices and screen sizes, and values are image paths relative to the project root directory.

Valid key values:

  • app_store (1024x1024) // Apple App Store
  • iphone_2x (120x120) // iPhone 5, SE, 6, 6s, 7, 8
  • iphone_3x (180x180) // iPhone 6 Plus, 6s Plus, 7 Plus, 8 Plus, X
  • ipad_2x (152x152) // iPad, iPad mini
  • ipad_pro (167x167) // iPad Pro
  • ios_settings_2x (58x58) // iPhone 5, SE, 6, 6s, 7, 8, iPad, mini, Pro
  • ios_settings_3x (87x87) // iPhone 6 Plus, 6s Plus, 7 Plus, 8 Plus, X
  • ios_spotlight_2x (80x80) // iPhone 5, SE, 6, 6s, 7, 8, iPad, mini, Pro
  • ios_spotlight_3x (120x120) // iPhone 6 Plus, 6s Plus, 7 Plus, 8 Plus, X
  • ios_notification_2x (40x40) // iPhone 5, SE, 6, 6s, 7, 8, iPad, mini, Pro
  • ios_notification_3x (60x60 // iPhone 6 Plus, 6s Plus, 7 Plus, 8 Plus, X
  • ipad (76x76) // Legacy
  • ios_settings (29x29) // Legacy
  • ios_spotlight (40x40) // Legacy
  • ios_notification (20x20) // Legacy
  • iphone_legacy (57x57) // Legacy
  • iphone_legacy_2x (114x114) // Legacy
  • ipad_spotlight_legacy (50x50) // Legacy
  • ipad_spotlight_legacy_2x (100x100) // Legacy
  • ipad_app_legacy (72x72) // Legacy
  • ipad_app_legacy_2x (144x144) // Legacy
  • android_mdpi (48x48)
  • android_hdpi (72x72)
  • android_xhdpi (96x96)
  • android_xxhdpi (144x144)
  • android_xxxhdpi (192x192)
Yes
js



const result = App.icons();
  icons
);

App.launchScreens

Summary:

Set the launch screen images for your mobile app.

Arguments:

Source code
NameTypeDescriptionRequired
launchScreensObject

A dictionary where keys are different devices, screen sizes, and orientations, and the values are image paths relative to the project root directory or an object containing a dark mode image path too { src, srcDarkMode } (iOS only). Note: If you want to have a dark theme splash screen on Android, please follow the instructions described here.

For Android specific information, check the Cordova docs and Android docs. Also note that for android the asset can either be an XML Vector Drawable or PNG.

For best practices when developing a splash image, see the Apple Guidelines. To learn more about size classes for iOS, check out the documentation from Cordova.

Valid key values:

iOS:

  • ios_universal (Default@2xuniversalanyany.png - 2732x2732 px) - All @2x devices, if device/mode specific is not declared
  • ios_universal_3x (Default@3xuniversalanyany.png - 2208x2208 px) - All @3x devices, if device/mode specific is not declared
  • Default@2x~universal~comany (1278x2732 px) - All @2x devices in portrait mode
  • Default@2x~universal~comcom (1334x750 px) - All @2x devices in landscape (narrow) mode
  • Default@3x~universal~anycom (2208x1242 px) - All @3x devices in landscape (wide) mode
  • Default@3x~universal~comany (1242x2208 px) - All @3x devices in portrait mode
  • Default@2x~iphone~anyany (1334x1334 px) - iPhone SE/6s/7/8/XR
  • Default@2x~iphone~comany (750x1334 px) - iPhone SE/6s/7/8/XR - portrait mode
  • Default@2x~iphone~comcom (1334x750 px) - iPhone SE/6s/7/8/XR - landscape (narrow) mode
  • Default@3x~iphone~anyany (2208x2208 px) - iPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max
  • Default@3x~iphone~anycom (2208x1242 px) - iPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max - landscape (wide) mode
  • Default@3x~iphone~comany (1242x2208 px) - iPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max - portrait mode
  • Default@2x~ipad~anyany (2732x2732 px) - iPad Pro 12.9"/11"/10.5"/9.7"/7.9"
  • Default@2x~ipad~comany (1278x2732 px) - iPad Pro 12.9"/11"/10.5"/9.7"/7.9" - portrait mode

Android:

  • android_universal (288x288 dp)
Yes
js



const result = App.launchScreens();
  launchScreens
);

App.appendToConfig

Summary:

Append custom tags into config's widget element.

App.appendToConfig('<any-xml-content/>');

Arguments:

Source code
NameTypeDescriptionRequired
elementString

The XML you want to include

Yes
js



const result = App.appendToConfig();
  "element"
);

App.addResourceFile

Summary:

Add a resource file for your build as described in the Cordova documentation.

Arguments:

Source code
NameTypeDescriptionRequired
srcString

The project resource path.

Yes
targetString

Resource destination in build.

Yes
platformString

Optional. A platform name (either ios or android, both if omitted) to add a resource-file entry.

No
js



const result = App.addResourceFile();
  "src",
"target",

"platform", // this param is optional
);

Note: The resource file is copied in two steps : from the src of your meteor project to the root of the cordova project, then to the target