Send push notifications to segments of your users.

To Field

There are three options for target devices:

  • "*": will target everyone
  • { "audience": "AUDIENCE_ID" }: an object with key audience and the value being the Audience ID. Will target all users in the specified audience. You can retrieve an ID via Audiences API or as a result of creating an on-the-fly audience (see below).
  • [{ "name": "CRITERIA_TYPE", "criteria": [CRITERIA_1, CRITERIA_2, …]}, {…}]: an array of one or more filters for creating an on-the-fly audience (see Filters below). Will target devices that match the specified criteria.

🚧

Sending to All

Be extremely careful with this endpoint during testing, especially when using "to": "*" . We recommend setting up a different app on Sailthru Mobile from your production app to avoid accidental communication with your users.

Targeting test devices

You can send notification to your testers by flagging your test devices as 'development' within the Sailthru Mobile dashboard (see [Testing Developer Push Notifications])(doc:testing-developer-push-notifications). When you do so, you can send a push notification to your devices by creating this audience:
[{"name": "development", "criteria": [true]}]

📘

Testing notifications on iOS

By default, Xcode builds your app against the Debug scheme, which maps to your Development provisioning profile which in turn can only talk to the Sandbox APNS.

If your Xcode scheme is Debug, make sure to target your Device ID using an on-the-fly audience, and make sure your device is in development mode. You can set this up here: Testing Developer Push Notifications.

Filters

A filter is an object composed of three attributes: name, criteria and not_filter.

Filter attribute

Details

name

String. Device attribute on which the criteria will be applied.

Example: { "name": "locale", criteria: ["en_US"] } will match devices with en_US locale. See the list of valid names/attributes below.

criteria

Array with values to match.

Provide at least one element of type string, integer, float, boolean or a range object (see below how to define a range object).

not_filter

Boolean. When true, it will match devices that don't match the criteria. Default is false.

Valid names/attributes for a filter

Name/Attribute

Description

locale

Locale used on the device, specified as a combination of ISO 639-1 and ISO 3166-1 alpha-2 e.g. en_NZ, fr_FR.

time_zone

Time zone used on the device. Possible values can be found here.

created_at

Date of device registration

registered_at

Date of last device update

badge

Current badge count

os_name

Device OS name

os_version

Device OS version

app_version

App version

sdk_version

Carnival SDK version

device_id

Carnival generated Device ID

country

Country based on user location (can be inaccurate, since sometimes the user don't enable GPS tracking and this value be defined using the user IP). Refer to Known Countries for a list of valid values.

marketing_name

Device model.

Examples: iPhone 5, iPhone 6, Samsung Galaxy S5

user_id

The ID assigned to the user.

user_email

The email address of the user of a given device

development

Whether or not to target development devices. Boolean.

location

Last available location of the user (being GeoIP or GPS location).

sdk_location

Last available GPS location of the user.

You can see valid values for these keys by querying Audience Builder in the dashboard.

Filtering by custom attributes

The filter name should be composed as follows: custom. + type of attribute (string, integer, float, date or boolean). + attribute_name.

Examples:

Data type

Prefix

Example

String

custom.string.

custom.string.favorite_color

Date

custom.date.

custom.date.last_purchased

Integer

custom.integer.

custom.integer.tier_points

Float

custom.float.

custom.float.lifetime_value

Boolean

custom.boolean.

custom.boolean.is_paid_user

Filtering by custom events

The filter name should be composed as follows: events. + source + event name. Events collected by the SDK do not have a source.

Examples:

Source

Prefix

Example

SDK

events.

events.checkout_completed

Events collected via Devices / Events or Users / Events

events.Public Api.

events.Public Api.instore_purchase_completed

Auto Analytics: Google Analytics

events.Google Analytics.

events.Google Analytics.message_stream_user

Auto Analytics: Adobe Analytics

events.Adobe Analytics.

events.Adobe Analytics.checkout_started

Auto Analytics: Mixpanel

events.Mixpanel.

events.Mixpanel.tutorial_started

Auto Analytics: Localytics

events.Localytics.

events.Localytics.tutorial_completed

Auto Analytics: Flurry

events.Flurry Analytics.

events.Flurry Analytics.shared_post_on_twitter

Auto Analytics: Amplitude

events.Amplitude.

events.Amplitude.video_played

Specifying criteria ranges

A range is an object with at least of the following keys: gt, lt, gte and lte.

Examples of valid ranges:

  • { "gt": 0 } returns values greater than 0
  • { "gt": 0, "lt": 10 } returns values greater than zero and less than 10 (non-inclusive)
  • { "gte": 0 } returns values greater than or equal to 0
  • { "gt": "now-1d" } return devices where this event have hapenned after yesterday

Range key

Description

gt

Greater than value

lt

Less than value

gte

Greater than or equal to value

lte

Less than or equal to value

Using Math Date for event last happened at

You can filter devices by the last time that an event happened. You do it using the same criteria range method but with a special math date syntax.

Example of valid math date ranges:

  • { "gt": "now-1d" } return devices where this event happened after yesterday
  • { "gt": "now-2M" } return devices where this event happened after 2 months ago
  • { "gt": "now-2w" } return devices where this event happened after 2 weeks ago
  • { "lt": "now-1y" } return devices where this event happened before 1 year ago
  • { "gt": "now-1y", "lt": "now-1d" } return devices where this event happened between 1 year ago and yesterday

The supported units are:

Letter

Unit

y

years

M

months

w

weeks

d

days

h or H

hours

m

minutes

s

seconds

More examples of supported Math Date expressions:

  • now+1h: The current time plus one hour, with ms resolution.
  • now+1h+1m: The current time plus one hour plus one minute, with ms resolution.
  • now+1h/d: The current time plus one hour, rounded down to the nearest day.
  • 2015-01-01||+1M/d: 2015-01-01 plus one month, rounded down to the nearest day.

Filtering by distance

location and sdk_location are the only fields that can be filtered by distance.

The filter criteria must have the following keys:

Key

Description

Example

point

A latitude and longitude object

{ "latitude" : -41.28664, "longitude" : 174.77557 }

distance

A number

10.5

unit

The unit of distance used. It can be one of the following: in, inch, yd, yards, ft, feet, km, kilometers, nauticalmiles, mi, miles m, meters

"kilometers"

Example:

{ 
  "name": "sdk_location", 
  "criteria": [{ "point" : { "latitude" : -41.1339, "longitude": 174.8406 }, 
                    "distance" : 4, "unit" : "kilometers" }] }

Filtering by a polygon

location and sdk_location are the only fields that can be filtered by a polygon.

The filter criteria must have the key polygon with at least 3 points with latitude and longitude. Example:

{ 
  "name": "location",
  "criteria": [{ "polygon" :
    [{ "latitude" :-41.31243, "longitude" : 174.75154 }, 
     { "latitude" :-41.30341, "longitude" : 174.96063 }, 
     { "latitude" :-41.19293, "longitude" : 174.91806 }, 
     { "latitude" :-41.20029, "longitude" : 174.76511 }]
   }] 
}

📘

Polygon & Distance combined

Polygon and distance filters can be mixed in a single criteria. For example:

{ 
  "name": "location",
  "criteria": [
    { "point" : { "latitude" : -41.1339, "longitude": 174.8406 }, 
                      "distance" : 4, "unit" : "kilometers" },
    { "polygon" :
      [{ "latitude" :-41.31243, "longitude" : 174.75154 }, 
       { "latitude" :-41.30341, "longitude" : 174.96063 }, 
       { "latitude" :-41.19293, "longitude" : 174.91806 }, 
       { "latitude" :-41.20029, "longitude" : 174.76511 }]  }
  ] 
}

Updating notifications

You can update a notification (including its payload) by specifying a collapse_key in the notification payload. This key acts as a unique identifier, so that you can reference the same notification in subsequent Notifications API requests.

Message attributes

You can include a hash inside the request payload using the custom key. For example, if you had a message stream that had multiple categories, you could have a hash like:

"custom" : { "category" : "announcements" }

On-the-fly audiences

On-the-fly audiences are persisted in your list of Audiences. When you send a notification, we return an audience ID in the response. You can use the Audience ID in the to.id to retrieve your Audience ] for example when you want to check the targeted device count, or to get a list of devices in this audience.

You will be given one Audience ID for each on-the-fly audience. If you use the same on-the-fly spec more than once you will be given the same Audience ID.

This example shows you how to create an on-the-fly audience, retrieve its ID and device count, and reuse it to send a push notification at a later stage.

// First, create an on-the-fly audience when sending a push notification
curl -X POST -u :WRITE_API_KEY -H "Content-type: application/json" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{
  "notification": {
    "to": [{ "name": "events.video_plays", "criteria": [{ "gt": 10 }]}, { "name": "custom.string.mykey", "criteria": ["tag2"]}],
    "payload": { /* Your push payload goes here */ }
  }
}'

// The response will be similar to this:
{
  "created_at": "2017-03-09T13:23:37.488Z",
  "state": "scheduled",
  "id": "58c157595c50nz000e347f79",
  "to": {
    "id": "589b54e38b1ny0000876e528",
    "type": "Audience"
  },
  "notification": { /* Notification payload */ }
}

// Next, use the `to.id` value to check the targeted device count.
// Make sure your API Key has Read permissions.
curl -X GET -u :READ_API_KEY https://api.carnivalmobile.com/v5/audiences/589b54e38b1ny0000876e528

// Response
{
    "audience": {
        "name": "api_audience_571a2cb135c4f3008028728_f9b10204a59727a528a4d33d262591f33de7f9fad977e4e1fb70aa4d533b162",
        "created_at": "2017-03-21T19:39:25.324Z",
        "updated_at": "2017-03-21T19:39:25.324Z",
        "id": "589b54e38b1ny0000876e528",
        "device_count": 42
    }
}

// You can reuse this on-the-fly audience for another push by specifying its ID
curl -X POST -u :WRITE_API_KEY -H "Content-type: application/json" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{
  "notification": {
    "to": { "audience": "589b54e38b1ny0000876e528" },
    "payload": { /* Your push payload goes here */ }
  }
}'

Custom Keys and Values

Some keys are reserved by the Apple, Google Cloud Message and/or Sailthru Mobile system:

  • alert
  • sound
  • badge
  • category
  • mutable_content
  • content_available
  • available
  • from
  • gcm
  • _st
  • _u (used for Deep Linking)
  • Any value prefixed by google

Other keys and values will be assumed to be custom keys, and will be included in the push payload.

Language
Authentication
Basic
base64
: