Licensing Adobe AIR applications on Android

Note: Adobe recommends using the next version of Flash Builder for developing native extensions for Adobe AIR. Sign up now to get access to the prerelease of Flash Builder 4.6.

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

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).

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).

2. Choose File > New Java Project.
3. For the project name enter AndroidLicensingJavaProject (see Figure 2).

4. Click Finish.
5. 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).

6. 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.

7. 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.

8. Go to <Android SDK DIR>\extras\google\market_licensing\library\src, copy the com folder, and paste it in the src folder of your Java project.
9. 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\AndroidLicensingJavaProject\src inside the src folder of your Java project.

At this point your Java project should resemble Figure 4.

10. Compile the Java project; there should be no compilation errors.
11. 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).

4. 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.
5. Click Finish.
6. Go to the AIR SDK, copy the Flex library code from frameworks\projects\air\Licensing\Android\AndroidLicensingJavaProject\src\ to the src folder of your Flex Library Project.

7. 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:

8. 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.

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.

3. Click Next and then Finish.
4. 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).

5. 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).

6. To add a UI component to your project, switch to Design view and add a button, label it Check for License, and give the label an id of lbl.
7. Switch back to Source view and add a click handler to the button, in the listener function:

8. Be sure to import the ActionScript library classes using the following statement:

9. Next you write a response handler function for the checkLicense method call. Add the following function:

10. 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:

An Android permission is needed for all applications that perform a license check; you need to add it below the <manifest> tag:

Also be sure the application descriptor namespace is set to 3.0:

11. 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.

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.

On Windows

On Mac OS X

Generating the APK file

When you have the ANE file, use the following command to package the APK file:

On Windows

On Mac OS X

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.

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:

• Modify the following line in AndroidLicensingExtensionContext.java to match the new function name:

• 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:

Rename the SampleAndroidLicensing_o.jar to SampleAndroidLicensing.jar and use it in packaging ANE.

• Obfuscate the ActionScript code.

The following table covers some possible error messages and tips on how to resolve them:

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.