Step 3: Fit - Update Your Code

Tip: If you're looking for details on how to integrate the A3L Messaging SDK, see Get Started with A3L Messaging and Integrate the A3L Messaging SDK.

Amazon Device Messaging (ADM) has similarities to Firebase Cloud Messaging (FCM) which will be called out in this guide. Your familiarity with FCM can help you get started with ADM. First, download the ADM SDK, set up your Android Studio project with ADM, then continue with the following steps.

On this page, learn how to update your app's manifest to be compatible with ADM.

Update your app manifest
Next steps

Update your app manifest

To receive messages, you must update your AndroidManifest.xml file. When setting up your app with FCM, you likely extended the FirebaseMessagingService class and added your subclass as a service in your app's manifest. With ADM, you must extend three ADM classes and add your subclasses as services in your manifest. For descriptions of these classes, see Implement registration and message handling. You must also add permissions and explicitly enable ADM in your manifest file. The following instructions provide the details to make these updates.

Open your AndroidManifest.xml file and add the Amazon namespace:
```
xmlns:amazon="http://schemas.amazon.com/apk/res/android"
```

To declare the permissions necessary to support ADM, after the manifest element, add the permission and uses-permission elements.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:amazon="http://schemas.amazon.com/apk/res/android"
   package="[YOUR PACKAGE NAME]"
   android:versionCode="1"
   android:versionName="1.0">
<!-- This permission ensures that no other application can intercept your ADM messages. -->
<permission
     android:name="[YOUR PACKAGE NAME].permission.RECEIVE_ADM_MESSAGE"
     android:protectionLevel="signature" />
<uses-permission android:name="[YOUR PACKAGE NAME].permission.RECEIVE_ADM_MESSAGE" />

<!-- This permission allows your app access to receive push notifications from ADM. -->
<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />

<!-- ADM uses WAKE_LOCK to keep the processor from sleeping when a message is received. -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
...
</manifest>

Explicitly enable ADM and declare whether your app requires ADM (android:required="true") or can work without ADM being present (android:required="false"). If you specify android:required="false", your app must degrade gracefully if ADM is unavailable. In the application node of the manifest, add the uses-library element.

...
<application
      android:icon="@drawable/ic_launcher"
      android:label="@string/app_name"
      android:theme="@style/AppTheme">

      <!-- You must explicitly enable ADM and declare whether your app cannot work without
         ADM (android:required="true") or can work without ADM (android:required="false").
         If you specify android:required="false", your app must degrade gracefully if ADM
         is unavailable. -->
     <uses-library
        android:name="com.amazon.device.messaging"
     android:required="true"/>
...

Declare a broadcast receiver to handle the REGISTRATION and RECEIVE intents that ADM sends. ADM requires that the receiver be defined in the AndroidManifest.xml file, rather than programmatically. Immediately after uses-library add the following elements.

 <!-- You must replace the names in the service and receiver tags
     with names that are appropriate to your package. -->

 <service
     android:name="[YOUR JOBSERVICE NAME]"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" />

 <!-- This is needed for devices with older ADM versions -->
 <service
     android:name="[YOUR SERVICE NAME]"
     android:exported="false" />

 <receiver
     android:name="[YOUR RECEIVER NAME]"

     <!-- This permission ensures that only ADM can send your app registration broadcasts. -->
     android:permission="com.amazon.device.messaging.permission.SEND" >

     <!-- To interact with ADM, your app must listen for the following intents. -->
     <intent-filter>
        <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
        <action android:name="com.amazon.device.messaging.intent.RECEIVE" />

        <!-- Replace the name in the category tag with your app's package name. -->
        <category android:name="[YOUR PACKAGE NAME]" />
     </intent-filter>
 </receiver>

After updating your AndroidManifest.xml file, you can confirm that the changes are correct for ADM by calling ADMManifest.checkManifestAuthoredProperly().

If you receive a java.lang.NoClassDefFoundError: com.amazon.device.messaging.ADM error, check your manifest to verify that you have added the uses-library element in the location specified in step 3.

The following code is a complete example of an AndroidManifest.xml file enabled for ADM.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:amazon="http://schemas.amazon.com/apk/res/android"
   package="[YOUR PACKAGE NAME]"
   android:versionCode="1"
   android:versionName="1.0" >

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

   <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" />

   <application
      android:icon="@drawable/ic_launcher"
      android:label="@string/app_name"
      android:theme="@style/AppTheme" >

      <uses-library
         android:name="com.amazon.device.messaging"
         android:required="true"/>

      <service
         android:name="[YOUR JOBSERVICE NAME]"
         android:permission="android.permission.BIND_JOB_SERVICE"
         android:exported="false" />

      <!-- This is needed for devices with older ADM versions -->
      <service
         android:name="[YOUR SERVICE NAME]"
         android:exported="false" />

      <receiver
         android:name="[YOUR RECEIVER NAME]"
         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>
   </application>
</manifest>

Next steps

Go to the next step: Obtain and Store Your API Key.

Last updated: Mar 24, 2022