permadi.com

This IDG survey will help us understand your needs and focus our content, so please help us out by completing it:

“We’d like your help. We’re running a short survey to find out more about how to make you, our cherished readers, happy. If you can spare 10 minutes to answer a few questions we’ll be hugely grateful. In fact so grateful that we’ll pop your name into a draw to win one of 2 shiny new apple ipads. Now, isn’t that sweet?

If you’re willing to help us out, please click here to get going, and thank very much!”

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 VibrationNEDeliverables\ReadyToUseExtension 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 bin\TestANE-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: http://permadi.com/blog/2012/03/publishing-apk-with-air-captive-runtime-with-flash-ide/)

In our example, this is the command:

PATH_TO_ADT\adt -package -target apk-captive-runtime -storetype pkcs12 -keystore "YOUR_CERTIFICATE_FILE" -storepass YOUR_CERTIFICATE_PASSWORD "TestANE.apk" "bin\TestANE-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~2\Adobe\Adobef~1.5\adobef~1.5\AIR2.6\bin\adt is equivalent to C:\Program Files (x86)\Adobe\Adobe Flash CS5.5\Adobe Flash CS5.5\AIR2.6\bin 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.

Background

Captive Runtime is introduced in AIR 3.0 and it allows the AIR runtime to be packaged with your APK so that when user starts the Android version of your application, the user is no longer required to download and install the AIR runtime (this happens if the user does not already have the same runtime version installed). The drawback is that your application size gets larger. (AIR’s iOS output includes the runtime already).

Read more about Captive Runtime here: http://www.adobe.com/devnet/air/articles/air3-install-and-deployment-options.html.

While the Flash Builder and Flash Develop have added support for outputting Captive Runtime, the documentation is lacking on how to build APK with the Captive Runtime from within the Flash IDE. This article will show you some pointers on how to make an APK with Captive Runtime, using just the Flash CS5.5 IDE.

Requirements

Apart from the Android SDK, it is also assumed that you have already know how to output regular APKs.
To run this example, you need to have installed the AIR 3.0 or later. (When using Flash 5.5, the available AIR version is 2.5 and 2.6. Steps to update Flash IDE to AIR 3.1 are described here: http://kb2.adobe.com/cps/908/cpsid_90810.html.).

The Flag

In order to embed the captive-runtime in Flash CS5.5 IDE, you need to Publish your swf first, then run adt (Android Development Tools that comes with AIR) from the command line, and specifying flags to tell adt to include the Captive Runtime. The flag you want is:

-target apk-captive-runtime

For more details, see the section titled Creating an APK package that includes its own version of the AIR runtime here: http://help.adobe.com/en_US/air/build/WS901d38e593cd1bac-4f1413de12cd45ccc23-8000.html.
More documentations and other flags can be read from the Adobe doc here:
http://livedocs.adobe.com/flex/3/html/CommandLineTools_5.html
Also see: http://help.adobe.com/en_US/air/build/WS901d38e593cd1bac-4f1413de12cd45ccc23-8000.html

Example

Even after reading those, the confusion is where to run adt command from? ADT comes with the AIR SDK and mine is at C:\Program Files (x86)\Adobe\Adobe Flash CS5.5\Adobe Flash CS5.5\AIR2.6\bin\ (nevermind that it says 2.6, it’s actually AIR 3.1 because I followed the update instruction at http://kb2.adobe.com/cps/908/cpsid_90810.html). You can enter this into the path into the PATH environment variable in Windows in order to be able to run it anywhere, but I didn’t do that because I have multiple versions. Let’s go back to this later, just find where your adt is located for now.

Now going to the Flash IDE. Let’s say in Flash IDE, I have created this FLA, which is set to publish to AIR for Android (via the Flash IDE’s default UI). Here’s how I outputted the APK with Captive Runtime.

1) The first step is to publish using the Flash IDE (you can also do command line here, but let’s not complicate things further). It doesn’t really matter if the Player is set to AIR for Android or AIR for iOS because the SWF output is what you will really need, but just pick AIR for Android.

There is a catch here in that you should output the swf into a subfolder and I will tell you why later (in the Troubleshooting section). In my case, I output it to bin folder. Also put any external files there if your swf requires them.

2) Go ahead and Publish. You should get the output swf and an APK too (created by Flash IDE) from publishing in Step 1. Again, make sure that your output swf is in a subfolder (bin in my example). You can and should delete that APK because we’re going to create it ourself.

3) Open a command prompt and go to the folder where your FLA is. Run the adt from within that folder. An example is shown below. All below should be run as one line, and don’t forget the . at the end.

C:\Progra~2\Adobe\Adobef~1.5\adobef~1.5\AIR2.6\bin\adt 
  -package -target apk-captive-runtime 
  -storetype pkcs12 
  -keystore "YOUR_CERTIFICATE_FILE.p12" 
  -storepass YOUR_CERTIFICATE_PASSWORD 
  "CaptiveExample.apk" "bin\CaptiveExample-app.xml" -C bin .

Rather than typing everytime, I recommend making a .bat file to run the adt to build a release version, whenever you’re ready.

Some notes:

• Replace C:\Progra~2\Adobe\Adobef~1.5\adobef~1.5\AIR2.6\bin\ with the path to your adt. PS: When using command-line prompt, in Windows, you must use the DOS path-name, and C:\Progra~2\Adobe\Adobef~1.5\adobef~1.5\AIR2.6\bin\adt is equavalent to C:\Program Files (x86)\Adobe\Adobe Flash CS5.5\Adobe Flash CS5.5\AIR2.6\bin 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
• Replace YOUR_CERTIFICATE_FILE and YOUR_CERTIFICATE_PASSWORD with yours.
• Replace CaptiveExample.apk with whet your APK filename should be named (avoid spaces and weird characters).
• Replace CaptiveExample-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 XML file contains the filename of your output swf and other settings and looks something like this:

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

  There should be no need to change anything on this XML file.

• Add additional parameters as needed to the adt command. For example, if you use native extension, you need to specify it (would be nice if Flash IDE shows exactly what it is executing).

4) To install to a phone to test, make another batch file, containing something like this (adapted from a Flash Develop batch file).

adb devices
adb -d install -r CaptiveExample.apk

if errorlevel 1 goto installfail

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

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

pause

Replace CaptiveExample.apk with the name of your APK. Replace com.permadi.CaptiveExample with your APP_ID (must be the same as specified in the XML, which gets its value from the Flash IDE). Do not remove the air. prefix because AIR Android app always begins with that — at least I haven’t seen one that doesn’t. Note: What’s adb. It’s the Android Debug Bridge, which you should already have when you installed the Android SDK.

Example

Here’s a simple project that you can use to test: ZIP FIlE
There is a batch file named build.bat to build the captive version. You need to change the path to the adt and other parameters as described in Step 3. There’s also a batch file named run.bat to install and run on a device.

Troublshooting

First of all, remember that the example above only handles the simplest situations and if you use additional options (such as Native Interface) then you need to add them to the adt parameters. Start by using the simple example I provided above to get comfortable with the process. Having said, that, below are some errors that you should not encounter:

• If you’re getting this error:

  unexpected failure: inputs not set
  java.lang.IllegalStateException: inputs not set
          at com.adobe.air.ApplicationPackager.createPackage(ApplicationPackager.j
  ava:61)
          at com.adobe.air.ADT.parseArgsAndGo(ADT.java:557)
          at com.adobe.air.ADT.run(ADT.java:414)
          at com.adobe.air.ADT.main(ADT.java:464) 
  

  Make sure the . (period character) is not missing at the end of the adt command (step 3).

• If your APK output is excessively large (a movie without any code on it should not produce an APK larger than 9MB). This is very likely because you are including unintended files in the APK. Make sure to put files that you want to include in a subfolder (in my example, the swf is inside bin subfolder). Use the -C option when running the adt to tell it to use that folder. If not, the adt‘s temporary output file may be included in the output APK.

  Here’s a bloated APK example (PS: too see the content of an .APK you can rename it to .ZIP).

  
  See how there’s a lot of junk files (especially the giant 8MB .tmp from nowhere)? This is why you should never run apk from the same folder as your output swf. By the way, that weird tmp file is file created by adt when packing your app and it is NOT supposed to be part of the APK.

• You get:

  'c:\Progra~2\Flashd~2\tools\flexsdk\binn\aad' is not recognized as an internal or external command, operable program or batch file.
  
  

  This error is because the adt is not found. Make sure the path to adt is correct. In the example above, I mistyped bin.