Amazon Device Messaging

Push Notifications on Amazon Devices

Amazon devices do not support FCM and instead use Amazon’s push notification service, ADM.

Note

Using ADM requires changes to the AndroidManifest.xml that are not supported by Adobe AIR, so you must un-pack, edit, re-pack and re-sign your APK after it has been generated by adt.

Add Permissions and Teak Components to your AIR XML

Add the following to the <manifest> section, above the opening <application> tag:

<permission
    android:name="YOUR_PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE"
    android:protectionLevel="signature" />
<uses-permission android:name="YOUR_PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" />
<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Add the following to the <application> section:

<!-- If you are using the Teak build scripts, uncomment the next line -->
<!-- <service android:name="placeholder.enable.adm" /> -->

<service android:name="io.teak.sdk.push.ADMPushProvider"
    android:exported="false" />
<receiver
    android:name="io.teak.sdk.push.ADMPushProvider$MessageAlertReceiver"
    android:permission="com.amazon.device.messaging.permission.SEND" >
    <intent-filter>
        <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
        <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
        <category android:name="YOUR_PACKAGE_NAME" />
    </intent-filter>
</receiver>

Note

Replace YOUR_PACKAGE_NAME with the package name of your Android game. Make sure that for air games, you prefix the package name with “air” (if applicable to your game).

Note

If you are using the Teak re-pack scripts, uncomment the placeholder.enable.adm line.

Get your Amazon Credentials

ADM requires that you have an api_key.txt in the assets folder of your Android app.

In order to get your api_key.txt follow the instructions located here: https://developer.amazon.com/docs/adm/obtain-credentials.html

Once you have completed these steps, go to your apps on the Amazon Developer site, and look at the Security Profiles https://developer.amazon.com/iba-sp/overview.html

Click on the security profile for your app.

Copy the value in the Amazon security profile for Client ID into the Teak Mobile Settings for your app for ADM Client ID.

Copy the value in the Amazon security profile for Client Secret into the Teak Mobile Settings for your app for ADM Client Secret.

This gives Teak the information it needs to send ADM messages to your app.

Add api_key.txt to your Assets

You can add api_key.txt to your APK in one of two ways: * Copy it during the re-pack step * Add it during build using adt

To add api_key.txt during your build step with adt, use the -C flag:

-C src/assets api_key.txt

Editing the Contents of your APK

At a high level, we use apktool to un-pack and re-pack the APK generated by adt. You can get apktool here: https://ibotpeaches.github.io/Apktool/

Note

Teak has a set of scripts that can help with all of these steps, you can find it here: https://github.com/GoCarrot/teak-air/tree/master/android/repacker

Contact us for help with the script.

Un-packing your APK

To un-pack an APK, use the following command:

java -jar apktool_2.1.0.jar d --force --output <temp_path>

This will unpack the contents of the APK to <temp_path>.

Add xmlns:amazon Property

At the top of your <temp_path>/AndroidManifest.xml you will see:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

Add the xmlns:amazon property:

<manifest xmlns:amazon="http://schemas.amazon.com/apk/res/android" xmlns:android="http://schemas.android.com/apk/res/android">

Add amazon:enable-feature Tag

Enable ADM by adding this tag:

<amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false"/>

It should be located right above this:

<service android:name="io.teak.sdk.push.ADMPushProvider" android:exported="false" />

Copy api_key.txt Into assets

Copy your api_key.txt to <temp_path>/assets/api_key.txt

Note

You do not need to do this if you are adding api_key.txt during your adt build step.

Re-pack your APK

Re-pack your apk using apktool:

java -jar apktool_2.1.0.jar b --output output.apk <temp_path>

Sign and zipalign Your New APK

Follow these instructions to sign and zipalign the resulting APK: https://developer.android.com/studio/publish/app-signing#sign-manually

Give it a Try

You should now have what you need to test ADM support.

Keep an eye on the debug console, if you see:

Add this to your <application> in AndroidManifest.xml in order to use ADM: <amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false" />

Revisit step 3 in https://developer.amazon.com/docs/adm/integrate-your-app.html#update-your-app-manifest

If you see log output with event_type of amazon.adm.registration_error Teak is trying to determine why ADM registration has failed. If you see:

Unable to find 'api_key.txt' in assets [...]

api_key.txt is not in the Android assets. Revisit https://developer.amazon.com/docs/adm/integrate-your-app.html#store-your-api-key-as-an-asset

If you see:

Whitespace found in 'api_key.txt'

There is whitespace somewhere in the contents of api_key.txt, this will prevent Amazon’s SDK from reading the key. Remove the whitespace, it is usually a trailing newline.

If you see:

Potentially malformed contents of 'api_key.txt', does not contain three sections delimited by '.'

The contents of api_key.txt are incorrect. Revisit https://developer.amazon.com/docs/adm/integrate-your-app.html#store-your-api-key-as-an-asset

If you see:

Package name mismatch in 'api_key.txt'

The package name of your app does not match the package name inside api_key.txt. The api_key.txt must be generated for the package name of your app.

If you see:

App signature SHA-256 does not match api_key.txt
App signature MD5 does not match api_key.txt

The signature your app was signed with does not match any of the signatures in api_key.txt. Revisit step 8 in https://developer.amazon.com/docs/adm/obtain-credentials.html