ActionScript
Using ANE (Air Native Extension) in Flash Professional IDE
March 10, 2012
0

Background

This is a quick walk trough on how to use ANE (AIR Native Extension) in Flash Professional CS5.5. I assume you know what ANE is, but if you want, you can read Abode’s overview here http://help.adobe.com/en_US/air/extensions/index.html. ANE it basically a method to call native code from within Adobe AIR applications.

To use Native Extension, you need to have AIR 3.0, which you can install to Flash Professional CS5.5 by following Adobe’s guide here: http://kb2.adobe.com/cps/908/cpsid_90810.html.

Example

For this article, I’m going to use one of Adobe’s example, the Vibrator extension.

1. Create a blank Flash movie. Add a button on the stage, name the instance button. Save the FLA as TestANE.fla.

2. Download the Vibrator files from Adobe: http://download.macromedia.com/pub/developer/air/ane/Vibration.zip. Article: http://www.adobe.com/devnet/air/native-extensions-for-air/extensions/vibration.html

3. Extract the Vibrator files. Then copy the files from VibrationNEDeliverablesReadyToUseExtension folder (You’ll see .swc, .ane, .txt files). Copy those files to the a lib subfolder where you have the FLA created in Step 1. You can open the extensionID.txt to see the package name of the ANE.

4. Add the swc file from the ANE into the Flash project.

5. Add a document class to your FLA

In this example, I’m calling the document class TestANE.

6. Edit TestANE.as. For this simple example, our app will do nothing but call the extension when the button is tapped.

Import the ANE package using this line:

	import com.adobe.nativeExtensions.Vibration;

Then, add the code to handle tap (mouse click).

button.addEventListener(MouseEvent.CLICK, onClicked);

private function onClicked(event:Event):void
{
  // we will fill this later
}

7. Now, there’s a slight issue. We don’t know what methods and classes are available in the ANE. There are several options here: 1) read documentation that comes with the ANE to see what methods are available in the ANE, at http://www.adobe.com/devnet/air/native-extensions-for-air/extensions/vibration.html.
b) expand the ANE in FlashDevelop by adding it to a project and bouble clicking on it.

There, you can see:

package com.adobe.nativeExtensions
{
	import flash.external.ExtensionContext;

	public class Vibration extends Object
	{
		public static function get isSupported () : Boolean;

		public function vibrate (duration:Number) : void;

		public function Vibration ();
	}
}

So let’s roll. Go back to our TestANE.as and edit the onClicked() method:

private function onClicked(event:Event):void
{
  var vibe:Vibration;
  if (Vibration.isSupported)
  {
    vibe = new Vibration();
    vibe.vibrate(1000);
  }
}

Always check whether the extension is available by calling isSupported. Most well built extension has this method.

So now the full content of TestANE.as is as follows:

package  {

	import flash.display.MovieClip;
	import com.adobe.nativeExtensions.Vibration;
	import flash.events.MouseEvent;


	public class TestANE extends MovieClip {


		public function TestANE()
		{
			button.addEventListener(MouseEvent.CLICK, onClick);
		}

		private function onClick(event:MouseEvent):void
		{
			if (Vibration.isSupported)
			{
				var vibration:Vibration=new Vibration();
				vibration.vibrate(1000);
			}
		}

	}

}

8. Publish. Make sure to publish to a subfolder. Below I’m publishing to bin subfolder.

9. If you try running the resulting output, you’ll get an error. Modify the build settings to acommodate the ANE. Add the tag into to the build settings XML (in my case, it’s at binTestANE-app.xml:

<extensionID>com.adobe.Vibration</extensionID>

If you read this particular extension documentation, there’s one permission that you need to add to allow Android devices to vibrate:

<uses-permission android:name="android.permission.VIBRATE"/>

So, edit applications.xml (this is the default xml used by Flash Develop when packaging your app) so that it looks something like this:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<application xmlns="http://ns.adobe.com/air/application/3.1">
  <id>TestANE</id>
  <versionNumber>1.0.0</versionNumber>
  <versionLabel/>
  <filename>TestANE</filename>
  <description/>


<!-- To localize the description, use the following format for the description element.<description><text xml:lang="en">English App description goes here</text><text xml:lang="fr">French App description goes here</text><text xml:lang="ja">Japanese App description goes here</text></description>-->

  <name>TestANE</name>

<!-- To localize the name, use the following format for the name element.<name><text xml:lang="en">English App name goes here</text><text xml:lang="fr">French App name goes here</text><text xml:lang="ja">Japanese App name goes here</text></name>-->

  <copyright/>

  <initialWindow>
    <content>TestANE.swf</content>
    <systemChrome>standard</systemChrome>
    <transparent>false</transparent>
    <visible>true</visible>
    <fullScreen>false</fullScreen>
    <aspectRatio>portrait</aspectRatio>
    <renderMode>cpu</renderMode>
    <autoOrients>false</autoOrients></initialWindow>

  <icon/>

  <customUpdateUI>false</customUpdateUI>

  <allowBrowserInvocation>false</allowBrowserInvocation>

  <android>
    <manifestAdditions>

      <![CDATA[<manifest>
<uses-permission android:name="android.permission.VIBRATE"/>
</manifest>]]>
    </manifestAdditions>
  </android>
<extensions>
<extensionID>com.adobe.Vibration</extensionID>
</extensions>

</application>

Make sure you can spot where I added the two entries.

10. Build using adt because unfortunately Flash CS5.5 IDE currently does not support doing this directly from the IDE. (More info on running adt can be read here: https://permadi.com/blog/2012/03/publishing-apk-with-air-captive-runtime-with-flash-ide/)

In our example, this is the command:

PATH_TO_ADTadt -package -target apk-captive-runtime -storetype pkcs12 -keystore "YOUR_CERTIFICATE_FILE" -storepass YOUR_CERTIFICATE_PASSWORD "TestANE.apk" "binTestANE-app.xml" -C bin . -extdir lib/

PS: You might encounter this message when publishing from Flash IDE after adding the above. This can be ignored because what this says is that the extension does not work on your Desktop machine, which is true (do you know of a desktop computer that support vibration, ha?):

  • Replace PATH_TO_ADT with the path to your adt. PS: When using command-line prompt, in Windows, you must use the DOS path-name, and C:Progra~2AdobeAdobef~1.5adobef~1.5AIR2.6binadt is equivalent to C:Program Files (x86)AdobeAdobe Flash CS5.5Adobe Flash CS5.5AIR2.6bin which where I have AIR SDK installed. This value depends on where you installed AIR ASK, so you can’t just copy that path. If you don’t know how to get the DOS name, this might help: http://answers.google.com/answers/threadview/id/522710.html
    PS: Reader Dave alerted me that you can use the long path name by putting it in quotes. Thanks.
  • Replace YOUR_CERTIFICATE_FILE and YOUR_CERTIFICATE_PASSWORD with yours.
  • Replace TestANE-app.apk with whet your APK filename should be named (avoid spaces and weird characters).
  • Replace TestANE-app.xml with your application XML (this file is created by Flash IDE when you set target to AIR for Android or AIR for iOS; this was also the file we edited in Step 8).
  • lib/ is the folder name where I copied the ANE files in step 3.

If there’s no error, the output APK can be run on a Device (the emulator won’t Vibrate and most ANE won’t run on the Emulator). For iOS, you can do the usual iTunes or TestFlight route. For Android, the command is something like this from the command line (this is adapted from a Flash Develop batch file):

adb devices
adb -d install -r TestANE.apk

if errorlevel 1 goto installfail

echo.
echo Starting application on the device for debugging...
echo.
adb shell am start -n air.TestANE/.AppEntry

:installfail
echo.
echo Installing the app on the device failed

pause

Remember to replace TestANE.apk with your APK filename and air.TestANE with air.YOUR_APP_ID.

If everything goes well, your phone should vibrate when tapped (note: iPad and iPod Touch does not support vibration as far as I know).

Download Example

Sample to download (contains portion from Adobe at http://www.adobe.com/devnet/air/native-extensions-for-air/extensions/vibration.html). Note: Edit build.bat to recompile.