Use native extensions

Native extensions let you include native platform capabilities into your mobile application.

A native extension contains ActionScript classes and native code. Native code implementation lets you access device-specific features, which cannot be accessed using pure ActionScript classes. For example, accessing the device's vibration functionality.

Adobe recommends

Have a tutorial you would like to share?

Article: Extending Adobe AIR

Oliver Goldman
Learn more about creating, using, and packaging native extensions

Native code implementation can be defined as the code that executes outside the Adobe AIR runtime. You define platform-specific ActionScript classes and native code implementation in the extension. The ActionScript extension classes access and exchange data with the native code using the ActionScript class ExtensionContext.

Extensions are specific to a device's hardware platform. You can create platform-specific extensions or you can create a single extension that targets multiple platforms. For example, you can create a native extension that targets both Android and iOS platforms. The following mobile devices support native extensions:

  • Android devices running Android 2.2 or a later version

  • iOS devices running iOS 4.0 or a later version

For detailed information on creating cross-platform native extensions, see Developing Native Extensions for Adobe AIR.

For a collection of native extension samples, contributed by Adobe and the community, see Native extensions for Adobe AIR.

Package native extensions

To provide your native extension to application developers, you package all the necessary files into an ActionScript Native Extension (ANE) file by following these steps:

  1. Build the extension’s ActionScript library into a SWC file.

  2. Build the extension’s native libraries. If the extension has to support multiple platforms, build one library for each target platform.

  3. Create a signed certificate for your extension. If the extension is not signed, Flash Builder displays a warning when you add the extension to your project.

  4. Create an extension descriptor file.

  5. Include any external resources for the extension, such as images.

  6. Create the extension package using the Air Developer Tool. For more information, see the Adobe AIR documentation.

For detailed information on packaging ActionScript extensions, see Developing Native Extensions for Adobe AIR.

Add native extensions to a project

You include an ActionScript Native Extension (ANE) file in the project’s build path the same way as you would include a SWC file.

  1. In Flash Builder, when you create a Flex mobile project, select the Native Extensions tab in the Build Paths settings page.

    You can also add extensions from the Project Properties dialog box by selecting Flex Build Path.

  2. Browse to the ANE file or the folder containing the ANE files to add to the project. When you add an ANE file, the extension ID is added to the project’s application descriptor file (project name-app.xml) by default.

Flash Builder displays an error symbol for the added extension in the following scenarios:

  • The Adobe AIR runtime version of the extension is later than the application’s runtime version.

  • The extension does not include all the selected platforms that the application is targeting.

Note: You can create an ActionScript native extension that targets multiple platforms. To test an application that includes this ANE file on your development computer using the Adobe AIR Simulator, ensure that the ANE file supports the computer’s platform. For example, to test the application using the Adobe AIR Simulator on Windows, ensure that the ANE file supports Windows.

Include ActionScript native extensions in an application package

When you use the Export Release Build feature to export the mobile application, the extensions used in the project are included within the application package by default.

To change the default selection, follow these steps:

  1. In the Export Release Build dialog box, select the Native Extensions tab under Package Settings.

  2. The ActionScript native extension files referenced in your project are listed, indicating if the ANE file is used in the project or not.

    If the ANE file is used in the project, it is selected by default in the application package.

    If the ANE file is included in the project but not used, the compiler does not recognize the ANE file. It is then not included in the application package. To include the ANE file in the application package, do the following:

    1. In the Project Properties dialog box, select Flex Build Packaging and the required platform.

    2. Select the extensions that you want to include in the application package.

Configure an iOS SDK externally

The Adobe AIR SDK contains a bundled iOS SDK version. The bundled iOS SDK version is specific to the Adobe AIR version. For example, Adobe AIR 3.1 contains iOS4 SDK, and Adobe AIR 3.4 contains iOS5 SDK.

If you want to use features from an iOS SDK higher than the bundled version, you can configure the supported iOS SDK version externally.

The supported iOS SDK versions are as follows:

Adobe AIR version

Bundled iOS SDK version

iOS SDK version supported for external configuration

AIR 3.1

iOS4

iOS5

AIR 3.4

iOS5

IOS6

You can configure an iOS SDK by using the AIR Developer Tool (ADT). Flash Builder lets you select the location of the supported external iOS SDK using the Package Settings dialog. After you select the location of the iOS SDK, the selected location is passed through the -platformsdk ADT command.
Note: With Adobe AIR 3.1, you can configure an external iOS SDK only on Mac. With Adobe AIR 3.4, you can configure it both on Windows and Mac.

Hide ANE Library Symbols

When you use multiple native extensions in your iOS application, there can be common symbol names that are used among the native extensions. These symbol name conflicts can cause issues during packaging (error message appears). And in some cases, cause the application to crash during runtime.

To ensure that this error does not occur, follow these steps:

  1. In the Project Properties dialog, select Build Packaging > Apple iOS.

  2. Under the Native Extensions tab, select Hide ANE-Library-Symbols.

When you select this option, the ADT package command -hideAneLibSymbols is set to yes, and any unintended symbol conflict issues are resolved. For more information, see ADT package command.

Verify if symbol conflict issues are causing the application to crash

Not all application crashes are caused due to symbol conflict issues. To determine if the crash was caused only due to duplicate symbols in the object files, package the application from the command line using the ADT -package command. Then, review the warning, if it appears.
Note: If the IPA is created successfully, Flash Builder does not show any warnings even if the packager has identified warnings. To review the warnings that appear during packaging, you must package the application from the command line.

To get the command line details, follow these steps:

  1. Click Customize Launch in the Run/Debug configurations dialog box or in the Package Settings section of the Export Release Build dialog box.

  2. In the Customize The Launch Parameters dialog, select Show Command.