Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reverted from v. 49

...

Table of Contents
maxLevel4

 

Sending push notifications

 

To send a push notification, you must provide the Dashboard the following information:

 

  • Notification recipients and channel – If your application users were subscribed using session-based subscriptions, you can send a notification to specific API Builder users subscribed to a particular channel. For token-based subscriptions, you can send notifications to all users subscribed to a particular channel, or all users regardless of their channel subscriptions.
  • Notification schedule – You can send a notification immediately, or schedule it to be sent at a future date and time. Scheduled notifications can be one-time or recurring.
  • Notification payload – The content of the notification, which consists minimally of an alert string to display, and optionally a sound to play or badge display. See About Notification Payloads.

 

To send a notification to users located in a geographic area, the application must have first provided their current location to API Builder. For details, see Updating Subscriptions with Device Location

 

Appcelerator Dashboard provides two views for sending notifications, Standard and Advanced. The Standard view provides an easy way to send notifications without having to understand the payload structure. In the Advanced view, you manually create the JSON payload. The advanced form provides additional flexibility, such as including custom payload fields. 

 

If you prefer can use the PushNotification.notify or PushNotification.notify_tokens REST APIs to send push notifications.

 

Note

A warning will be displayed if you attempt to perform a push with an expired or disabled iOS certificate.

 

To send a push notification from the Dashboard:

 

  1. In the Dashboard, select your application from the Projects view.
  2. From the left-side navigation, select Push Notifications.
  3. Select Send to open the Send Push Notification form
  4. Select either the Standard or Advanced.
  5. Select Recipients and (optionally) the notification Channel Name:
    1. To send a notification to all users regardless of their channel subscriptions, select All Users and leave the Channel Name field blank. 
    2. To send a notification to all users subscribed to a particular channel, select All Users and enter the channel name in the Channel Name field.
    3. To send a notification to specific users who are subscribed to a particular channel, select Specific Users, then:
      1. Click the add (+) button in the To Users field.
      2. Select the desired recipients from the list of users. To locate a particular user, enter their username in the search field.
      3. In the Channel Name field enter the name of the target channel subscription. Note: You must specify a channel when sending a notification to specific users.
    4. To send a notification to all users located within a geographic selection, select Geographic Selection, then:
      1. Click the add (+) button in the Place field and select an existing place. This defines the center points of the geographic selection. The selected Place must have a defined latitude and longitude.
      2. In the Radius field, enter the distance (in Miles or Meters) from the selected Place to define the size of the geographic selection.

  6. To specify when to deliver the notification, in the Send When field, select one of the following options:
    1. To send the notification immediately, select Send Now.
    2. To schedule a one-time notification, select One-Time and then select the delivery date and time (All times are in UTC.)
    3. To schedule a recurring notification, select Recurring, select the start date and time, the end date, and the recurrence interval: Daily, Weekly, or Monthly. (All times are in UTC.)
  7. To define the notification payload using the Standard view:
    1. In the Alert field, enter the notification message to display on the device.
    2. In the Channel Name field, enter the channel name to use for notifications. A Channel is required when not sending a push to all users.
    3. In the Badge field, enter a badge value. See Notification Badges for details.

    4. In the Sound field, select None, Default, or Custom. See Notification Sounds for details.

    5. For iOS devices:

      1. In the Content-Available field, check the box to indicate that new content is available. This is used to support Newsstand apps and background content downloads.

      2. In the Category field, enter the name of the category to use for interactive notifications. See iOS Interactive Notifications.

    6. For Android devices:
      1. In the Vibrate field, select No or Yes to have the device vibrate or not upon receipt of the notification.
      2. In the Title field (Android, only), select the title to display in the Alert message. See Notification Titles for details.
      3. In the Icon field (Android, only), specify the name of the image file to display as the notification icon. See Notification Icons for details.
      4. In the Collapse Key field (Android, only), identify a group of messages (for example, with {{collapse_key: “Updates Available”}}) that can be collapsed, so that only the last message gets sent when delivery can be resumed.
      5. In the Time to Live field (Android, only), specify how long (in seconds) the message should be kept in Firebase Cloud Messaging storage if the device is offline.
      6. In the Priority field (Android, only), select either Normal or High. Set to high priority if the message is time-critical and requires the user's immediate interaction.
  8. To define the notification payload using the Advanced view:
    1. In the Custom JSON field, enter a valid JSON string (see Custom JSON Payloads for details).

  9. Click Send Now. 

About Notification Payloads

The content, or payload, of a push notification, is a JSON-encoded object whose fields contain the payload values. The JSON object typically contains one of the "standard" notification fields. Standard fields are supported by both iOS and Android devices. Some fields are platform-specific, such as icon or title, that are only used by Android, or category and content-available, that are only used by iOS 8 devices and later.

Standard fields include the following: 

  • alert – The notification message displayed to the user. 
  • badge – The number to display in the notification. See Notification badges.
  • sound – The name of an audio file to play when the notification arrives, minus its extension. See Notification sounds.

Android devices support the following additional fields:

  • icon – The name of the image file to display as the icon, minus its extension. 
  • title – Title displayed above the alert text. Defaults to the application name. 
  • vibrate – A Boolean that the device to vibrate momentarily upon receipt. 

See Android-specific notification fields for more information about specifying these fields.

iOS 8 devices and later support the following additional fields:

  • category – The name of the category to use for interactive notifications. See iOS Interactive Notifications for more information.
  • content-available – If set to 1, indicates that new content is available. This is used to support Newsstand apps and background content downloads.

The payload can also include custom fields that your application can read and use as desired. See Custom JSON Payloads for an example of using custom fields.

Custom JSON payloads

Appcelerator Dashboard provides two forms, Standard and Advanced, for you to compose the payload. In the Standard form, you use common form controls to compose the payload, without having to write JSON code. In the Advanced form, you manually enter the JSON-encoded string that's sent in the notification. The JSON object can contain any of the standard fields discussed in About Notification Payloads, or custom fields specific to your application. For example, the following payload contains alert and sound fields, as well as a custom field named high_score.

Image Added

Below is a more advanced custom JSON payload:

Code Block
linenumberstrue
{
    "alert": "Sample alert",
    "badge": "+2",
    "category": "sampleCategory", 
    "icon": "little_star",
    "sound": "door_bell",
    "title": "Example",
    "vibrate": true,
    "custom_field_1": "Arrow Push Rocks!",
    "custom_field_2": "Hi Push"
}

When the device receives this payload, it will do the following:

  • Display the "Sample alert" message.
  • Increment the current badge value by two.
  • Play the "door_bell" audio file.
  • On Android devices: 
    • The notification title will be set to "Example"
    • The device will vibrate
    • The "little_star" icon will be displayed in the notification area.
  • On iOS devices:
    • The user notification actions associated with the "sampleCategory" user notification category.

About JSON Payloads Delivered to Devices

The notification payload that Mobile Backend Services delivers to either FCM or GCM or APNS is slightly modified from the original JSON payload you provide to Dashboard. Also, the payloads are slightly different for Android and iOS devices.

For Android, all Android-specific fields are contained in an android dictionary, while all other iOS-only and custom fields are top-level keys of the payload. For example, the payload shown in Custom JSON payloads will be delivered to an Android application as follows:

Code Block
linenumberstrue
{
    "android": {
        "title": "Example",
        "alert": "Sample alert",
        "icon": "little_star",
        "badge": "+2",
        "sound": "door_bell",
        "vibrate": true,
    },
    "category": "sampleCategory",
    "custom_field_1": "Arrow Push Services Rocks!",
    "custom_field_2": "Hi Push"
}

For iOS devices, all iOS-specific fields are contained in an aps dictionary, while all Android-specific and custom fields are top-level keys of the payload. For example, the payload shown in Custom JSON payloads will be delivered to an iOS application as follows:

Code Block
linenumberstrue
{
    "aps": { 
        "alert": "Sample alert", 
        "badge": "+2", 
        "category": "sampleCategory", 
        "sound": "door_bell"
    }, 
    "title": "Example", 
    "icon": "little_star", 
    "vibrate": true, 
    "custom_field_1": "Arrow Push Rocks!", 
    "custom_field_2": "Hi Push" 
}

 

...