API levels

An API level determines which APIs are available for you to use in your app. The API level corresponds to a version of the BlackBerry 10 OS (for example, 10.0, 10.1, and 10.2). When you create a project for your app and select an API level, you are choosing the version of the BlackBerry 10 OS that your app is compatible with.

The API level is backward compatible. Higher API levels include all of the APIs from lower API levels. APIs are deprecated, but are not removed, to ensure that existing apps can continue to use them.

API levels also correspond to a version of the Momentics IDE for BlackBerry. To use a particular API level, you must also use a Momentics IDE version that supports it. The Momentics IDE is backward compatible with older API levels, but it is not forward compatible with newer API levels. When you download a newer API level that your Momentics IDE version does not support, your Momentics IDE updates automatically.

You can select Use Global as your API level to apply the same API level to all of your projects or you can specify an API level for each project that you create. By default, new projects use the global API level. If you update the global API level, the API level of your project changes automatically.

API levels and supported devices

Each API level supports a set of devices. When you select an API level, you see a list of devices that the API level supports. The API level of your app must correspond to the API level of the device that you want to run your app on.

Apps that are developed with a lower API level are supported on existing devices and can reach a broader market. However, apps that are developed with a higher API level can take advantage of a richer set of APIs and features.

If your app uses APIs that were introduced in a higher API level, you can't install the app on a device with a lower API level. However, you can run an app with a lower API level on a device with a higher API level because API levels are backward compatible.

To deploy your app on a device with an OS version that supports a lower API level, do one of the following:

  • Upgrade the OS version on the device (the device runtime).
  • Download a simulator that matches the API level that the app uses.
  • Downgrade the app API level to one that supports the device. You can either select a different installed API level or download another one.

Set the global API level

You can use the global API level to manage the API level for multiple projects in your workspace. By default, the global API level is the latest installed API level. If you set the API level for a project to Use Global, it uses the global API level. When you change the global API level, it updates the API level for all projects in the workspace that use the global setting.

By default, new projects use the global API level. The first time that you start the Momentics IDE, you can complete the Download and Install SDK wizard and install an API level. That API level becomes the global API level.

You can change the global API level and the API level for a specific project at any time.

  1. In Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences.
  2. Expand BlackBerry and click API Level.
  3. Select the API level to use for all projects that have the Use Global option set.

Set the API level for your project

You can select a specific API level to use for any project. The API level determines which version of the BlackBerry 10 OS your app is compatible with.

The API level that you select also sets the minimum platform version for your app. You must use the same platform version when you publish your app on the BlackBerry World storefront. For more information and to submit your app, see BlackBerry World.

To change the API level of an existing project:

  1. In the Project Explorer view, right-click your project and click Properties.
  2. Click BlackBerry API Level and select the API level that your project supports from the drop-down list.
  3. Click Apply and click OK.

When you set the API level for your project, it updates the platform version number that is used when you package your app. You can set the platform version explicitly in the bar-descriptor.xml file.

To set the platform version in the bar-descriptor.xml file:

  1. In the Project Explorer view, expand your project and open the bar-descriptor.xml file.
  2. On the General tab, expand the API Level section, and then select Explicitly set the platform version.
  3. In the Platform version field, type the version of the BlackBerry 10 OS that you want to use. You must have an installed API level that targets the specified platform version.
  4. Save your changes.

Download and install an API level

You can download and install a new API level from the Help menu. After you download a new API level, you can use it with any project.

  1. On the Help menu, click Update API Levels.
  2. In the API Levels dialog box, select the tab for the type of API level that you want to install (Gold or Beta).
  3. Click Install for the API level that you want to install.
  4. When the API level finishes installing, click OK.

You can also install a custom API level by selecting the Custom tab in the API Levels dialog box and clicking Add New Custom SDK. You can specify a path to an SDK platform and uniquely name an SDK when you create a custom API level.

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus