This topic provides information on setting up and sending push notifications with the Usergrid API backend as a service (BaaS). For high-level information, prerequisites, and tutorials, see Push notifications overview.
When you create a notification, it is scheduled to be delivered to all applicable devices immediately unless the deliver property has been set. A notification may contain multiple messages (payloads), and each payload must be associated with a notifier in order to deliver that message to the associated app. This allows a single notification to be delivered to multiple apps across various services, and is useful if you want to send messages to multiple notifiers, such as development and production versions of both Apple and Google simultaneously.
Notification can be created via POST request to the BaaS API, or in the admin portal:
This request will target a specific device entity.
Request Syntax
curl -X POST https://api.usergrid.com/<org>/<app>/devices/<device_ID>/notifications -d '{"payloads":{<notifier>:<message>}}'
This request will target all device entities.
Request Syntax
curl -X POST https://api.usergrid.com/<org>/<app>/devices/*/notifications -d '{"payloads":{<notifier>:<message>}}'
This request will target a specific user entity.
Request Syntax
curl -X POST https://api.usergrid.com/<org>/<app>/users/<username>/notifications -d '{"payloads":{<notifier>:<message>}}'
This request will target all users associated with a specific group entity.
Request Syntax
curl -X POST https://api.usergrid.com/<org>/<app>/groups/<group_path>/notifications -d '{"payloads":{<notifier>:<message>}}'
This request will target all device entities that are within a set radius of a latitude/longitude coordinate.
Request Syntax
curl -X POST https://api.usergrid.com/<org>/<app>/devices;ql=location within <radius> of <lat>,<long>/notifications -d '{"payloads":{<notifier>:<message>}}'
The following parameters can be specified when targeting push notifications.
Base URL
These parameters are used in forming the base URL of the request:
Parameter Description
org Organization UUID or organization name app Application UUID or application name
Notification
These parameters are used when forming the notification portion of the request:
Parameter Description
notifier The notifier
entity you wish to associate with the notification (see Creating notifiers for information on creating notifiers) message The push notification message that will be delivered to the user
Note: If your message contains double-quotes ("") you must escape them with a backslash
Targets
These parameters are used when specifying the notification target in the request.
Parameter Description
device UUID of a device entity. user UUID or username of a user entity. phone_type Specified in a appended query string. The type property of a device entity. group UUID or name of the group entity. latitude, longitude, radius Specified in a appended query string. The radius in meters of a user device from a latitude/longitude coordinate.
To create the new notification with the admin portal, do the following:
To create a notification to send multiple messages or target multiple platforms, see the cURL syntax for creating notifications.
To send notifications from iOS app code, you use the 11ApigeeAPSDestination11 and ApigeeAPSPayload
classes.
With ApigeeAPSDestination
, you specify where the notification should go (a particular user or device or user group, for example). With ApigeeAPSPayload
, you specify the contents of the message, including any alert text, sound, or badge (items specified by Apple as allowable notification content types). You then use ApigeeDataClient
to send the message via Apigee and Apple APNs.
The following code illustrates how to send a notification to a single user. Though this is the device on which the app itself is installed, you can imagine how you might send a notification to another device, such as one belonging to someone “following” this user. For more, see the iOS push sample application included with the Apigee iOS SDK.
- (void)sendMyselfAPushNotification:(NSString *)message completionHandler:(ApigeeDataClientCompletionHandler)completionHandler { // send to a single device -- our own device NSString *deviceId = [ApigeeDataClient getUniqueDeviceID]; ApigeeAPSDestination* destination = [ApigeeAPSDestination destinationSingleDevice:deviceId]; // set our APS payload ApigeeAPSPayload* apsPayload = [[ApigeeAPSPayload alloc] init]; apsPayload.sound = kBundledSoundNameWithExt; apsPayload.alertText = message; // Example of what a custom payload might look like -- remember that // APNS payloads are limited to a maximum of 256 bytes (for the entire // payload -- including the 'aps' part) NSMutableDictionary* customPayload = [[NSMutableDictionary alloc] init]; [customPayload setValue:@"72" forKey:@"degrees"]; [customPayload setValue:@"3" forKey:@"newOrders"]; __weak AppDelegate* weakSelf = self; // send the push notification [dataClient pushAlert:apsPayload customPayload:customPayload destination:destination usingNotifier:notifier completionHandler:^(ApigeeClientResponse *response) { if ( ! [response completedSuccessfully]) { [weakSelf alert:response.rawResponse title: @"Error"]; } if (completionHandler) { completionHandler(response); } }]; }
To schedule a notification for a later time, add the deliver parameter with a UNIX timestamp to the body of your request.
Request body syntax
'{"deliver":<unix_timestamp>,"payloads":{<notifier>:<message>}}'
To send multiple messages or target multiple platforms with a single notification entity, include multiple notifier-message pairs as a comma-separated list in the payloads object of the request body:
Request body syntax
'{"payloads":{<notifier>:<message>, <notifier>:<message>, ...}}'
If a push service can't deliver a message to a device and needs to resend it (for example, if the device is turned off), you can set a notification to expire after a certain date/time.
To do this, adding the expire parameter with a UNIX timestamp to your request body. This specifies when the service should stop trying to send the notification.
Request body syntax
'{"expire":<unix_timestamp>,"payloads":{"<notifier_name>":"<message>"}}'
NOTE: The timestamp is a UNIX timestamp and is specified in seconds.
The following are endpoints can be used to get notifications. For details on the notification properties you can get, see Notifier, Receipt, and Notification.
Getting one or more notifications:
/notifications
Getting notifications associated with one or more receipts:
/receipts/*/notification
Getting the list of devices associated with one or more notifications before the notifications are sent:
/notifications/*/queue
You can cancel a notification that's already in progress by doing the following:
curl -X PUT "https://api.usergrid.com/my-org/sandbox/notifications/<notification-uuid>" -d '{"canceled": true}'
You can view JSON for notifications by viewing their entity entries in the Data section of your application.
In the admin portal, click Data, then click the /notifications collection. You can also view notification data in the message history.
In the admin portal, click Push, then click Message History. Locate the notification for which you want to view data, then click its view details link.
curl -X DELETE "https://api.usergrid.com/<you-org>/<app>/notifications/<notification-uuid>"
After sending a notification, the BaaS generates a receipt entity that contains details about the notification. Receipts show details such as timestamps, payloads sent, and the receipt endpoints.
For information about what's contained in a receipt, see Notifier, Receipt, and Notification. Use the following endpoints to get receipts.
To get one or more receipts:
/receipts
To get receipts associated with one or more devices:
/devices/*/receipts
To get receipts for one or more notifications. For example, get receipts for notifications that had errors.
/notifications/*/receipts
The /notifications
endpoints let you create, schedule, cancel, and delete notifications. You can also use the following endpoints to accomplish the same actions for specific groups, users, devices, or any combination thereof.
Base URL: https://api.usergrid.com/my-org/my-app
/groups/*/notifications /groups/*/users/*/notifications /groups/*/users/*/devices/*/notifications /users/*/notifications /users/*/devices/*/notifications /devices/*/notifications