Home > Services & APIs > Engage > Device Messaging

Setting Up Amazon Device Messaging

Introduction

Introduction

To use Amazon Device Messaging (ADM) with your app, you first need to include the ADM JAR in your development environment. This document presents three ways of configuring your project to include ADM:

  • using Android Studio.
  • using Eclipse, an open-source integrated development environment (IDE).
  • using the command line.

If you haven’t already, see Understanding ADM for an overview of the ADM architecture. Obtaining ADM Credentials describes the process of getting your initial credentials for ADM.

To use ADM in your project, install the following on your development computer:

  • The Android SDK (API 15 or higher)
  • Any Android SDK system requirements, including the JDK

Before configuring your project, download the Amazon Mobile App SDK. By downloading our Amazon Mobile App SDK, you agree to our Program Materials License Agreement. Extract the SDK contents to a location of your choice.

Adding ADM to Your IDE Project

To use ADM with your IDE-based project, you add the ADM library to your project as an external JAR. While you can use ADM with any development environment, the following sections describe adding ADM to Android Studio or to Eclipse.

Adding ADM to Android Studio

Make sure you have downloaded and installed the current version of Android Studio.

  1. In Android Studio, create a new Android project or open an existing project.

  2. Change the folder structure from Android to Project.

    change-folder-structure
    Change the folder structure in Android Studio
  3. Search for the libs folder inside the app folder.

    find-libs-in-apps-folder
    Find the libs folder in the apps folder
  4. Copy the amazon-device-messaging-1.0.1.jar from where you extracted the ADM zip file.

  5. Paste the jar into the libs folder.

    paste-jar-in-libs
    Paste the jar file in libs
  6. Right click the jar file and at end click Add as library.

    add-library
    Add jar file as library

    This automatically adds the compile files('libs/amazon-device-messaging-1.0.1.jar') command to the build.gradle file.

  7. Finally, because you need the library only for compile time and not for runtime as the Amazon device will have the necessary classes and methods, change the line from compile files to provided files. Change from this:

    dependencies {
        compile files('libs/amazon-device-messaging-1.0.1.jar')
    }
    

    to this:

    dependencies {
        provided files('libs/amazon-device-messaging-1.0.1.jar')
    }
    

Adding ADM to Eclipse

Make sure you have installed the Android Development Tools (ADT) Plugin for Eclipse.

  1. In Eclipse, create a new Android project or open an existing one.

  2. Open the project’s properties; for example, right-click the root folder for the project, and then click Properties.

  3. From the list of properties, select Java Build Path. Select the Libraries tab.

  4. Click Add External JARs… and navigate to where you extracted the ADM zip file.

  5. Open the DeviceMessaging/lib folder, select the amazon-device-messaging-1.0.1.jar file, and then click Open.

  6. You should now see amazon-device-messaging.jar listed in the Properties window. Click OK.

    In the Package Explorer for your project, under Referenced Libraries, amazon-device-messaging.jar should now appear.

Adding ADM from the Command Line

Before performing this procedure, update your AndroidManifest.xml file, as described in Integrating Your App with Amazon Device Messaging. Also ensure that you have Apache ANT installed, with your ANT_HOME, JAVA_HOME, and PATH environmental variables properly defined.

  1. Change directories into the Android SDK’s tools/ path.

  2. Run a command with the following syntax, where <path> is the location where the project will be created, and <target Android platform> is the Android Platform for which the project is intended. For a list of available platforms, run android list targets.

    android create project –-path <path> --target <target Android platform> –-activity ADMActivity –-package com.example.amazon.adm
    
  3. At the root of your new project, create a new directory, called ext_libs.

  4. Navigate to the Android/DeviceMessaging/lib directory, in the Amazon Mobile App SDK, and copy the JAR file to your new ext_libs directory.

  5. At the root of your new project, create a custom_rules.xml file that contains the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <project name="custom_rules">
    <path id="java.compiler.classpath.path">
    <fileset dir="ext_libs" includes="*.jar"/>
    </path>
    <property name="java.compiler.classpath" refid="java.compiler.classpath.path" />
    </project>
    
  6. To build your project, run the following command from the root directory for your project:

    ant debug

Make sure that you take similar steps to configure the projects that test your app.

Configuring Proguard

If you use Proguard, edit the proguard.cfg file and add the following configuration:

#This should point to the directory where ADM’s jar is stored
-libraryjars libs
-dontwarn com.amazon.device.messaging.**
-keep class com.amazon.device.messaging.** {*;}
-keep public class * extends com.amazon.device.messaging.ADMMessageReceiver
-keep public class * extends com.amazon.device.messaging.ADMMessageHandlerBase

Next Steps

To use ADM, you must: