Requirements
Prerequisite knowledge
Familiarity with native extensions in Adobe AIR on Android, Java, and Android Licensing Verification Library (LVL)
Required products
Flash Builder 4.7 Premium (Download trial)
Adobe AIR 3
User Level
Intermediate

This tutorial shows you how to use and package the native extension for Android licensing, including tips for securing your application.
 

 
Understanding Android licensing in Adobe AIR

The Android Licensing native extension provides AIR application developers access to the Android Market Licensing service. This service helps you enforce licensing policies for paid applications that you publish through Android Market. When using this service, your application can query Android Market at runtime to obtain the licensing status for the current user and then permit or prohibit further use.
 
  • The AIR application uses a native extension to access the Android Market Licensing service.
  • The native extension uses the License Verification Library (LVL) to talk to the Android Market licensing server and pass the result back to the AIR application.
  • The native extension library sends the request to the LVL and will provide the response to the application.
  • You can modify the LVL and the source code for SWC provided in AIR SDK. For example, you may want to change the LVL code if you want to implement your own custom policy for Android Licensing. (By default, LVL uses a server-based policy).

 
Using Android licensing native extensions

Before you begin: verify that your copy of Flash Builder has the Java Development Tools (JDT) installed. You need the JDT to edit Java code in Flash Builder. For details on how to install JDT, follow the steps in Jason's Flex blog post on Java development in Flash Builder.
 
To use the native extension for Android Licensing, you need to create:
 
  • A Java project
  • An ActionScript library
  • The AIR application
 
Creating the Java project
To create the Java project follow these steps:
 
  1. Launch Flash Builder and select Java perspective (see Figure 1).
Select Java perspective in Flash Builder.
Figure 1. Select Java perspective in Flash Builder.
 
  1. Choose File > New Java Project.
  2. For the project name enter AndroidLicensingJavaProject (see Figure 2).
Enter a name for your new Java project.
Figure 2. Enter a name for your new Java project.
 
  1. Click Finish.
  2. To reference the Google Android APIs, right-click your Java project, and then select Properties, then Java Build Path in the left panel, and then click the Libraries Tab on the right panel (see Figure 3).
Adding External JAR files.
Figure 3. Adding External JAR files.
 
  1. Click Add External JARs and point it to the android.jar file from your Android SDK directory: <Android SDK DIR>\platforms\android-11\android.jar.
    Note: Using the latest Android API level directory is recommended.
     
  2. Create a reference to FlashRuntimeExtensions.jar from the Adobe AIR SDK: <AIR SDK DIR>\lib\android\FlashRuntimeExtensions.jar.
    You now need to copy the LVL available with the Google Android SDK to your Java src project.
     
  3. Go to <Android SDK DIR>\extras\google\play_licensing\library\src, copy the com folder, and paste it in the src folder of your Java project.
  4. After linking to all the external libraries, you now need the AIR native extension code in our Java project.
    Go to AIR SDK, and copy the com folder from <air_sdk_dir>\frameworks\projects\air\Licensing\Android\java\src inside the src folder of your Java project.
     
  5. At this point your Java project should resemble Figure 4.
     
Package Explorer for your Java project in Flash Builder
Figure 4. Package Explorer for your Java project in Flash Builder
 
  1. Compile the Java project; there should be no compilation errors.
  2. Right-click your Java project and select Export, then Jar inside Java, and then rename the Jar file SampleAndroidLicensing.jar.
 
Developing the ActionScript library
After setting up your Java project for the native extension, you need to create an ActionScript library that enables the communication between Java code and your AIR application on runtime.
 
Later, you will be referencing this ActionScript library in your AIR application.
 
  1. To develop ActionScript projects, choose the Flash perspective in Flash Builder. Before continuing, be sure you've overlaid the latest AIR SDK in Flash Builder.
  2. Choose File > New > Flex Library Project.
  3. For the project name type AndroidLicensingLib (see Figure 5).
Type a name for your new Flex Library Project.
Figure 5. Type a name for your new Flex Library Project.
 
  1. Be sure you select the check box Include Adobe AIR libraries, otherwise the Flash.external.ExternalContext API will not be available to your ActionScript library.
  2. Click Finish.
  3. Go to the AIR SDK, copy the Flex library code from frameworks\projects\air\Licensing\Android\lib\src\ to the src folder of your Flex Library Project.
  4. You also need to set your developer public key in your Flex Library Project which is required for communication between your AIR application and the Android Market server.
     
    Sign in your Google Android Market Portal, copy the public key and set it to the BASE64_PUBLIC_KEY variable in the LicenseChecker.as file:
     
// Add the Public key obtained from Android Market here private static const BASE64_PUBLIC_KEY:String = "";
  1. Compile your Flex Library Project; you should see the AndroidLicensingLib.swc in the bin folder of the project. At this point, your Project Explorer should look like Figure 6.
Flash Builder Project Explorer showing the Java and Flex projects.
Figure 6. Flash Builder Project Explorer showing the Java and Flex projects.
 
 
Developing the sample AIR app
Next you create the AIR app that will use Android Licensing via the native extension that you've just created.
 
  1. Choose File > New > Flex Mobile Project.
  2. Enter a project name type; I used AndroidLicensingUsage (see Figure 7).
     
    Be sure not to use the same project name as this ID is already used in Google Android Market.
     
Type a name for your Flex Mobile AIR Project.
Figure 7. Type a name for your Flex Mobile AIR Project.
 
  1. Click Next and then Finish.
  2. Next you need to add a reference to the ActionScript Library you developed above. Right-click this project, chose Properties, and then select Flex Build Path on the left panel. Click Add SWC and point to the AndroidLicensingLib.swc of the AndroidLicensingLib project (see Figure 8).
Referencing the SWC to your Flex Mobile Project.
Figure 8. Referencing the SWC to your Flex Mobile Project.
 
  1. Change the link type of the SWC to External; double-click the Link Type and choose External from the popup menu and click Ok (see Figure 9).
Set the link type to External.
Figure 9. Set the link type to External.
 
  1. Add a Label, with id lbl and a button to your project.
<s:Button x="10" y="10" width="200" height="50" label="Check for License" click="launch_clickHandler(event)"/> <s:Label x="10" y="200" width="400" height="50" text="label text" id="lbl"/>
  1. Next add a click handler to the Button, in the listener function.
protected function launch_clickHandler(event:MouseEvent):void { var lc:LicenseChecker = new LicenseChecker(); lc.addEventListener(LicenseStatusEvent.STATUS,licenseResult); lc.checkLicense(); }
  1. Be sure to import the ActionScript library classes using the following statement:
import com.adobe.air.sampleextensions.android.licensing.*;
  1. Next you write a response handler function for the checkLicense method call. Add the following function:
protected function licenseResult(event:LicenseStatusEvent):void{ lbl.text = "status: " + event.status + " statusReason: +" + event.statusReason; if (event.status == LicenseStatus.LICENSED) { //Application is licensed, allow the user to proceed. } else if (event.status == LicenseStatus.NOT_LICENSED) { //Application is not licensed, don't allow to user to proceed. switch (event.statusReason) { case LicenseStatusReason.CHECK_IN_PROGRESS: // There is already a license check in progress. break ; case LicenseStatusReason.INVALID_PACKAGE_NAME: // Package Name of the application is not valid. break ; case LicenseStatusReason.INVALID_PUBLIC_KEY: // Public key specified is incorrect. break ; case LicenseStatusReason.MISSING_PERMISSION: // License Check permission in App descriptor is missing. break ; case LicenseStatusReason.NON_MATCHING_UID: // UID of the application is not matching. break ; case LicenseStatusReason.NOT_MARKET_MANAGED: // The application is not market managed. break ; default: // Application is not licensed. } } }
  1. The following changes are required in the application descriptor when writing an AIR application that uses a native extension for Android Licensing.
     
    Add an Extension ID tag following the application tag:
     
<extensions> <extensionID>com.adobe.air.sampleextensions.android.licensing</extensionID> </extensions>
An Android permission is needed for all applications that perform a license check; you need to add it below the <manifest> tag:
 
<uses-permission android:name="com.android.vending.CHECK_LICENSE"/>
Also be sure the application descriptor namespace is set to 3.0:
 
<application xmlns="http://ns.adobe.com/air/application/3.0">
  1. Compile the application. This generates a SWF/XML in the output (bin-debug) folder.
Note: The SWF generated here is a debug SWF. One of the ways to do this in Flash Builder (regardless of AIR or web project, or whether the export is available) is to add an argument to the compiler options. To do this go to: Project > Properties > Flex Compiler and then add -debug=false" to Additional compiler arguments.
 
To summarize, this application will perform a license check when the button is clicked, and print the response in the label text.
 

 
Packaging Android native extension and your application

For your own projects, be sure to also read through the next section which has recommendations on securing your application.
 
To package your app you need following files:
 
  • JAR file, generated from the Java project (here, SampleAndroidLicensing.jar)
  • SWC file, generated from the ActionScript Library project (here, AndroidLicensingLib.swc)
  • SWF/XML files of AIR application, generated from your Flex Mobile Project (here, AndroidLicensingUsage.swf and AndroidLicensingUsage-app.xml)
  • extenson.xml (a sample file that you can fine at frameworks\projects\air\Licensing\Android\AndroidLicensingLib\src\ in the AIR SDK)
Create a workfolder called PackageAL, copy all these files into this folder, and then use the ADT tool (available with the AIR SDK) to package the application.
 
 
Generating the ANE file
  1. Change the directory on command prompt to point to the work folder you just created, and create a folder here called Android-ARM.
  2. Copy the SampleAndroidLicensing.jar file to the Android-ARM directory.
  3. Extract AndroidLicensingLib.swc by unzipping it, copy the file library.swf to the Android-ARM directory, then remove catalog.xml; do not remove AndroidLicesingLib.swc.
  4. Use the following ADT command to package the ANE file.
  5. On Windows
     
<Full Path to adt.bat> -package -storetype PKCS12 -keystore <path to Certificate for Native Extension> -storepass <password> -target ane com.adobe.air.sampleextensions.android.licensing.ane extension.xml -swc AndroidLicensingLib.swc -platform Android-ARM -C .\Android-ARM\ .
    On Mac OS X
     
<Full Path to adt> -package -storetype PKCS12 -keystore <path to Certificate for Native Extension> -storepass <password> -target ane com.adobe.air.sampleextensions.android.licensing.ane extension.xml -swc AndroidLicensingLib.swc -platform Android-ARM -C ./Android-ARM/ .
 
Generating the APK file
When you have the ANE file, use the following command to package the APK file:
 
On Windows
 
<Full Path to adt.bat> -package -target apk -storetype PKCS12 -keystore <path to Certificate for AIR application> -storepass <password> AndroidLicensingUsage.apk AndroidLicensingUsage-app.xml AndroidLicensingUsage.swf –extdir .
On Mac OS X
 
<Full Path to adt> -package -target apk -storetype PKCS12 -keystore <path to Certificate for AIR application> -storepass <password> AndroidLicensingUsage.apk AndroidLicensingUsage-app.xml AndroidLicensingUsage.swf –extdir .
Note: If you want to see traces in device logcat, please change the target to apk-debug.
 
Users of your application will receive the response "Licensed" when you've published your application to market and they've purchased the application from Google Android Market.
 

 
Tips for securing your application

Refer to the follow in tips to make your application more secure:
 
  • Do not share the Android Market Portal public key with anyone.
  • Change the function name "checkLicenseNative" in the following line in LicenseChecker.as to some other name:
var retValue:int = extContext.call( "checkLicenseNative", BASE64_PUBLIC_KEY ) as int;
  • Modify the following line in AndroidLicensingExtensionContext.java to match the new function name:
functionMap.put("checkLicenseNative", new AndroidLicensing() );
  • Improve the SALT variable in AndroidLicensing.java as necessary.
  • Obfuscate the SampleAndroidLicensing.jar file after it is generated before packaging the ANE. JAR files can be obfuscated using the ProGuard tool. You can use the configuration file (licensing.pro) that accompanies this tutorial to obfuscate the JAR file:
java –jar <Path to ProGuard.jar> @licensing.pro
    Rename the SampleAndroidLicensing_o.jar to SampleAndroidLicensing.jar and use it in packaging ANE.
     
  • Obfuscate the ActionScript code.

 
Troubleshooting your application

The following table covers some possible error messages and tips on how to resolve them:
 
Error message How to resolve
Invalid Key Specification Error (from LVL in logcat)
 
Be sure you've provided the exactly same key that is available in your Google Android Market portal.
 
missingPermission (statusReason)
 
Check if you've provided the Android Permission for Check License in the application descriptor.
 
notMarketManaged (statusReason)
 
The ID is not recognized by the Google Android Market application, because an application with this ID has never been uploaded to Google Android Market. Upload the proper application.
 
Error contacting licensing server (from LVL in logcat)
 
Be sure you've logged in once in the market application of your Android phone. Also make sure your device has a working internet connection.
 

 
Where to go from here

In this example, you have learned how to use the AIR native extension for Licensing your Android applications. To learn more about ANEs, go to the Native extensions for Adobe AIR page in the AIR Developer Center.