Navigation

Push Notifications (GCM)

MongoDB Stitch supports integrating mobile (Android and iOS) apps with the Google Cloud Messaging (GCM) service to provide push notifications. You configure and send notification messages from within the Stitch console, while clients register with GCM for messages sent to specific topics.

For a tutorial on integrating Push Notifications in an Android app, see Push Notifications (Android App).

Managing Stitch Push Notifications

In the Stitch console, in the left-hand navigation pane, click on Push Notifications. The Push Notifications page has four tabs:

  • Sent

    The Sent tab shows the messages that have already been sent to registered clients. From here, you can view a list of the sent messages. For the sent messages, you can:

    • Resend sent messages.
    • Duplicate sent messages.
  • Draft

    In the Draft tab, you can view a list of the draft messages. For the draft messages, you can:

    • Duplicate draft messages
    • Edit draft messages
    • Delete draft messages
  • Config

    In the Config tab, you provide the GCM credentials (Sender ID and Legacy API key).

  • Rules

    You can optionally specify rules to restrict the types of push notifications that can be sent from your application. See the Notification Rules section for details.

In addition, you can send new Push Notifications from the Push Notifications page. Click the Send New Notification button to open the Send New Notification dialog:

Sending a new Push Notification

In this dialog, you provide the notification message, label, and the topic that your clients are listening for.

Notification Rules

To specify rules for Push Notifications, click on the Rules tab on the Push Notifications page. For general information on service rule construction and syntax, see Service Rules.

Note

Unlike other services in MongoDB Stitch, rules for push notifications are optional. By default, all push notifications are allowed. However, once you specify a rule, the restrictions imposed by that rule will take effect.

The following arguments are permitted in Push Notifications rules, and they can be accessed with the "%%args" expansion:

Field Type Description
userIds Array of strings. The user ids of the message recipients.
to String The send-to topic. The recipients are the users who have opted into the topic.
registrationTokens Array of strings. The list of registration tokens for the devices receiving the multicast message.
priority string The priority of the notification. Value is either "high" or "normal". Corresponds to the priority option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
collapseKey string The collapse key associated with collapsible messages. Corresponds to the collapse_key option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
contentAvailable boolean A flag that determines whether to awake idle client apps upon receipt of the message. Corresponds to the content_available option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
mutableContent boolean A flag that determines whether the notification content can be modified before being displayed to the user. Corresponds to the mutable_content option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
timeToLive int

Maximum time (in milliseconds) to retain the message if the device is offline. Valid value range from 0 to 2419200.

Corresponds to the time_to_live option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.

data JSON document Payload for data message. data document consists of custom key-value pairs. Corresponds to the data option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
notification JSON document Payload for notification. notification document consists of predefined fields. Corresponds to the notification option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.

Notification Fields

The following table lists the fields of the notification document that is available as a permitted field for Push Notifications rules. To access one of these fields in a rule, use "%%args.notification.<field>".

Field Type Description
title string The title of the notification. Corresponds to the title option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
body string The body of the notification. Corresponds to the body option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
sound string The sound to play upon receipt of the notification. Corresponds to the sound option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
clickAction string The action to take when a user click on the notification. Corresponds to the click_action option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
bodyLocKey string The key for localization of the body string. Corresponds to the body_loc_key option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
bodyLocArgs string The string values to replace format specifiers for localization in the body string. Corresponds to the body_loc_args option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
titleLocKey string The key for localization of the title string. Corresponds to the title_loc_key option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
titleLocArgs string The string values to replace format specifiers for localization in the title string. Corresponds to the title_loc_args option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
icon string For Android only. The notification icon. Corresponds to the icon option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref .
color string For Android only. Indicates the icon color in #rrggbb format. Corresponds to the color option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
tag string For Android only. If specification, each notification does not result in a new entry but replaces an existing entry with the specified tag. If unset, each notificaiton results in a new entry. Corresponds to the tag option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.
badge string For iOS only. The badge on client app home icon. Corresponds to the badge option for for HTTP JSON messages via GCM. See https://developers.google.com/cloud-messaging/http-server-ref.

Example

Actions When
send
{
  "to" : { "%in": "%%values.validTopics" }
}

This rule ensures that applications can only perform a send action when the to argument is a string listed in validTopics, where validTopics is a user-defined constant. For more information in defining constants, see Values.

Client Application Integration

The Push Notifications (Android App) tutorial demonstrates integrating Push Notifications in an Android application. The general process is as follows:

  1. Add a dependency for GCM.
  2. Create a GCMPushClient.
  3. Use the GCMPushClient’s register() method to register the client for push notifications.
  4. Use GCMPushClient’s subscribeToTopic() method to subscribe to topics.
  5. Create a class that extends the abstract GCMListenerService and implement the onPushMessageReceived() method. This class handles communication with GCM.
  6. Update AndroidManifest.xml file for your Android project to register your GCMListenerService and a receiver for your application.

For the latest information on GCM integration with Android clients, see https://developers.google.com/cloud-messaging/android/client.

To use GCM with Stitch in an iOS app, follow these general steps:

  1. Create a valid Apple Push Notification service (APNs) certificate through the Apple Developer Member center.
  2. Copy the GoogleService-Info.plist file to your XCode project.
  3. Configure GCM and add your iOS app. When you register your app, GCM will return a registration token.

For the latest information and detailed steps on GCM integration with iOS clients, see https://developers.google.com/cloud-messaging/ios/client.