Announcement

 

Property

Type

Description

name

string

Unique name of the campaign (64 characters max).

id

integer

read-only parameter

Unique identifier of the campaign.

audience

object

Optional.

Specify which users will be targeted by this campaign (65535 bytes max, see Audience format). By default, all users will be targeted.

System_CAPS_noteNote

If you set pushMode property to manual, the only thing you can specify in the audience is the push quota filter.

category

string

Optional. Category of the campaign (64 characters max). Categories can be used on the application side to customize campaigns.

pushMode

string

Optional. Defines how the campaign is pushed. Valid values are:

  • real-time : Never ending campaign, the campaign will be delivered to your existing users and also to your new users.

  • one-shot : In this mode, the campaign will be delivered only to your existing users (campaign will stop after that).

  • manual : In this mode, the campaign will not be pushed automatically to devices. You will have to use the Push campaign command to push the campaign to your end-users. Campaigns can be pushed multiple times to the same device.

Default value: real-time

type

string

Type of announcement. Valid values are:

  • text/plain : Text-only announcement: body property should only contain plain text.

  • text/html : HTML announcement: body attribute can contain HTML code.

  • only_notif : Notification-only announcement. With this kind of announcements, the body, title, actionButtonText and exitButtonText are ignored.

deliveryTime

string

Defines when the campaign should be delivered. Valid values are:

  • any : Campaign will be delivered as soon as possible.

  • background : (iOS only) Campaign will be only delivered when the application is in background (out of app).

  • session : Campaign will be delivered when the application is running.

deliveryActivities

array

Optional. Array containing the list of activities in which the campaign can be delivered. deliveryTime must be set to session. If the platform is iOS, this option can also be set if deliveryTime is set to any. In that case, if the campaign is received when the application is launched, it will be delivered only in the specified list of activities.

startTime

string

Optional. The date at which the campaign should be started. The date shall conform to the following format: yyyy-MM-dd HH:mm'Z'.

System_CAPS_noteNote
  • If you set pushMode property to manual, this attribute will be ignored.

  • If you set pushMode property to one-shot, then the timezone attribute must be specified.

Example: 2011-11-21 15:23Z

endTime

string

Optional. The date at which the campaign should be finished. The date shall conform to the following format: yyyy-MM-dd HH:mm'Z'.

Example: 2011-11-21 15:23Z

timezone

string

Optional. The id of the time zone to use for the startTime and endTime dates
(see Supported Time-Zones for a list of valid values). If not provided, the two date attributes will be expressed using the device timezone.

Example: America/Los_Angeles

notificationType

string

Optional. Android only. Defines how the notification should be displayed. Valid values are:

  • system : Display the notification using a standard system notification.

  • popup : Display the notification using a in-app banner notification.

Default value: popup

notificationIcon

boolean

Optional. A flag indicating whether or not you want to display the resource icon in notification content.

Default value: true

notificationCloseable

boolean

Optional. A flag indicating whether or not you want the notification to be closeable.

Default value: true

notificationVibrate

boolean

Optional. Android only. A flag indicating whether or not you want the system notification to make a vibration. The notificationType property must be set to system.

Default value: false

notificationSound

boolean

Optional.

  • Android : A flag indicating whether or not you want the system notification to make a sound. The notificationType property must be set to system.

  • iOS : A flag indicating whether or not you want the native Apple Push notification to make a sound. The deliveryTime property must be set to any or background. This will play the ‘default’ sound. If you want to play a custom sound, see the notificationOptions property.

  • Windows : A flag indicating whether or not you want the native Windows Notification Service to make a sound. The deliveryTime property must be set to any.

Default value: falseiOS only

notificationBadge

boolean

Optional. A flag indicating whether or not you want the native Apple Push notification to update the badge icon to the number of unread messages. The deliveryTime property must be set to any or background.

Default value: false

notificationTitle

string

Optional. Title of the notification (2000 characters max).

This field supports AppInfo markers.

notificationMessage

string

Optional. Title of the notification (4000 characters max).

This field supports AppInfo markers.

notificationImage

string

Optional. Optional image encoded in base 64 (65535 bytes max).

Usually included in the right part of in app notifications (or as a banner if there is neither text nor content icon).

For Android system notifications, the image is used as the large icon (displayed only on Android 3+).

notificationOptions

object

Optional. Additional platform specific options as a sub JSON object. The available properties are:

Property Name

Type

Description

bigText

string

Optional. Android 4.1+ only. Multi line message shown in expanded notifications on Android 4.1+ devices (4000 characters max).

The notificationType property must be set to system.

bigPicture

string

Optional. Android 4.1+ only. URL of a remote image displayed in expanded notifications on Android 4.1+ devices with the following constraints:

  • The URL length is limited to 2000 characters.

  • The image size must be less than 4 MiB.

  • The following MIME types are supported:

    • image/png

    • image/jpeg

    • image/gif

    • image/webp

    • image/bmp

    • mage/x-bmp

    • image/x-ms-bmp

  • URL scheme must be HTTP or HTTPS (with valid SSL certificate).

  • Incompatible with bigText, only one of the fields can be set.

  • The notificationType property must be set to system.

sound

string

Optional. iOS only. The name of a sound file in the application bundle. The sound in this file is played as an alert. If the sound file doesn’t exist or default is specified as the value, the default alert sound is played. The audio must be in one of the audio data formats that are compatible with system sounds; see Preparing Custom Alert Sounds for details.

The deliveryTime property must be set to any or background.

actionText

string

Optional. iOS only. The action text is the title of the right button of the alert or the value of the unlock slider, where the value replaces ‘unlock’ in ‘slide to unlock’. ‘View’ (localized to the preferred language) is used as the default value.

The deliveryTime property must be set to any or background.

title

string

Optional. Title of the announcement (128 characters max).

This field supports AppInfo markers.

body

string

Optional for notif-only announcement. Body of the announcement (65535 bytes max).

This field supports AppInfo markers.

actionButtonText

string

Optional. Text of the action button (64 characters max).

exitButtonText

string

Optional. Text of the exit button (64 characters max).

actionUrl

string

Optional. URL to launch when the announcement is actioned (2000 characters max).

This field supports AppInfo markers.

localization

object

Optional. Reach campaigns can be localized using an optional JSON object. The JSON key is a two-character language code as specified by the ISO 639-1 standard. The corresponding value is an object containing the localizable properties: title, body, notificationTitle, notificationMessage, notificationImage, notificationOptions, actionButtonText, exitButtonText, actionUrl.

Example:

"localization": {
  "en": {
    "title": "Foo app is now available",
    "body": "This is a great app, that allows you to bla bla...",
    "notificationTitle": "New application available right now!",
    "notificationMessage": "Click here to download this great app.",
    "actionButtonText": "Download now",
    "exitButtonText": "Later",
    "actionUrl": "http://store.download.com/?id=123&lang=en"
  },

  "fr": {
    "title": "L'application foo est maintenant disponible",
    "body": "Voici une application géniale qui vous permet de bla bla...",
    "notificationTitle": "Nouvelle application disponible dès maintenant!",
    "notificationMessage": "Cliquez ici pour télécharger cette application.",
    "actionButtonText": "Télécharger maintenant",
    "exitButtonText": "Plus tard",
    "actionUrl": "http://store.download.com/?id=123&lang=fr"
  }
}

AppInfo markers are special strings which are replaced with user information (also known as appInfo) when the campaign is pushed. This is used to create personalized campaigns based on appInfo.

The format of the replacement string is ${<appInfo>} where <appInfo> is the key of the appInfo that should be replaced. The appInfo of a device can be updated using the Tag devices command or using the SDK’s sendAppInfo: function.

For instance, consider the following text:

Hello ${name}.

When the campaign is pushed on a device, ${name} is replaced with the content of the appInfo identified with key name for the corresponding user.

Since personalization works by replacing a marker by its related appInfo content, you have to make sure the user has the proper appInfo defined. Here we suppose the targeted user has an appInfo named ${name} with value being set to the name of the user.

See the format above to know which fields are supporting appInfo markers.

A text/plain announcement:

{
  "name": "MyAnnouncement",
  "type": "text/plain",
  "audience": {"expression" : "not German", "criteria": {"German": { "type": "language", "name": "de"} } },
  "deliveryTime": "activity",
  "deliveryActivities": ["Main", "Settings"],
  "startTime": "2011-10-23 17:34Z",
  "endTime": "2011-10-25 17:34Z",
  "notificationType": "system",
  "notificationTickerIcon": true,
  "notificationIcon": true,
  "notificationCloseable": true,
  "notificationSound": false,
  "notificationVibrate": false,
  "title": "Foo app is now available",
  "body": "This is a great app, that allows you to bla bla...",
  "notificationTitle": "New application available right now!",
  "notificationMessage": "Click here to download this great app.",
  "actionButtonText": "Download now",
  "exitButtonText": "Later",
  "actionUrl": "http://store.download.com/?id=123&lang=en",

  "localization": {
    "fr": {
      "title": "L'application foo est maintenant disponible",
      "body": "Voici une application géniale qui vous permet de bla bla...",
      "notificationTitle": "Nouvelle application disponible dès maintenant!",
      "notificationMessage": "Cliquez ici pour télécharger cette application.",
      "actionButtonText": "Télécharger maintenant",
      "exitButtonText": "Plus tard",
      "actionUrl": "http://store.download.com/?id=123&lang=fr"
    }
  }
}

A notification-only announcement:

{
  "name": "MyAnnouncement",
  "type": "only_notif",
  "audience": {"expression" : "not German", "criteria": {"German": { "type": "language", "name": "de"} } },
  "deliveryTime": "session",
  "startTime": "2011-10-23 17:34Z",
  "endTime": "2011-10-25 17:34Z",
  "notificationType": "popup",
  "notificationTitle": "New application available right now!",
  "notificationMessage": "Click here to download this great app.",
  "actionUrl": "http://store.download.com/?id=123&lang=en",

  "localization": {
    "fr": {
      "notificationTitle": "Nouvelle application disponible dès maintenant!",
      "notificationMessage": "Cliquez ici pour télécharger cette application.",
      "actionUrl": "http://store.download.com/?id=123&lang=fr"
    }
  }
}
Show: