Get started with Notification Hubs for Kindle apps

This tutorial shows you how to use Azure Notification Hubs to send push notifications to a Kindle application. You create a blank Kindle app that receives push notifications by using Amazon Device Messaging (ADM).

In this tutorial, you create/update code to do the following tasks:

  • Add a new app to the developer portal
  • Create an API key
  • Create and configure a notification hub
  • Set up your application
  • Create your ADM message handler
  • Add your API key to your app
  • Run the app
  • Send a test notification

Prerequisites

Add a new app to the developer portal

  1. Sign into the Amazon Developer Portal.

  2. Select Add New App, and then select Android.

    Add new app button

  3. On the New App Submission page, follow these steps to get the application key:

    1. Enter a name for the App title.

    2. Select any category (for example: education)

    3. Enter an email address for the Customer support email address field.

    4. Select Save.

      New App Submission page

  4. At the top, switch to the Mobile Ads tab, and do the following steps:

    1. Specify whether your app is directed primarily at kids under 13. For this tutorial, select No.

    2. Select Submit.

      Mobile Ads page

    3. Copy the application key from the Mobile Ads page.

      Application key

  5. Select Apps & Services menu at the top, and select your application in the list.

    Select your app from list

  6. Switch to the Device Messaging tab, and follow these steps:

    1. Select Create a New Security Profile.
    2. Enter a name for your security profile.
    3. Enter description for your security profile.
    4. Select Save.
    5. Select View Security Profile on the result page.
  7. Now, on the Security Profile page, do the following steps:

    1. Switch to the Web Settings tab, and copy the Client ID and Client Secret value for later use.

      Get client ID and secret

    2. Switch to the Android/Kindle Settings page, and keep the page open. You'll enter these values in the next section.

Create an API key

  1. Open a command prompt with administrator privileges.

  2. Navigate to the Android SDK folder.

  3. Enter the following command:

    keytool -list -v -alias androiddebugkey -keystore ./debug.keystore
    
  4. For the keystore password, type android.

  5. Copy the MD5 and SHA256 fingerprints.

  6. Back in the developer portal, on the Android/Kindle Settings tab, do the following steps:

    1. Enter a name for the API key.

    2. enter the name of the package for your app (for example, com.fabrikam.mykindleapp) and the MD5 value.

      Important

      When you create an app in Android Studio, use the same package name you specified here.

    3. Paste the MD5 signature you copied earlier.

    4. Paste the SHA256 signature you copied earlier.

    5. Select Generate New Key.

      Android/Kindle settings - generate key

    6. Now, select Show in the list to see the API key.

      Android/Kindle settings - Show API Key

    7. In the API Key Details window, copy the API Key and save it somewhere. Then, select X in the upper-right corner to close the window.

Create and configure a notification hub

  1. Follow steps in the Create an Azure notification hub in the Azure portal article to create a notification hub.

  2. Select Amazon (ADM) under Settings menu.

  3. Paste the Client ID and Client Secret you saved earlier.

  4. Select Save on the toolbar.

    Configure ADM settings for a notification hub

  5. Select Access Policies on the left menu, and select the copy button for the connection string for the DefaultListenSharedAccessSignature policy. Save it somewhere. You'll use it later in the source code.

    Notification hub - listen connection string

Set up your application

  1. Launch Android Studio.

  2. Select File, point to New, and then select New Project.

  3. In the Choose your project window, on the Phone and Tablet tab, select Empty Activity, and select Next.

  4. In the Configure your project window, do the following steps:

    1. Enter a name for your application. You may want to match it with the name of the application you created in the Amazon Developer Portal.

    2. Enter a name for the package.

      Important

      The package name must match the package name you specified in the Amazon Developer Portal.

    3. Review and update the remaining values as appropriate.

    4. Select Finish.

      Configure Android project

  5. Download Amazon Developer SDK for Android library to your hard disk. Extract the SDK zip file.

  6. In Android Studio, change the folder structure from Android to Project if it isn't already set to Project.

    Android Studio - Switch to project structure

  7. Expand app to see the libs folder in the tree view.

  8. In a File Explorer window, navigate to the folder where you downloaded the Amazon Android SDKs.

  9. Press CTRL and drag-and-drop the amazon-device-messaging-1.0.1.jar file to the lib node in the tree view.

    Android Studio - Add Amazon Device Messaging JAR

  10. In the Copy window, select OK. If you see the Move window instead of Copy window, close it, and try drag-drop operation with CTRL button pressed.

    Android Studio - Copy JAR

  11. Add the following statement to the app's build.gradle file in the dependencies section: implementation files('libs/amazon-device-messaging-1.0.1.jar').

    Android Studio - add ADM to app's build.gradle

  12. In the Build.Gradle file for the app, add the following lines in the dependencies section:

    implementation 'com.microsoft.azure:notification-hubs-android-sdk:0.6@aar'
    implementation 'com.microsoft.azure:azure-notifications-handler:1.0.1@aar'
    
  13. Add the following repository after the dependencies section:

    repositories {
        maven {
            url "https://dl.bintray.com/microsoftazuremobile/SDK"
        }
    }
    
  14. In the editor for the build.gradle file for the app, select Sync now on the toolbar.

    Android Studio - sync build.gradle of the app

  15. Switch back to the Android structure in the tree view. Add the Amazon namespace in the root manifest element:

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

    Amazon namespace in the manifest

  16. Add permissions as the first element under the manifest element. Replace [YOUR PACKAGE NAME] with the package that you used to create your app.

    <permission
        android:name="[YOUR PACKAGE NAME].permission.RECEIVE_ADM_MESSAGE"
        android:protectionLevel="signature" />
    
    <uses-permission android:name="android.permission.INTERNET"/>
    
    <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" />
    
  17. Insert the following element as the first child of the application element. Replace [YOUR PACKAGE NAME] with the package name with which you created your app. You'll create the MyADMMessageHandler class in the next step.

        <amazon:enable-feature
            android:name="com.amazon.device.messaging"
            android:required="true"/>
        <service
            android:name="[YOUR PACKAGE NAME].MyADMMessageHandler"
            android:exported="false" />
        <receiver
            android:name="[YOUR PACKAGE NAME].MyADMMessageHandler$Receiver"
            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>
    

Create your ADM message handler

  1. Add a new class to the com.fabrikam.mykindleapp package in the project that inherits from com.amazon.device.messaging.ADMMessageHandlerBase and name it MyADMMessageHandler, as shown in the following image:

    Create MyADMMessageHandler class

  2. Add the following import statements to the MyADMMessageHandler class:

    import android.app.NotificationManager;
    import android.app.PendingIntent;
    import android.content.Context;
    import android.content.Intent;
    import android.support.v4.app.NotificationCompat;
    import android.util.Log;
    import com.amazon.device.messaging.ADMMessageReceiver;
    import com.microsoft.windowsazure.messaging.NotificationHub;
    
  3. Add the following code in the class that you created. Remember the [HUB NAME] and [LISTEN CONNECTION STRING] with the name of your notification hub and listen connection string:

    public static final int NOTIFICATION_ID = 1;
    private NotificationManager mNotificationManager;
    NotificationCompat.Builder builder;
    private static NotificationHub hub;
    
    public static NotificationHub getNotificationHub(Context context) {
        Log.v("com.wa.hellokindlefire", "getNotificationHub");
        if (hub == null) {
            hub = new NotificationHub("[HUB NAME]", "[HUB NAMESPACE CONNECTION STRING]", context);
        }
        return hub;
    }
    
    public MyADMMessageHandler() {
        super("MyADMMessageHandler");
    }
    
    @Override
    protected void onMessage(Intent intent) {
        String nhMessage = intent.getExtras().getString("msg");
        sendNotification(nhMessage);
    }
    
    @Override
    protected void onRegistrationError(String s) {
    
    }
    
    @Override
    protected void onRegistered(String s) {
        try {
            getNotificationHub(getApplicationContext()).register(s);
        } catch (Exception e) {
            Log.e("[your package name]", "Fail onRegister: " + e.getMessage(), e);
        }
    }
    
    @Override
    protected void onUnregistered(String s) {
        try {
            getNotificationHub(getApplicationContext()).unregister();
        } catch (Exception e) {
            Log.e("[your package name]", "Fail onUnregister: " + e.getMessage(), e);
        }
    }
    
    public static class Receiver extends ADMMessageReceiver
    {
        public Receiver()
        {
            super(MyADMMessageHandler.class);
        }
    }
    
    private void sendNotification(String msg) {
        Context ctx = getApplicationContext();
    
        mNotificationManager = (NotificationManager)
                ctx.getSystemService(Context.NOTIFICATION_SERVICE);
    
        PendingIntent contentIntent = PendingIntent.getActivity(ctx, 0,
                new Intent(ctx, MainActivity.class), 0);
    
    
        NotificationCompat.Builder mBuilder =
                new NotificationCompat.Builder(ctx)
                        .setSmallIcon(R.mipmap.ic_launcher)
                        .setContentTitle("Notification Hub Demo")
                        .setStyle(new NotificationCompat.BigTextStyle()
                                .bigText(msg))
                        .setContentText(msg);
    
        mBuilder.setContentIntent(contentIntent);
        mNotificationManager.notify(NOTIFICATION_ID, mBuilder.build());
    }
    

Add your API key to your app

  1. Follow these steps to add an assets folder to the project.
    1. Switch to the Project view.

    2. Right-click app.

    3. Select New.

    4. Select Folder.

    5. Then, select Assets Folder.

      Add assets folder menu

    6. On the Configure Component page, do the following steps:

      1. Select Change folder location

      2. Confirm that the folder is set to: src/main/assets.

      3. Select Finish.

        Configure assets folder

  2. Add a file named api_key.txt to the assets folder. In the tree view, expand app, expand src, expand main, and right-click assets, point to New, and then select File. Enter api_key.txt for the file name. 3.
  3. Copy the API key that you generated in the Amazon developer portal to the api_key.txt file.
  4. Build the project.

Run the app

  1. On the Kindle device, swipe from the top and click Settings, and then click My account and register with a valid Amazon account.
  2. Run the app on a Kindle device from Android Studio.

Note

If a problem occurs, check the time of the emulator (or device). The time value must be accurate. To change the time of the Kindle emulator, you can run the following command from your Android SDK platform-tools directory:

adb shell  date -s "yyyymmdd.hhmmss"

Send a notification message

To send a message by using .NET:

static void Main(string[] args)
{
    NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString("[conn string]", "[hub name]");

    hub.SendAdmNativeNotificationAsync("{\"data\":{\"msg\" : \"Hello from .NET!\"}}").Wait();
}

For sample code, see this example on GitHub.

Next steps

In this tutorial, you sent broadcast notifications to all your Kindle devices registered with the backend. To learn how to push notifications to specific Kindle devices, advance to the following tutorial: The following tutorial shows how to push notifications to specific Android devices, but you can use the same logic for pushing notifications to specific Kindle devices.