Schema sample: RawContent object for a push notification - Amazon Pinpoint

Schema sample: RawContent object for a push notification

When you send a push notification through a push notification channel, you have the option of using a RawContent object to specify the settings and contents of the notification. Using a RawContent object can be helpful when you want to send custom data to an app for processing, as part of sending a notification. If you use a RawContent object to define the settings and contents of a push notification, the settings and content that you specify in the object override all other settings and content for the notification.

Overview

A RawContent object is a raw, JSON-formatted string that contains the payload for a push notification. The data in the payload is formatted as a set of key-value pairs, with the quotation marks escaped.

The contents of a RawContent object vary, depending primarily on the target platform and push notification service. For each platform and service, the contents of this object maps to a specific message object of the Amazon Pinpoint API:

  • Amazon Device Messaging – For push notifications that you want to send through the ADM channel to the Amazon Device Messaging (ADM) service, use the fields and options defined by the ADMMessage object. Enclose the RawContent object in that object.

  • Apple Push Notification service – For push notifications that you want to send through an APNs channel to the Apple Push Notification (APNs) service, use the fields and options defined by the APNSMessage object. Enclose the RawContent object in that object.

  • Baidu Cloud Push – For push notifications that you want to send through the Baidu channel to the Baidu Cloud Push service, use the fields and options defined by the BaiduMessage object. Enclose the RawContent object in that object.

  • Firebase Cloud Messaging – For push notifications that you want to send through the GCM channel to the Firebase Cloud Messaging (FCM) service, use the fields and options defined by the GCMMessage object. Enclose the RawContent object in that object.

The preceding links go to the object definitions for the SendMessages operation, which corresponds to sending a POST request to the Messages resource. However, you can use these objects with other Amazon Pinpoint API operations that send push notifications.

The structure and design of these objects aligns with the requirements and options that are provided by the corresponding platform and push notification service. For detailed information about the options for a particular platform or service, see the documentation for the platform or service.

Important

Avoid putting sensitive data, such as credit card numbers, in RawContent objects. If you have to include sensitive data in an object, make sure that you encrypt the data before you send it and use the decryption features provided by the target platform.

Samples

The samples in this topic use comparable example data to show the structure of two RawContent objects. The objects specify the settings and contents of a standard push notification. The notification congratulates an existing user of a fitness app because the user reported a new personal record for a running time.

The first sample is designed to be sent to APNs for delivery to the app on an iOS device:

{ "APNSMessage":{ "RawContent":"{\"Body\":\"Hi {{User.UserAttributes.FirstName}}, congratulations on your new {{User.UserAttributes.Activity}} record!\",\"Title\":\"Congratulations!\",\"Action\":\"OPEN_APP\",\"SilentPush\":\"false\",\"Data\":{},\"MediaUrl\":\"url-to-trophy-image\",\"Sound\":\"default\",\"Badge\":\"1\",\"ThreadId\":\"example-app-ID\",,\"content-available\":\"0\",\"PreferredAuthenticationMethod\":\"CERTIFICATE\",\"TimeToLive\":\"86400\",\"Priority\":\"10\",\"CollapseId\":\"congrats\",\"APNSPushType\":\"alert\"}" } }

The second sample is designed to be sent to FCM for delivery to the app on an Android device:

{ "GCMMessage":{ "RawContent":"{\"Body\":\"Hi {{User.UserAttributes.FirstName}}, congratulations on your new {{User.UserAttributes.Activity}} record!\",\"Title\":\"Congratulations!\",\"Action\":\"OPEN_APP\",\"SilentPush\":\"false\",\"Data\":{},\"IconReference\":\"appicon\",\"Sound\":\"default\",\"ImageUrl\":\"url-to-trophy-image\",\"ImageIconUrl\":\"url-to-large-icon\",\"SmallImageIconUrl\":\"url-to-small-icon\",\"CollapseKey\":\"congrats\",\"RestrictedPackageName\":\"example.fitnessapp\",\"TimeToLive\":86400\",\"Priority\":\"high\"}" } }

The remaining sections of this topic describe the fields and characteristics of these samples.

Common fields

Both the APNs and FCM samples have the following fields and characteristics:

Field Type Value Description
Body

String

Hi {{User.UserAttributes.FirstName}}, congratulations on your new {{User.UserAttributes.Activity}} record!

Display this text in the body of the notification.

The text uses message variables for two custom user attributes for the Amazon Pinpoint application: FirstName, which stores the recipient's first name; and, Activity, which stores the recipient's preferred activity.

For example, if the recipient's first name is Alejandro and his preferred activity is running, the text in the body of the notification would be:

Hi Alejandro, congratulations on your new running record!

Title String Congratulations! Display this text, as the title, above the body of the notification.
Action Enumerated value OPEN_APP Open the app or move it to the foreground if the recipient taps the notification.
SilentPush Boolean false Display the notification as a standard push notification on the recipient's device. (The notification isn't a silent push notification.)
Data String null Don't pass a custom data payload to the app or treat the notification as a silent push notification.
Sound String default Play the default notification sound for the recipient's device when the recipient receives the notification.
TimeToLive Integer 86400 Store and attempt to deliver the notification for 86,400 seconds (24 hours) if the notification can't be delivered on the first attempt.

APNs-Specific fields

In addition to the common fields and values, the APNs sample has the following unique fields and characteristics:

Field Type Value Description
MediaUrl String url-to-trophy-image Display this image (a rendering of a trophy, at the specified URL) in the body of the notification.
Badge Integer 1

Badge the app's icon and display the number 1 with the badge when the recipient receives the push notification.

ThreadId String example-app-ID Associate the notification with the notification grouping for the app. (The app uses a Notification Content app extension that can be used to group notifications.)
content-available Integer 0 Treat the notification as a standard push notification, not a silent push notification.
PreferredAuthenticationMethod Enumerated value CERTIFICATE Authenticate with APNs by using a certificate, not a token.
Priority String 10 Send the notification immediately.
CollapseId String congrats If necessary, coalesce multiple messages into a single push notification, instead of delivering each message individually.
APNSPushType String alert Deliver the notification as a standard notification—display the notification on the recipient's device and prompt the recipient to interact with the notification.

FCM-Specific fields

In addition to the common fields and values, the FCM sample has the following unique fields and characteristics:

Field Type Value Description
IconReference

String

appicon

Display the launcher icon specified in the app's manifest as the notification badge.

ImageUrl String url-to-trophy-image Display this image (a rendering of a trophy, at the specified URL) in the body of the notification.
ImageIconUrl String url-to-large-icon Display this image (the app icon, at the specified URL) in the content view of the push notification.
SmallImageIconUrl String url-to-small-icon Display this image (a small version of the app icon, at the specified URL) in the status bar and the notification drawer.
CollapseKey String congrats Replace any older notifications with this notification if they have the same collapse key.
RestrictedPackageName String example.fitnessapp Use this package (the package name of the app) to verify that the registration tokens match, before delivering the notification to the recipient.
Priority Enumerated value high Send the notification immediately, wake the recipient's device if the device is sleeping.