DEV Community: Michael

Accessing User GDPR Settings in AIR

Michael — Wed, 15 Jun 2022 01:27:13 +0000

At some point in your application development when you start to store and share data you will need to handle user GDPR settings.

The General Data Protection Regulation (GDPR) is a European Union (EU) regulation that mandates how an organisation should handle personal data.

If you use personalised advertising or store user related data on your server then you will need to address GDPR concerns in your application.

On mobile devices the GDPR settings are stored through the IAB Europe Transparency & Consent Framework. This framework ensures settings are stored in consistent places for developers to access and determine their appropriate behaviour for the user.

These values are stored in NSUserDefaults on iOS and in SharedPreferences on Android.

With the AIR SDK we can access these values easily through the Application extension. The Application extension allows access to the NSUserDefaults and the SharedPreferences through the defaults functionality.

Firstly, we set the useSharedDefaults flag to ensure we use the application's shared values.

Application.service.defaults.useSharedDefaults = true;

If we don't set this flag, then the values retrieved through the defaults functionality will be isolated from values set via other methods and you won't retrieve the correct TC data values.

Once you have set this flag you can retrieve any of the TC data from the framework by using the appropriate key.

For example:

var value:String = 
    Application.service.defaults.
        getString( "IABTCF_TCString" );

You can then use this value as required for your implementation of GDPR in your application.

For a full list of the available keys and a description of the values and types see the documentation here.

Updating an AIR Project using APM

Michael — Wed, 01 Jun 2022 23:34:17 +0000

How to update an application using air packages

In this tutorial we are going to run through how to update an application that has been setup to use the AIR Package Manager.

This assumes you have got your AIR project running with apm. If you haven’t have a look at the following tutorials:

Updating a project that has been setup with apm is one of the most powerful things about the AIR Package Manager.

Previously you would have had to go to the site distributing the ANE, download the ANE, check for updates to any dependencies and download them. Then you would have to check the documentation and sift through your manifest additions and info additions to check if any updates are required. This is all before you can even start to check for any code changes required. Obviously it was a painful process and one we at distriqt were all too aware of.

So lets look at what we do with apm.

In this example I have 2 packages installed:

My Application@1.0.0 /Users/marchbold/work/myapp
├──com.distriqt.facebook.Core@9.3.1
└──com.distriqt.IDFA@5.0.31

Outdated Packages

Firstly we can quickly see if there is an update available by using the outdated command:

apm outdated

This check the installed packages for updates in the repository:

$ apm outdated

identifier                  installed    available
com.distriqt.facebook.Core  9.3.1        9.3.2
com.distriqt.IDFA           5.0.31       5.0.31

From this we can see that there is a new version of the com.distriqt.facebook.Core package available. It is a patch release (last digit in the sem ver) so will only contain bug fixes and minor updates and shouldn’t require any changes to the API (though there may be manifest changes or other such additions).

Using outdated isn’t necessary, it is just information that you can use to decide whether you want to update or not.

Update Packages

Now that we know there is an update and we have decided to update our packages we move to the update command.

Open up a terminal in the project directory, and run the help update process to print out the details on the update command:

$ apm help update

apm update

update the installed packages in your project

apm update apm       check for a new release of the apm client and update if available
apm update           update all dependencies in your project
apm update <foo>     update the <foo> dependency in your project

You will see there are several options here, the first is to update the apm client (more on this later). The other commands allow you to update packages. If you pass a parameter you can specify a package to update, eg:

apm update com.distriqt.IDFA

would check to see if there are any updates to the IDFA extension and install them if available.

Alternatively you can just run update without any parameters:

apm update

This process will firstly check with the repository for the latest versions of all your packages and then update them as required.

Lets run this now.

apm update

You will see apm going through and checking the versions of all the extensions, uninstalling old and unused extensions, then installing the newer versions.

Once complete you should be able to list your installed packages and see:

My Application@1.0.0 /Users/marchbold/work/myapp
├──com.distriqt.IDFA@5.0.31
└──com.distriqt.facebook.Core@9.3.2

Here we can see the facebook package is now at the updated 9.3.2 release.

Finalising

When you update (or install) a package you should always regenerate your application descriptor. This makes sure any changes to the android manifest or the ios info additions and entitlements are correctly updated in your build.

$ apm generate app-descriptor src/MyApplication-app.xml
✓ Merge tool available
Android package name: air.com.my.app
✓ Android manifest merge
✓ iOS additions merge complete
✓ iOS entitlements merge complete
✓ App descriptor generated: /Users/marchbold/work/myapp/src/MyApplication-app.xml

Now we can return to our application and check it builds and runs as expected.

Summary

Updating is easy with apm, simply run:

apm update

and then regenerate your application descriptor:

apm generate app-descriptor

and you are done!

Advanced: Updating APM

It is worth ensuring you have the latest version of apm installed. This is done through a specific form of the apm update command:

apm update apm

This will list out the current version and then check for the latest. It will then download any updates to the apm application and install.

apm: v0.0.8-beta
✓ Found new release: 0.0.9-beta
✓ Install complete

If you have the latest you will see something like the following:

apm: v0.0.9-beta
✓ Already at latest version

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

Migrating to the AIR Package Manager

Michael — Wed, 01 Jun 2022 23:31:42 +0000

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
Approach
Process
Summary

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.

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 com.distriqt.Core@6.4.3
✓ FOUND   : Package com.distriqt.GameServices@7.2.7
✓ FOUND   : Package com.distriqt.Notifications@6.2.0
✓ FOUND   : Package com.distriqt.ZipUtils@3.0.31
✓ FOUND   : Package com.distriqt.InAppBilling@13.1.0
✓ FOUND   : Package com.distriqt.Share@7.0.12
✓ FOUND   : Package com.distriqt.Adverts@13.3.32
✓ FOUND   : Package com.distriqt.Application@6.8.1
✗ WARNING : Could not locate package for extensionID com.distriqt.Debug
✓ FOUND   : Package com.distriqt.SystemGestures@2.1.46
✓ FOUND   : Package com.distriqt.ApplicationRater@6.1.0
✓ FOUND   : Package com.distriqt.Image@5.1.79
✓ FOUND   : Package com.distriqt.MediaPlayer@4.4.8
✓ FOUND   : Package androidx.appcompat@1.2.0
✓ FOUND   : Package androidx.browser@1.3.0
✓ FOUND   : Package androidx.cardview@1.0.0
✓ FOUND   : Package androidx.core@1.3.2
✓ FOUND   : Package androidx.room@2.2.6
✓ FOUND   : Package androidx.work@2.5.0
✓ FOUND   : Package androidx.recyclerview@1.1.0
✓ FOUND   : Package androidx.multidex@2.0.1
✓ FOUND   : Package androidx.transition@1.4.0
✓ FOUND   : Package androidx.vectordrawable@1.1.0
✓ FOUND   : Package androidx.constraintlayout@1.1.3
✓ FOUND   : Package com.android.installreferrer@1.0.0
✓ FOUND   : Package com.google.android.material@1.0.0
✓ FOUND   : Package com.google.code.gson@2.8.6
✓ FOUND   : Package com.distriqt.playservices.Base@17.5.1
✓ FOUND   : Package com.distriqt.playservices.Auth@19.0.0
✓ FOUND   : Package com.distriqt.playservices.Identity@17.0.0
✓ FOUND   : Package com.distriqt.playservices.Drive@17.0.0
✓ FOUND   : Package com.distriqt.playservices.Games@21.0.0
✓ FOUND   : Package com.distriqt.playservices.Ads@20.2.0
✓ FOUND   : Package com.distriqt.playservices.AdsIdentifier@17.0.0
✓ FOUND   : Package com.distriqt.playservices.Analytics@17.0.0
✗ WARNING : Could not locate package for extensionID com.distriqt.CustomResources
✓ FOUND   : Package com.distriqt.IronSource@3.2.3
✓ FOUND   : Package com.distriqt.ironsource.AdColony@1.0.122
✓ FOUND   : Package com.distriqt.ironsource.AppLovin@1.0.117
✗ WARNING : Could not locate package for extensionID com.amazon.extensions.GameCircle
Processing identified packages
✗ SKIPPING : Dependency: com.distriqt.Core@6.4.3
✓ ADDING   : Package: com.distriqt.GameServices@7.2.7
✓ ADDING   : Package: com.distriqt.Notifications@6.2.0
✓ ADDING   : Package: com.distriqt.ZipUtils@3.0.31
✓ ADDING   : Package: com.distriqt.InAppBilling@13.1.0
✓ ADDING   : Package: com.distriqt.Share@7.0.12
✓ ADDING   : Package: com.distriqt.Adverts@13.3.32
✓ ADDING   : Package: com.distriqt.Application@6.8.1
✓ ADDING   : Package: com.distriqt.SystemGestures@2.1.46
✓ ADDING   : Package: com.distriqt.ApplicationRater@6.1.0
✓ ADDING   : Package: com.distriqt.Image@5.1.79
✓ ADDING   : Package: com.distriqt.MediaPlayer@4.4.8
✗ SKIPPING : Dependency: androidx.appcompat@1.2.0
✗ SKIPPING : Dependency: androidx.browser@1.3.0
✗ SKIPPING : Dependency: androidx.cardview@1.0.0
✗ SKIPPING : Dependency: androidx.core@1.3.2
✗ SKIPPING : Dependency: androidx.room@2.2.6
✗ SKIPPING : Dependency: androidx.work@2.5.0
✗ SKIPPING : Dependency: androidx.recyclerview@1.1.0
✗ SKIPPING : Dependency: androidx.multidex@2.0.1
✗ SKIPPING : Dependency: androidx.transition@1.4.0
✗ SKIPPING : Dependency: androidx.vectordrawable@1.1.0
✗ SKIPPING : Dependency: androidx.constraintlayout@1.1.3
✓ ADDING   : Package: com.android.installreferrer@1.0.0
✗ SKIPPING : Dependency: com.google.android.material@1.0.0
✗ SKIPPING : Dependency: com.google.code.gson@2.8.6
✗ SKIPPING : Dependency: com.distriqt.playservices.Base@17.5.1
✗ SKIPPING : Dependency: com.distriqt.playservices.Auth@19.0.0
✗ SKIPPING : Dependency: com.distriqt.playservices.Identity@17.0.0
✗ SKIPPING : Dependency: com.distriqt.playservices.Drive@17.0.0
✗ SKIPPING : Dependency: com.distriqt.playservices.Games@21.0.0
✗ SKIPPING : Dependency: com.distriqt.playservices.Ads@20.2.0
✗ SKIPPING : Dependency: com.distriqt.playservices.AdsIdentifier@17.0.0
✗ SKIPPING : Dependency: com.distriqt.playservices.Analytics@17.0.0
✗ SKIPPING : Dependency: com.distriqt.IronSource@3.2.3
✓ ADDING   : Package: com.distriqt.ironsource.AdColony@1.0.122
✓ ADDING   : Package: com.distriqt.ironsource.AppLovin@1.0.117

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 
App[@3](http://twitter.com/3).3.7 ~/work/application/android
├──com.distriqt.GameServices@7.2.7
├──com.distriqt.Notifications@6.2.0
├──com.distriqt.ZipUtils@3.0.31
├──com.distriqt.InAppBilling@13.1.0
├──com.distriqt.Share@7.0.12
├──com.distriqt.Adverts@13.3.32
├──com.distriqt.Application@6.8.1
├──com.distriqt.SystemGestures@2.1.46
├──com.distriqt.ApplicationRater@6.1.0
├──com.distriqt.Image@5.1.79
├──com.distriqt.MediaPlayer@4.4.8
├──com.android.installreferrer@1.0.0
├──com.distriqt.ironsource.AdColony@1.0.122
└──com.distriqt.ironsource.AppLovin@1.0.117

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

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.

Initialise using your existing application descriptor:

$ apm init src/App-app.xml
Install the packages:

$ apm install
Set configuration parameters
Handle any extensions that couldn’t be located as manually add extensions
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.

An Introduction to APM

Michael — Wed, 01 Jun 2022 23:27:31 +0000

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
Create a Project
Install a Package
Add to your IDE
Check Configuration
Generate the Application Descriptor
Get Coding

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 let’s 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

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

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