Using Push Notifications in SparkPost Enterprise

April 29, 2017 Contributors

Note: This Knowledge Base Article Is For SparkPost Enterprise Only

# Using Push Notifications in SparkPost Enterprise

SparkPost Enterprise customers have the option of sending push notifications through the transmissions API by including optional “channel” strings nested beneath the recipients array. This article will explain in brief overview the attributes that must be added to a transmission call, illustrated by a few examples of sample code.

# Push Documentation for APNS/GCM

Prior to sending any push notification traffic, you should be familiar with payload definitions/rules for both push notification platforms. There are many optional fields available for use through both push platforms that can improve the quality of your push notifications overall. Here are links to their documentation for your reference:

  • APNs (Apple Push Notification service)
  • GCM (Google Cloud Messaging service)

# Transmissions API and Push Notification Usage

The minimum requirements for email are untouched prior to push notifications being introduced, and no changes will be required to your injecting application(s). All fields dealing with push notifications are optional and are ignored if the “push” field in the inline template’s “content” object is undefined.

In order to make use of push notifications through the transmission API, you must use either the “apns” or “gcm” JSON object nested in the “content” object in your payload. If the content.push object is defined, fields related to email are instead made optional. This includes all the fields under the inline content attributes in our API documentation listed here. Push notifications must use a valid ip_pool/binding group configured in your environment, otherwise, push notifications will be blackholed and not be sent.

A recipient’s address attribute can now be a JSON array to allow for easier multi-channel support. Each entry in the array should be a string or JSON object. These entries will conform to the format specified in address attributes. Currently, only the first entry of the array will be used, and the remaining entries will be ignored. Channels other than email can only be specified within this array.

Note: All payloads are delivered as is  with one exception – the “to” field in a gcm payload will be replaced with info provided in the recipient list.

Note: Any platform-specific features need to be added in their own part of the push object.

The simple example below shows “color” was given in the GCM push object. Once this push information was received by the end user’s mobile device, any phone notification light with the appropriate permissions set would flash SparkPost orange. Our use of “badge” in the simple example APN block will make the app icon on the home screen of the iOS device show one notification.

Note: Substitution data is not supported for push content. When all recipients are email channels, do not include the push object, as this will break email substitution.

Note: Stored templates are not supported for push notifications.

# What Do I Need to Provide my TAM to Use Push Notifications in Enterprise?

For APNs, you must provide a TLS certificate for each unique app_id you wish to send push notifications to.

For GCM, you must provide an authentication token ID for each unique app_id you wish to send push notifications to.

Provide these to your TAM, who can then complete the setup process for you.

# Best Practices for Push Notification Reporting

Since all push notifications are sent out of the same binding group/IP pool, we recommend one of the following methods to segment your push notification reporting by campaign and device.

  1. Use a campaign ID that is unique for each application ID and device. For example, if you had an application that supported both APNs and GCM, you could name your campaigns “marketing_apns” and “marketing_gcm”. These values will be carried through on all message events.
  2. Use subaccounts. You will need to send transmissions from the master account and send on behalf of the subaccount. The subaccount_id field will be included in all message event data, allowing you to segment your reporting based upon this field.

# Example Transmissions API Code for Push Notifications

# Simple Push Notification Example:

The iOS (aps) device will receive a push notification with payload:

The Android (gcm) device will receive a push notification with payload:

# Complex Push Notification Example

In the example above, here is what would be received by each recipient:

Recipient 1: A push notification to their APNs device.

Recipient 2: A push notification to their GCM device. Because “channel” was defined as “gcm”, the “email” field is ignored and no email is sent. The second entry is ignored as well. See the recipient lists documentation for more info on “address” as a JSON array.

Recipient 3: An email is sent to “fred@flinstone.com”. No push notification is sent to his GCM device because “channel” was not specified, and thus defaults to email.

Recipient 4: Nothing. This is an error case. “Channel” is set to “apns” but the required fields “token” and “app_id” are not defined as per APNs specs.

# Sample Message Event/Webhook Entries for Push Notifcations

Push notifications generate message events that can be pulled via the Message Events API or pushed via our webhooks. Almost all push events will be one of four types – reception (injection), delivery, inband, and tempfail. The “inband” event type is considered a permanent failure and will not be retried, whereas tempfail messages will be retried.

*Note: In the context of push notifications, a “tempfail” event likely means SparkPost failed to send the push notification out. All responses from APNS are treated as a inband (permanent) failure, but the failure codes of “GCM_UNAVAILABLE (1)” or “GCM_INTERNAL_SERVER_ERROR (9)” from GCM is treated as a tempfail event.

# Sample events

# Reception

# Delivery

# Tempfail

# Inband