What can I do with AIR Native Extensions?

Adobe AIR 3.0 introduces an exciting new feature: AIR Native Extensions. This is an architectural enhancement that lets you expand the capabilities of your AIR applications. By using native extensions, you can: access native features of devices; perform multi-threaded operations; and offload hard tasks to highly optimized, native libraries.

Native extensions are used by creating .ANE files, which combine ActionScript 3 code with native code, such as C++, Java, and Objective-C. You then package the native extension into your applications, and access the features as you would any other ActionScript 3 API.

Adobe has created some sample native extensions to get you started:

I’ve worked on two native extension resources that will soon be available via my blog:

  • A notification native extension, for dispatching native notifications on Android and iOS devices.
  • A complete tutorial on creating your own native extension from the ground up.

You can get started today by downloading the Adobe AIR 3.0 Release Candidate from Adobe Labs and referring to the above samples. You’ll have to compile and package your applications using the command line tool adt. Once builds of Flash Builder 4.6 are available, however, you’ll be able to create apps that use native extensions without using command line tools.

Check back soon to learn about getting access to Flash Builder 4.6, to download the notification native extension sample, and to read my tutorial on creating your own.

Additional Resources

29 Responses to What can I do with AIR Native Extensions?

  1. Orr Kislev says:

    Native Extensions are awesome, and its even more great right now that I when looking for some features for my first air for ios project! yey!
    and I read some about it, but I couldnt feagure it out, and I don’t know Objective C, and I don’t have a mac…
    I will be so pleased when you publish both the native notification extension (and how to use it) and the tutorial on creating my own, so please, is you can, notify me when you do…
    orrkislev@gmail.com

  2. Craig says:

    Hi Daniel,

    Great resource. We’re really excited about using Adobe Air in our mobile app, and native extensions make this a real option for us.

    I’m currently trying to compile down the Vibration example for iOS, but am getting the following error:

    “Error occurred while packaging the application:
    /TestVibrationExtension-app.xml: error 102: Invalid namespace http://ns.adobe.com/air/application/3.0

    I’m guessing this is due to trying to compile using FB 4.5, and from your post it appears I need to compile on the command line using adt. Is that the solution to building the app correctly, or is there something else I’m missing? If so, do you have any links to example of compiling an .ipa using adt? (sorry…I’m a obj-C guy and want to check before I sit down and learn how to use adt).

    Also, is there any ETA on when FlashBuilder 4.6 prerelease will be available?

    Looking forward to seeing more from Adobe in mobile!

    Thanks,
    Craig

  3. Pingback: Rebirth of a (Flash) Developer | Philter Design Studios

  4. Michael Baisuck says:

    So, if I am understanding this all correctly, these wonderful new “Native Extensions” for AIR are actually only wonderful if you are a developer using Flex (and you know how to program and compile Java). For designers like myself who have been using Flash since the 90’s, we’re out in the cold.
    Is there any chance that Adobe is going to remember that not all Flash users have a background in programming, and pre-package these “Native Extensions” in a way that makes them accessible?
    Thank you for your attention.

    • dkoestle says:

      Hey Michael,

      Although the examples I wrote provide Flex as the sample client application, you can use AIR with just AS3 and no Flex. You can also use Flash Pro to create a SWF, and use AIR’s command line tools to include the native extensions you reference via SWCs. Many of the extensions referenced in this post require no Flex at all.

      A lot of the information on native extensions is currently geared towards providing developers with samples and tutorials for creating their own native extensions. These developers will then package their native extensions as ANE files, which can be dropped into Flex or plain AS3 apps, without you having to know the specifics of the language it was written in.

      • Michael Baisuck says:

        Daniel,
        Thank you for your response. Is there any documentation/examples available that demonstrate this? I’ve been trying to implement Christian Cantrell’s “CompassApp” example. Unfortunately, his samples are for Flex and also require that I build the ANE from .java files, and I don’t know how to do that. I looked at some other examples provided by Adobe (specifically the Vibration and Gyroscope extensions) but ran into the same roadblocks. These examples do include SWC files, but provide no instructions on how to use them.
        If you could point me to some step-by-step instructions or examples of Native Extensions being used in conjunction with Flash Pro, I would be greatly appreciative.
        Thanks again.
        Mike
        P.S. I apologize if my frustration is leaking out into this message, but it seems that all of the newest features are only accessible by trained developers. As a Flash designer who has been using your software since 1998, I must admit, I’m feeling a little abandoned. ๐Ÿ™
        Thanks again for any help you can provide.

        • dkoestle says:

          There are a few paths you can take for using ANEs, depending on what tools you’re using. By far the easiest way is to use Flash Builder; you have to sign up for the Flash Builder 4.6 prerelease, but this version of FB will package the ANE in with your application, and take care of referencing the library so you can access the APIs.

          If you want to go this route, I recommend following my tutorial and skipping directly to “Using the native extension in a Flex sample application.” Download the zip to access the completed ANE file. In your case, create an AIR Mobile Application and NOT a Flex Mobile Application, so that you can use only the AS3 code you’re familiar with. Here’s the article: http://www.adobe.com/devnet/air/articles/developing-native-extensions-air.html#articlecontentAdobe_numberedheader_4

          If you don’t use FB or don’t have FB 4.6, however, you’ll have to use the AIR command line tools. Create your AIR application as you normally would (Flash Pro or your own IDE), but pass some additional parameters to adt to specify that you’re using a native extension. You’ll also have to link to the SWC file provided with the extension, so that your AS3 code will understand the new API calls you’re trying to make. The additional parameters for using extensions with command line tools are here: http://help.adobe.com/en_US/air/build/WS597e5dadb9cc1e0253f7d2fc1311b491071-8000.html

          Also check out the section “Using Native Extensions” in Oliver Goldman’s useful “Extending Adobe AIR” article: http://www.adobe.com/devnet/air/articles/extending-air.html#articlecontentAdobe_numberedheader_1

          Another note on using command line tools or your own IDE: if you’ve found an Adobe native extension example that provides an ANE file but doesn’t provide a library SWC, let me know. Our examples should support both of these workflows, though we encourage you to use Flash Builder 4.6, which is the easiest method.

          I’m also assuming you’re familiar with developing AIR applications, and aren’t just referring to Flash apps. Native extensions are an advanced feature of AIR, and also aren’t useful if you’re creating web content using Flash (and not packaging an APK, IPA, etc.).

          Does this help?

  5. Michael Baisuck says:

    Daniel,
    Thank you for the detailed response. I wish I could say that I now understand what to do. Unfortunately, while I am building AIR applications for Android, I’m doing so from within Flash. In other words, what I know how to do is select “Publish” and then wait for my app to appear on the phone I use for testing. I have never used Flash Builder and I never knew that AIR applications can be created through a command line interface.
    Currently, I am working with the Gyroscope example. (Christian Cantrellโ€™s โ€œCompassAppโ€ example does not come with an ANE or a SWC. It’s just a bunch of uncompiled, undocumented Flex and .java files that can be downloaded from GITHUB.)
    What I’m seeing when I unzip the Gyroscope example is a bunch of directories (AS, Binaries, Eg, Native Android, and Native IOS) with lots of sub-directories. Buried deeply in one of these directories, I’ve located the three .AS files (gyroscope.as, GyroscopeEvent.as, and GyroscopeIntervalValue.as). Buried in another directory, I located the Gyroscope.swc (and ANE) file… And then there’s all the other files that I don’t know what they are.
    I’d like to think I can just copy the AS files from where they are into my own project directory (without the 5 layers of sub-sirectories – “AS/src/com/adobe/nativeExtensions/…”) then link to the SWC in my Actionscript 3 settings, and then everything will just work (after I figure out how to utilize the AIR command line tools, of course)… But somehow I have the feeling that it’s not going to be that simple. Can you tell me what I’m missing? Is there a “AIR Native Extensions for Dummies” book out there somewhere? ๐Ÿ™‚
    I’m so sorry to be taking up your time like this, and I know I sound like an idiot. But I figure if I can get through this process once, I’ll better understand what needs to happen and I can duplicate the results for future projects.
    Thanks again for your seemingly infinite patience and understanding…
    Mike

    Back in the good ole’ days of Flash, non-programmers like myself would just need to paste in some code, or drop a new component into some directory, and then everything would work… My training as an artist and a designer (with a little scripting) was enough to undertake some fairly elaborate projects. Now it seems you have to have a background in software development to use your tools… What happened? ๐Ÿ™

  6. dkoestle says:

    No worries. This feature is very new, and I understand that more documentation would definitely be a good thing. Hopefully we’ll see some books coming out that discuss it (the feature is certainly complicated enough to warrant a full book!).

    Christan’s compass example indeed provides no binaries, so it’s expecting you to import three projects, and do a number of things with them:

    1. Import the Android library project and SDK
    2. Compile the Android code and create a JAR file
    3. Import the ActionScript library project and produce a SWC
    4. Package the SWC, the SWC’s library.swf, an JAR file into an ANE file
    5. Import the AS3 CompassApp (no Flex!), link to the SWC, package it with the ANE, and run it

    This is, as you can tell, a relatively involved workflow, especially if you’re unfamiliar with the process. The “Developing Extensions with Adobe AIR” document I linked you to earlier will help with all these steps, even though they won’t match exactly.

    Fortunately, you don’t have to use his project as your first ANE, and can use the Gyroscope example from the ADC. It sounds like you’ve already found it. The process when using that code is as follows:

    1. Ignore the AS, Eg, NativeAndroid, and NativeIOS folders. They’re only useful if you’re recompiling/repackaging everything (see above)
    2. Open the Binaries folder and import the Gyroscope.swc file into your Flash Pro project. This is the part that’s equivalent to dropping-in a library, which you can now reference from your other AS3 code. If you’re unfamiliar with how to add AS3 libraries in Flash Pro, go to Publish Settings, Flash, and click the settings button next to ActionScript 3.0. Add the SWC in the Library Path tab.
    3. You’re now able to reference the Gyroscope APIs, which are explained on the dev net site where you downloaded the zip file (http://www.adobe.com/devnet/air/native-extensions-for-air/extensions/gyroscope.html)
    4. Take the Gyroscope.ANE file (which contains the native extension code that makes it all work) and put it in the project directory. I’m not that familiar with how Flash Pro sets up the directories for AIR files, but it may go in the bin-debug folder, or in the project’s root folder.
    5. At this point you’d normally let Flash Pro take care of packaging your AIR app for you (when you click “Publish,” it’s doing a lot of work for you, automatically). At the moment you have to use command line tools to package your AIR application manually, however. The bad news is that this is more involved than clicking Publish, but the good news is that it’s a very common task, and has been done long before native extensions. Using Google and references like this one: http://help.adobe.com/en_US/air/build/WS62b4b4caef5f7931-1f86f0fb1328dba45c2-7fd4.html#WS62b4b4caef5f7931-1f86f0fb1328dba45c2-7fd3 you should be able to use the tool “adt” to specify the ANE file, your application descriptor, and your SWF, all of which will be bundled up for you and made into an APK/IPA.

    Steps one through four should be straight-forward and mostly familiar. Step five will require learning about the AIR command line tools and possibly setting up a batch file or shell script. Once you do it a few times, though, it’s not that bad.

  7. Michael Baisuck says:

    Daniel,
    I was looking at “gyroscope.as” and I noticed this line:

    ctx = ExtensionContext.createExtensionContext(“com.adobe.gyroscope”,null);

    This is a point of confusion for me since I don’t see any directory/file structures in the sample ZIP file that match “com.adobe.gyroscope”. I noticed the same thing with the “CompassApp” example: References to paths that don’t seem to exist.
    Obviously I’m reading this wrong but I can’t seem to figure out what my mistake is. I’ve looked through the documentation but all it says is that the extension ID is “The extension identifier of the extension. This identifier has the same value as the id element in the extension descriptor file…” I’m sure you can understand why this is not a very helpful definition for me. ๐Ÿ™
    I’m sorry to be throwing this all at you, but unfortunately for you, you are the only person from Adobe who has ever responded to my posts.
    Thanks again for your help.
    Mike

    • dkoestle says:

      Check out my reply above, but I can also explain that ID you’ve found:

      The extension context ID is a way that the native code (Objective-C, Java, etc.) can understand what context you want to create. In other words, your native code can have multiple contexts, and passing in that ID is the way you differentiate between them. This allows for very complicated yet organized native extensions. An extension that is called Sensors.ANE, for example, might look for the following IDs:

      com.example.sensors.gyroscope
      com.example.sensors.compass
      com.example.sensors.microphone
      etc.

      The code in each of these contexts will differ greatly enough that they warrant the creation of a new context, which keeps things from getting disorganized and bloated.

      If you look at this source file: Gyroscope.zip\Gyroscope\NativeAndroid\src\com\adobe\nativeExtension\GyroscopeExtension.java you’ll see createContext(String ctxType). That ctxType variable will contain “com.adobe.gyroscope”. If the Gyroscope ANE decided to have more than one context, you’d see a switch or an if statement checking ctxType and deciding which context to create. Since there is only one context, however, it ignores it and simply returns a GyroscopeExtensionContext.

      Oliver Goldman’s article “Extending Adobe AIR” (https://www.adobe.com/devnet/air/articles/extending-air.html) gets into the meaning and use of ExtensionContexts; these are part of the native side of ANEs, however, and more in-depth than you need.

      The string passed into the createExtensionContext() function will differ from extension to extension; it’s up to the developer to decide whether to ignore it or parse it. In the latter case, they should absolutely specify the expected value(s) in the documentation. In the former case, the value may be ignored due to being redundant.

      Where were you having difficulty getting your questions answered? You might want to also try on the Adobe Forums: http://forums.adobe.com/community/air (I’m not always available to answer comments on my posts, though I try to be.)

  8. Michael Baisuck says:

    Daniel,
    Thank you. I’ll go through this tomorrow and see if I can wrap my meager brain around this. In the meantime, let me say that you are a gentleman and a scholar and I sincerely appreciate your help and your patience.
    Thanks again.
    Mike

  9. Michael Baisuck says:

    Daniel,
    Well, you can’t say I didn’t try. ๐Ÿ™‚
    I got as far as the command-line ADT step. When I set everything up to the best of my ability and was finally was able to run the ADT program, I received this error:
    error 102: Invalid namespace http://ns.adobe.com/air/application/3.0
    Since I don’t know what the error is referring to, I’m pretty much stuck…

    The examples also aren’t clear on how to specify the ANE file as part of the package. Do I just add to to the list of items to be packaged? (I’m assuming I do need to package the ANE, despite the inclusion of the .swc file in the Library path.)

    I’m sorry to keep bugging you. For what it’s worth, if you can help me get through this, I’d be happy to document it in a way that other Flash Pro Purists can follow, and upload it for posterity.

    Thanks again for your seemingly inexhaustible patience. ๐Ÿ™‚
    Mike

    • dkoestle says:

      Sure, and that sounds like it’d be a useful document. I’d be happy to link to it from this article.

      It sounds like your application descriptor (my-app.xml) is specifying an AIR namespace (3.0) that adt doesn’t recognize. This could be because the version of AIR you’re using is out of date, and which doesn’t support the features of AIR 3.0 (such as native extensions). You should try getting the latest version of the AIR SDK and runtime, which are available here: https://www.adobe.com/special/products/air/sdk/ and here: http://get.adobe.com/air/, respectively. You’ll have to extract the SDK and put it alongside the existing AIR SDK you have. I’m not entirely sure where this is in Flash CS5, but it’s possible it’s in a folder called AIK, like this:

      C:\…\Adobe\Adobe Flash CS5\AIK2.0

      You could create an AIK3.0 (presumably) and edit your system path to point to the bin directory in this new location (alternatively, use absolute rather than relative directories in your shell script/batch file to explicitly point to the new version of adt that you just downloaded). You might want to look around for tutorials on this, since I’m not entirely sure of the procedure.

      As for packaging the ane, specifying a directory with the -extdir switch should be sufficient for ADT to find the .ane file that your application uses.

      Let me know if that works

  10. Michael Baisuck says:

    Hmmm. So, I’m pretty sure I already have the latest version of the AIR SDKs and runtime (3.0). However, the location of the SDKs is in Adobe Flash CS5.5\AIR2.6\. (When I try to change the name of the directory, nothing works anymore). Perhaps your advice about “editing my system path…” to point to a new directory would work – if I had the vaguest idea how to edit my system path. (I’m on a MAC, by the way.)
    (I’m assuming that the ADT program was updated when I updated to AIR3.)

    Also, sorry but you totally lost me on “As for packaging the ane, specifying a directory with the -extdir switch should be sufficient for ADT to find the .ane file that your application uses.” I’m not sure what directory you are referring to as I don’t know what an “-extdir switch” is.

    Sorry about this. I’m feeling stupider and stupider with each passing day. I hate to keep bothering you with this…

    • dkoestle says:

      Hmm, adt should’ve been updated, as well as the other parts of the runtime. If you’re executing adt from the command line on OS X, try running “which adt”, to see where it’s pointing. On OS X you can edit the path using echo $PATH and seeing what it contains, and then setting it with PATH=(value), however, it’d be easier if you used absolute paths, like this:

      /Applications/Adobe\ Flash\ Pro\ CS5/AIK/bin/adt

      I got that -extdir command from this tutorial:
      http://help.adobe.com/en_US/air/build/WS62b4b4caef5f7931-1f86f0fb1328dba45c2-7fd4.html#WS62b4b4caef5f7931-1f86f0fb1328dba45c2-7fd3

      Although that’s AIR for TV, the -extdir command is relevant to packaging a native extension. It’s a command line argument to the adt command. It might look like this:

      /Applications/Adobe\ Flash\ Pro\ CS5/AIK/bin/adt -package -storetype pkcs12 -keystore ../codesign.p12 myApp.air myApp-app.xml myApp.swf icons -extdir extension_directory/

      Again, it’s too bad you’re not using Flash Builder ๐Ÿ˜‰ This stuff certainly isn’t as straightforward as using a GUI tool.

      The namespace problem still sounds like it’s not using the correct version of the runtime, however. That should be the first thing you try to solve; Google should be helpful there, as there’s a lot more information on using command line tools than there is packaging native extensions (since it’s so new).

  11. Michael Baisuck says:

    Okay… So if I were going to try to use Flash Builder, does it actually work with Flash Pro? Or do I have to start a new career as a developer and learn the ins and outs of Flex?

    • dkoestle says:

      Well, Flash Builder lets you create pure AS3 applications, using no Flex at all. You can also create ones that run entirely in the browser (using the Flash plugin, and no AIR), or ones that work on desktop and mobile. There are certainly a number of differences, the most jarring of which will probably be that there’s no timeline or stage components. You can access the timeline in AS3 code as you normally do, as well as use Design View to visually lay out your app. To use it to solve this one problem will probably end up taking more time (I don’t think you’re far away from solving it using the command line tools…probably a step or two away from getting it to package and run), but if it’s something you’re otherwise interested in, it’s definitely worth learning.

      If want to focus heavily on creating mobile applications using AS3 and assets you drop in from Flash Pro, I recommend using Flash Builder. If you’re more comfortable with the timeline and stage, I recommend ironing out these packaging problems. Actually, you might want to package a hello world AIR app using Flash Pro and ADT, and once you get that working, switch to including native extensions using -extdir. (Though, as I said, I think you’re quite close to getting it to work.)

  12. Michael Baisuck says:

    test test

  13. Michael Baisuck says:

    test

  14. Michael Baisuck says:

    Sorry about that. I lost the ability to post for awhile there. (I had to download Chrome to continue our dialogue.)
    So anyway…
    I am getting closer.

    The error I’m currently dealing with is:
    “error 100: Descriptor cannot be parsed”

    So (assuming that the “descriptor” is that funky XML file that goes with the app (e.g. my-app.xml)) I wonder if you could take a look at this xml, and see if anything looks “off” to you.

    Gyroscope
    1.0.0
    Gyroscope

    Gyroscope

    Gyroscope.swf
    standard
    false
    true
    false
    false
    portrait
    cpu

    false
    false

    <![CDATA[]]>

    Thanks again.
    Mike

  15. Michael Baisuck says:

    Ooops! It seems as if my XML has been truncated. I’m going to try again….
    <!–

    Gyroscope
    1.0.0
    Gyroscope

    Gyroscope

    Gyroscope.swf
    standard
    false
    true
    false
    false
    portrait
    cpu

    false
    false

    <![CDATA[]]>

    –>

  16. Michael Baisuck says:

    darn…

    Gyroscope
    1.0.0
    Gyroscope

    Gyroscope

    Gyroscope.swf
    standard
    false
    true
    false
    false
    portrait
    cpu

    false
    false

    <![CDATA[]]>

  17. Michael Baisuck says:

    This is very unfortunate. I can’t seem to post the XML data for your review. Is there a way to attach a file to these posts???

  18. Michael Baisuck says:

    Hi Daniel,
    I tried rewriting my descriptor file from examples I found, but I’m still getting the same error:

    “…development/gyroscope/Gyroscope-app.xml: error 100: Descriptor cannot be parsed”

    I’m not sure where to go from here (especially considering I can’t paste the XML onto this blog.)

    Any advice?
    I can’t thank you enough for your continued assistance.
    Mike

  19. Michael Baisuck says:

    HELP!
    After three days of trying to create a damn ANE, I have come to the conclusion that the reason I am having so much trouble is that there is a very ambiguous part of the tutorial. I keep getting tripped up on the following sections:

    “The library.swf file needs to be placed inside of the native code directory for every platform you target. For example, you’d place this file inside iOS/, android/, x86/, etc., depending on your project’s targets….)”

    So, first of all, where is this “native code directory”? That concept just gets thrown into the mix without an explanation. My new FB project did not create it so where is that supposed to be and what should be in it?

    Secondly, in the same section, you go on to say “When complete, your HelloANELibrary folder should contain both HelloANELibrary.swc, and HelloANENative should contain library.swf.”

    I think the grammar on that sentence needs some work. It does not make sense. “Both” indicates that there are two things to put in the “HelloANELibrary folder” but only “HelloANELibrary.swc” is mentioned. This is followed by another reference (I assume) to the non-existant “native code directory”.

    Can you please, please, please clarify these points so I can continue trying to implement an ANE?
    Thank you very much for your time and attention.
    Sincerely,
    Mike