Migrating to the AIR Package Manager

[marchbold]

A case study of moving an existing project to APM

As with most AIR developers we support clients who have been using AIR in their applications for many years. They have an existing application code base structure and build systems in place that sometimes can make integrating new systems, like the AIR Package Manager (APM), a time consuming process.

In this guide we are going to run through a case study of converting one of these existing applications across to use the AIR Package Manager. Undoubtably this won't match exactly your setup, but we wanted to show how easy it can be to migrate even a large application across to APM.

Goal

Our goal with this initial integration is to utilise APM to manage the native extensions in use with this application. We will use APM to generate the required manifest additions and info additions in the application descriptor.

The application is a mobile application targeting iOS, Android and Amazon.

While this is a long document the process is very simple and there are only really 5 major steps.

• Initialisation
• Installation
• Configuration
• Manually Add Extensions
• Generate Application Descriptor

Approach

The application has the following basic structure at the top level:

|____ AppLibs
|____ AppServerAPI
|____ amazon
|____ android
|____ common
|____ ios

Each of the platforms has a separate directory with a common source tree and several shared libraries (AppLibs / AppServerAPI). 

The application descriptors are stored in each of the platform directories alongside the main application class for that platform.

|____ amazon
| |____ provisioning 
| |____ src
| | |____ assets
| | | |____ // amazon specific assets 
| | |____ App.as
| | |____ App-app.xml
|____ android
| |____ provisioning 
| |____ src
| | |____ assets
| | | |____ // android specific assets 
| | |____ App.as
| | |____ App-app.xml
|____ ios
| |____ provisioning 
| |____ src
| | |____ assets
| | | |____ // ios specific assets 
| | |____ App.as
| | |____ App-app.xml

The common directory contains the majority of the application source code along with all the ANEs for the application:

|____ common
| |____ ane
| | |____ // ANE files are here
| |____ src

All the ANEs are stored in one location, and each application may exclude some of them from the build as there are some slight differences between the platform implementations, particularly around supported advertising mediation networks. The ANEs being stored in a single location was just to make updating the extensions simpler however with apm we don't need to worry about this so much and instead we will have an ane directory inside each of the platform directories. We simply make a small change in our IDE to include the [platform]/ane directory in each project instead of the common/ane directory.

Due to these slight differences between the platform we have decided to create a separate apm project for each platform. While this adds a slight complexity to updating (i.e. having to update multiple projects), it gives us the flexibility to control specifics of the packages used in each platform.

Depending on your setup you may choose to do this as well or if you don't have any differences between the extensions packaged on the platforms it is simpler to use one project.

Process

Initialisation

Now for some magic! We can utilise the existing application descriptor and get apm to attempt to create a project for it. To do this we pass the path to the application descriptor to the init command. We run this in the platform directory, so lets move into the android directory and do this platform first:

apm init src/App-app.xml

Note we run this command in the android directory and have passed src/App-app.xml. This is so the project file is created at android/project.apm and not in the src directory.

This process will read the app xml and extract the application identifier, version and other information for the project definition and importantly, it will scan the extensions, attempt to identify matching packages and add the latest version to your project.

Creating new project definition file from application descriptor: App-app.xml
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✗ WARNING : Could not locate package for extensionID com.distriqt.Debug
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✗ WARNING : Could not locate package for extensionID com.distriqt.CustomResources
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✓ FOUND   : Package [email protected]
✗ WARNING : Could not locate package for extensionID com.amazon.extensions.GameCircle
Processing identified packages
✗ SKIPPING : Dependency: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✓ ADDING   : Package: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✗ SKIPPING : Dependency: [email protected]
✓ ADDING   : Package: [email protected]
✓ ADDING   : Package: [email protected]

This application is a decent size so contains a number of extensions and dependencies. 

You will note there are a couple of WARNING flags in there for extensions that it couldn't find: com.distriqt.CustomResources , com.distriqt.Debug and com.amazon.extensions.GameCircle. 

We will address these later in the section "Manually Add Extensions".

The process has gone through and identified all the extensions and we can check with apm list:

apm list 

[email protected] ~/work/application/android
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
├──[email protected]
└──[email protected]

The process skips all packages that are dependencies of another package. So this doesn't add things like the playservices and androidx libs, but unfortunately it has incorrectly skipped com.distriqt.IronSource as it is a dependency for the mediators eg com.distriqt.ironsource.AdColony. This won't affect anything as we have the mediators there for IronSource which will trigger the main extension installation but it is convenient to list it separately incase we remove the mediators later. So we will manually install this package later. We do hope to improve this, but currently it's just something to watch out for.

Installation 

Next we will trigger an install. 

apm install

This will download all the latest versions of the extensions and deploy them to the ane directory in our platform directory.

Once complete we will have 

|____ android
| |____ ane
| |____ apm_packages
| |____ project.apm
| |____ provisioning
| |____ src
| | |____ assets
| | | |____ // android specific assets 
| | |____ App.as
| | |____ App-app.xml

The ane directory contains all the downloaded extensions and the apm_packages directory is a cache directory used by apm. You can add this directory to your .gitignore (or equivalent), but do not delete it. apm will use this cache for certain operations and would need to download the package again if you delete it. 

At this point lets add that incorrectly skipped ironSource package:

apm install com.distriqt.IronSource

Configuration

Next we check the configuration to make sure we have correctly set any configuration items for the packages. We list the configuration parameters required by running apm project config :

apm project config

photoLibraryAddUsageDescription=Access to photo library is required to save images.
motionUsageDescription=
calendarsUsageDescription=
photoLibraryUsageDescription=Access to photo library is required to save images.
adMobIOSApplicationId=
adMobAndroidApplicationId=
playGamesAppId=XXXXXXXX
cameraUsageDescription=

There are several important pieces of information here, such as the AdMob application identifiers and the Play Games App Id. All these values would have been in your application descriptor previously but we need to inform apm of these values. To set a value:

apm project config set [NAME] [VALUE]

eg:

apm project config set adMobAndroidApplicationId ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY

Make sure you set values for all of the configuration:

adMobAndroidApplicationId=ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY
adMobIOSApplicationId=ca-app-pub-XXXXXXXXXXXXXXXX~ZZZZZZZZZZ
calendarsUsageDescription=Calendar usage description
cameraUsageDescription=Camera usage description
motionUsageDescription=Motion usage description
photoLibraryAddUsageDescription=Access to photo library is required to save images.
photoLibraryUsageDescription=Access to photo library is required to save images.
playGamesAppId=TTTTTTTTTTTT

Manually Add Extensions

Now we can address those extensions that aren't packages and need to be handled manually. Firstly just copy these extensions the the android/ane directory.

apm will remove extensions from this location but only ones that are unused dependencies or directly uninstalled, so these extensions will never be affected by apm.

Two of the extensions, com.distriqt.CustomResources and com.distriqt.Debug are simple extensions that don't require any manifest additions so once we have copied them across we are done with them. 

However com.amazon.extensions.GameCircle has some manifest additions. In order to add manifest entries with apm we create a new xml file at config/android/AndroidManifest.xml. This file is used to specify any additional manifest entries you require for your application. This file should have the following contents:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" >
    
    <uses-sdk 
        android:minSdkVersion="19" 
        android:targetSdkVersion="30" />

</manifest>

I immediately place the uses-sdk tag in here to make sure we are specifying the correct minimum and target SDK for android. This is a good file to create even if you don't have any other manifest additions, just to make sure you specify these SDK versions.

Now add the additions for the GameCircle ANE:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-sdk android:minSdkVersion="19" android:targetSdkVersion="30" />

    <application>

        <!-- AMAZON GAME CIRCLE -->
        <activity android:name="com.amazon.ags.html5.overlay.GameCircleUserInterface" android:theme="@style/GCOverlay" android:hardwareAccelerated="false"></activity>
        <activity android:name="com.amazon.ags.html5.overlay.GameCircleAlertUserInterface" android:theme="@style/GCAlert" android:hardwareAccelerated="false"></activity>
        <activity android:name="com.amazon.identity.auth.device.authorization.AuthorizationActivity" android:theme="@android:style/Theme.NoDisplay" android:allowTaskReparenting="true" android:launchMode="singleTask">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:host="air.application.id" android:scheme="amzn" />
            </intent-filter>
        </activity>
        <receiver android:name="com.amazon.identity.auth.device.authorization.PackageIntentReceiver" android:enabled="true">
            <intent-filter>
                <action android:name="android.intent.action.PACKAGE_INSTALL" />
                <action android:name="android.intent.action.PACKAGE_ADDED" />
                <data android:scheme="package" />
            </intent-filter>
        </receiver>

    </application>

</manifest>

These will now be merged with the other extensions manifest additions automatically. 

One thing to note here is the usage of the application package name in the manifest additions (air.application.id). You can leave that as is without any issues, however if you replace it with ${applicationId} then the merge process will insert it automatically for you and will make it easier for you to copy these additions into another project. 

So now we have:

|____ android
| |____ ane
| |____ apm_packages
| |____ config
| | |____ android
| | | |____ AndroidManifest.xml
| |____ project.apm
| |____ provisioning
| |____ src
| | |____ assets
| | | |____ // android specific assets 
| | |____ App.as
| | |____ App-app.xml

If this was an iOS application with info additions we would have added config/ios/InfoAdditions.xml with the following content (the usage description string is just an example):

<plist version="1.0">
  <dict>
  
    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>Some description string.</string>
    
  </dict>
</plist>

Generate Application Descriptor

Now we have actually completed the conversion to apm for the android project! We can use apm to generate the application descriptor. This is important to do now as during the above process you will likely have updated the extensions to their latest versions which may have had manifest changes.

Before we do this, if you aren't using version control, make a backup of your existing application descriptor. This process will modify it.

To generate the app descriptor we call apm generate app-descriptor and pass the location of the current application descriptor:

apm generate app-descriptor src/App-app.xml

Merging with supplied main manifest: config/android/AndroidManifest.xml
Android package name: air.application.id
✓ Android manifest merge
✓ iOS additions merge complete
✓ iOS entitlements merge complete
✓ App descriptor generated: /XXX/android/src/App-app.xml

At this point we open up our IDE and check that the application launches and runs as expected. The only change we have made to the build configuration is the relocation of the ane directory.

We then repeat this process with the other platforms.

---

Summary

In this case study we have shown how to migrate an existing project to apm.

1. Initialise using your existing application descriptor: 

apm init src/App-app.xml

2. Install the packages:

apm install

3. Set configuration parameters

4. Handle any extensions that couldn't be located as manually add extensions

5. Generate your application descriptor

apm generate app-descriptor src/App-app.xml

You now have an active apm managed project that you can use to simply add and update packages and most importantly, never again struggle with manifest additions!

---

Thanks for reading and if you have any questions you can reach out at the apm discussion forum.

[jimmymjing]

Hi, I throughly read through this post and thought the structure is excellect. I just mimic the steps and basically made 3 modules in Intellij (Android, iOS and common). I set common as a shared lib. Everything is cool and I could compile and run debug/release apk and ipas, but I just have few questions.

The first question is about the common folder. It says The common directory contains the majority of the application source code along with all the ANEs for the application in the post. But as anes have dependencies, if I have to manage 3 apms, there must be a lot of duplicated ANEs like the core.ane. I have no idea how to make them coexsit and then include them into IntelliJ.

The second question is about shared code and assets. I have no issues to include them from common module into android/ios modules, but the released game's frame rate is horriable! Is it a common knowledge that code efficency suffers with shared code? Please let me know if it is simply my own issue.

My last question is probably IntelliJ specific. I find that the provisioning profile and p12 file are not related to a build profile. So I have to manually switch among adhoc/release/debug. Is it a common flow for IntelliJ?

[marchbold]

1. In our migration we removed the ane's from the common directory and moved them into the project specific directories. In intellij we simply added the ane directory in the platform implementation to the module as a dependency. There is an ane directory for each of the platforms but we could add this directory individually to the intellij config. There shouldn't be an apm project for the common dir only for each platform.

2. Definitely something is wrong in your build, a shared library or common source folder should have absolutely no effect on the framerate.

3. In IntelliJ provisioning is set in the modules settings. You can setup multiple module settings configurations for a module allowing you to specify different build configurations (eg with a app store profile and a debug profile or for a different store)