Integration
A push notification is an out-of-app alert that appears on the user’s screen when an important update occurs. Push notifications are a valuable way to provide your users with time-sensitive and relevant content or to re-engage them with your app.
ADM (Amazon Device Messaging) is not supported on non-Amazon devices. In order to test Kindle Push you must have a FireOS device (see Amazon Listing of supported devices).
Check out the Help section for additional best practices.
Braze sends push notifications to Amazon devices using Amazon Device Messaging (ADM).
Amazon Device Messaging (ADM) is only supported on Fire phones and tablets (except for Kindle Fire 1st Generation). You cannot test ADM messaging on a regular Android device.
Step 1: Enable ADM
- Create an account with the Amazon Apps & Games Developer Portal if you have not already done so.
- Obtain OAuth credentials (Client ID and Client Secret) and an ADM API key by following the instructions in Obtaining Amazon Device Messaging Credentials.
-
Add the following line to your
res/values/braze.xml
file to enable ADM:1
<bool name="com_appboy_push_adm_messaging_registration_enabled">true</bool>
Step 2: Update AndroidManifest.xml
-
In your app’s AndroidManifest.xml, add Amazon’s namespace to the
<tt>manifest</tt>
tag.1
xmlns:amazon="http://schemas.amazon.com/apk/res/android"
-
Declare permissions required to support ADM by adding
<tt>permission</tt>
and<tt>uses-permission</tt>
elements after the<tt>manifest</tt> element
.1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
<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>
-
Declare that your app uses the device’s ADM feature and declare that your app is designed to remain functional without ADM present on the device (android:required=”false”) by adding an amazon:enable-feature element to the manifest’s application element. It is safe to set android:required to “false” because Braze ADM code degrades gracefully when ADM is not present on the device.
1 2 3 4 5 6 7 8
... <application android:icon="@drawable/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme"> <amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false"/> ...
-
Add intent filters to handle
REGISTRATION
andRECEIVE
intents from ADM within your Braze broadcast receiver’sAndroidManifest.xml
file. Immediately afteramazon:enable-feature
, add the following elements:1 2 3 4 5 6 7
<receiver android:name="com.appboy.AppboyAdmReceiver" android:permission="com.amazon.device.messaging.permission.SEND"> <intent-filter> <action android:name="com.amazon.device.messaging.intent.RECEIVE" /> <action android:name="com.amazon.device.messaging.intent.REGISTRATION" /> <category android:name="com.yourapp.packagename" /> </intent-filter> </receiver>
Step 3: Store Your ADM API Key
- Save your ADM API key to a file named
api_key.txt
and save it in your project’sassets
folder. - For how to obtain an ADM API Key for your app, consult Amazon’s documentation on obtaining an ADM API Key.
- Amazon will not recognize your key if
api_key.txt
contains any white space characters, such as a trailing line break.
Step 4: Add Deep Links
Enabling Automatic Deep Link Opening
To enable Braze to automatically open your app and any deep links when a push notification is clicked, set com_appboy_handle_push_deep_links_automatically
to true
in your braze.xml
:
1
<bool name="com_appboy_handle_push_deep_links_automatically">true</bool>
If you would like to custom handle deep links, you will need to create a BroadcastReceiver
that listens for push received and opened intents from Braze. See our section on Custom Handling Push Receipts and Opens in the Android push documentation for more information.
Step 5: Add Client Secret and Client ID to Braze Dashboard
Lastly, you must add the Client Secret and Client ID you obtained in Step 1 to the Braze dashboard’s “Manage App Group” page as pictured below:
Manual Push Registration
If you need to handle ADM registration yourself, you should do the following:
-
Within braze.xml add the following:
1 2
<!-- This will disable automatic registration for ADM via the Braze SDK--> <bool name="com_appboy_push_adm_messaging_registration_enabled">false</bool>
-
Use the registerAppboyPushMessages() method to pass your user’s ADM
registration_id
to Braze:1
Appboy.getInstance(context).registerAppboyPushMessages(registration_id);
Braze does not recommend using manual registration if possible.
ADM Extras
Users may send custom key value pairs with a Kindle push message as “extras” for “Deep Linking”, tracking urls, etc. Please note that unlike in Android push, Kindle push users may not use Braze reserved keys as keys when defining “extra” key value pairs.
Reserved Keys Include:
_ab
a
cid
p
s
t
ttl
uri
If a Kindle reserved key is detected, Braze returns Status Code 400: Kindle Push Reserved Key Used.