An Introduction to APM

[marchbold]

APM is the AIR Package Manager which allows management of AIR libraries and extensions and assists in creation of the application descriptor.

The initial goal of APM is simplify the setup and updating of an AIR application, in particular mobile applications, where the environment and SDKs (extensions) change rapidly.

Here I will show you how to create a new AIR application and use apm to add a dependency.

Installation

Installation is a manual process at the moment and is still a work in progress. To install firstly download the latest release from the apm releases and then follow the guide to setup your environment correctly. Basically the goal is to ensure you have:

• extracted the release to a location;
• made the location available in your PATH;

You need to ensure you have at least AIR SDK v33.1.1.554 installed.

Once installed you should be able to open a terminal and enter:

apm -version

This will output the version of the tool.

Create a Project

Firstly, let's create a directory for our project, you can create a new empty directory or you can use a new project directory created through an IDE. The key is to open a terminal at the location where you would normally place a src directory containing all your actionscript source code.

Let's initialise a new project by running apm init. This will run through some basic questions to setup the project configuration:

❯ apm init
Creating new project definition file
Application Identifier [com.my.app]: com.example.app
Application Name [My Application]: Example App
Application Version [1.0.0]: 1.0.0

Your directory will now contain a project.apm file. This is the file that contains all the information about your project including installed packages, versions and configuration values. You shouldn't need to edit this file directly but feel free to have a look at the contents (it is a json formatted text file).

Install a Package

Next let's search for a package to install. We will look for an "IDFA" extension to be able to get an advertising identifier for a user. Searching is done by calling apm search [query] so:

apm search IDFA

This will run as below and finds the com.distriqt.IDFA extension:

> apm search IDFA
✓ Search complete
found [1] matching package(s) for search 'IDFA'
└──com.distriqt.IDFA@5.0.31   The IDFA extension gives you simple access to the advertising identifiers on Android and iOS.

Let's go ahead and install this extension:

apm install com.distriqt.IDFA

This will get the details of the extension, and dependencies and install all the required extensions:

❯ apm install com.distriqt.IDFA
com.distriqt.IDFA@5.0.31
androidx.core@1.3.2
com.distriqt.playservices.AdsIdentifier@17.0.0
com.distriqt.playservices.Base@17.5.1
com.distriqt.Core@6.4.3
Installing package : com.distriqt.IDFA@5.0.31
✓ downloaded
✓ extracted
Installed package : com.distriqt.IDFA@5.0.31
Installing package : com.distriqt.playservices.Base@17.5.1
✓ downloaded
✓ extracted
Installed package : com.distriqt.playservices.Base@17.5.1
Installing package : com.distriqt.playservices.AdsIdentifier@17.0.0
✓ downloaded
✓ extracted
Installed package : com.distriqt.playservices.AdsIdentifier@17.0.0
Installing package : com.distriqt.Core@6.4.3
✓ downloaded
✓ extracted
Installed package : com.distriqt.Core@6.4.3
Installing package : androidx.core@1.3.2
✓ downloaded
✓ extracted
Installed package : androidx.core@1.3.2
✓ Deployed: com.distriqt.IDFA@5.0.31
✓ Deployed: com.distriqt.playservices.Base@17.5.1
✓ Deployed: com.distriqt.playservices.AdsIdentifier@17.0.0
✓ Deployed: com.distriqt.Core@6.4.3
✓ Deployed: androidx.core@1.3.2

You can see this extension has 4 dependencies:

• com.distriqt.playservices.Base
• com.distriqt.playservices.AdsIdentifier
• com.distriqt.Core
• androidx.core

Each of these is downloaded and installed along with the main com.distriqt.IDFA extension. Once complete you will have the following directory structure created:

|____apm_packages
|____ane
| |____androidx.core.ane
| |____com.distriqt.Core.ane
| |____com.distriqt.IDFA.ane
| |____com.distriqt.playservices.AdsIdentifier.ane
| |____com.distriqt.playservices.Base.ane
|____project.apm

The apm_packages directory is a cache directory, where apm keeps all your installed packages and details on them. The contents of this directory are used for apm operations so don't modify the contents of this directory. It is completely recreatable though by running apm install so you can add it to your .gitignore (or similar version control system) and just run apm install when starting development. Feel free to try that now, i.e. delete the apm_packages directory and run apm install. You should see something similar to the original install command output and the cache recreated.

Add to your IDE

Next lets open up your IDE and add the outputs from apm to your IDE.

In this case we have an ane directory containing the extensions. For example, in IntelliJ I would open up the module settings and add the ane directory as a dependency:

If you had installed a package with a SWC then you would also have a libs directory containing the swc files, and if you installed a package with source code then you may have a libs_src directory containing the package source code.

Similarly you should add these two directories to your build if they are present.

Check Configuration

Next you should check the project configuration to check if you want to make any changes to the configuration parameters that will be used for the extensions.

To do this run apm project config which will output all the current configuration parameters for your project:

> apm project config
userTrackingUsageDescription=Allows us to deliver personalized ads for you.

You will see there is one configuration parameter for the IDFA extension, which is the usage description that is used in the App Tracking Transparency dialog on iOS. If you wish to update it use the config set command: apm project config set <param> <value>

> apm project config set userTrackingUsageDescription "Better advertising for you."

Check it updated correctly by using:

❯ apm project config
userTrackingUsageDescription=Better advertising for you.

Generate the Application Descriptor

The next step which is particularly important for extensions, is to generate the application descriptor by calling apm generate app-descriptor. This will create an application descriptor with all the correct manifest additions, info additions and extensions for you to build your application.

The default is output to src/APPNAME-app.xml.

Note: If you already have an application descriptor at src/APPNAME-app.xml then it will be used as a template. The id, version, manifestAdditions, InfoAdditions, and Entitlements sections will be overwritten and the extensions will be corrected to ensure the required extensions are added.

❯ apm generate app-descriptor
Android package name: air.com.example.app
✓ Android manifest merge
✓ iOS additions merge complete
✓ iOS entitlements merge complete
✓ App descriptor generated: /Users/marchbold/exampleapp/src/ExampleApp-app.xml

Your application package name will be correctly inserted into appropriate spots, all permissions and manifest entries will be inserted and merged correctly and configuration parameters applied.

This creates the following:

<application xmlns="http://ns.adobe.com/air/application/33.1">
  <id>com.example.app</id>
  <versionNumber>1.0.0</versionNumber>
  <filename>ExampleApp</filename>
  <name>Example App</name>
  <initialWindow>
    <content>[]</content>
    <visible>true</visible>
    <fullScreen>false</fullScreen>
    <autoOrients>false</autoOrients>
    <renderMode>direct</renderMode>
  </initialWindow>
  <android>
    <manifestAdditions><![CDATA[<manifest android:installLocation="auto" >
  <uses-sdk android:minSdkVersion="19" android:targetSdkVersion="30"/>
  <!-- Required permission for App measurement to run. -->
  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  <uses-permission android:name="android.permission.WAKE_LOCK"/>
  <uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE"/>
  <!-- Required by older versions of Google Play services to create IID tokens -->
  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE"/>
  <application android:appComponentFactory="androidx.core.app.CoreComponentFactory">
    <provider android:name="androidx.lifecycle.ProcessLifecycleOwnerInitializer" android:authorities="air.com.example.app.lifecycle-process" android:exported="false" android:multiprocess="true"/>
    <provider android:name="androidx.startup.InitializationProvider" android:authorities="air.com.example.app.androidx-startup" android:exported="false"/>
    <receiver android:name="com.google.android.gms.measurement.AppMeasurementReceiver" android:enabled="true" android:exported="false"/>
    <service android:name="com.google.android.gms.measurement.AppMeasurementService" android:enabled="true" android:exported="false"/>
    <service android:name="com.google.android.gms.measurement.AppMeasurementJobService" android:enabled="true" android:exported="false" android:permission="android.permission.BIND_JOB_SERVICE"/>
    <activity android:name="com.google.android.gms.common.api.GoogleApiActivity" android:exported="false" android:theme="@android:style/Theme.Translucent.NoTitleBar"/>
    <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>
    <service android:name="com.google.firebase.components.ComponentDiscoveryService" android:exported="false">
      <meta-data android:name="com.google.firebase.components:com.google.firebase.analytics.connector.internal.AnalyticsConnectorRegistrar" android:value="com.google.firebase.components.ComponentRegistrar"/>
    </service>
  </application>
</manifest>
]]></manifestAdditions>
    <containsVideo>true</containsVideo>
  </android>
  <iPhone>
    <InfoAdditions><![CDATA[
<key>NSUserTrackingUsageDescription</key>
<string>Better advertising for you.</string>]]></InfoAdditions>
    <Entitlements><![CDATA[
]]></Entitlements>
  </iPhone>
  <extensions>
    <extensionID>com.distriqt.IDFA</extensionID>
    <extensionID>androidx.core</extensionID>
    <extensionID>com.distriqt.playservices.Base</extensionID>
    <extensionID>com.distriqt.playservices.AdsIdentifier</extensionID>
    <extensionID>com.distriqt.Core</extensionID>
  </extensions>
</application>

Get Coding

Now it is time to start writing code. You will see all the work of reading documentation and downloading the correct dependencies and adding manifest additions has been reduced to two commands:

apm install com.distriqt.IDFA
apm generate app-descriptor

Open up your IDE and start coding, (you may now have to refer to the documentation for usage of the package though :) )

package
{
	import com.distriqt.extension.idfa.IDFA;
	import com.distriqt.extension.idfa.TrackingAuthorisationStatus;
	import com.distriqt.extension.idfa.events.IDFAEvent;
	import flash.display.Sprite;

	public class ExampleApp extends Sprite
	{
		public function ExampleApp()
		{
			IDFA.service.addEventListener( IDFAEvent.COMPLETE, idfaCompleteHandler );

			IDFA.service.requestAuthorisation(
					function ( status:String ):void {
						if (status == TrackingAuthorisationStatus.AUTHORISED)
						{
							IDFA.service.getIDFA();
						}
					}
			);
		}


		private function idfaCompleteHandler( event:IDFAEvent ):void
		{
			trace( "identifier: " + event.identifier );
			trace( "isLimitAdTrackingEnabled: " + event.isLimitAdTrackingEnabled );
		}

	}
}