External API Structure to support additional APN parameters

This optional supplement to the API resource for sending Push notification messages via the SCG CPaaS service is to provide customers who previously accessed the Apple APN servers directly, same set of functionalities when submitting Push notification message via the Syniverse CPaaS API service.

The /messages and /message_request endpoints now supports the 'options' field in the request payload, which is a simple string-to-string map.

For now the 'options' attribute (in push notification context) is used to transfer information related to badge, notification type, and sound. The same field would be extended to allow additional arguments to be passed to APN.

APN Payload - Field Level Mapping

External API field included under 'options'	APN for iOS	Comments
push:alert:title	alert.title	Short description of the notification purpose
push:alert:subtitle	alert.subtitle	Subtitle for the notification
push:alert:launch-image	alert.launch-image	Image to be shown when the receiving app launches in response to this push notification. The filename of an image file in the application bundle, it may include the extension.
push:alert:title-loc-key	alert.title-loc-key	A key to a string in the receiving application's localized string list. Clears any previously-set literal alert title. The message in the application's string list may optionally have placeholders, which will be populated by values from the given title-loc-arg list.
push:alert:title-loc-arg:<IDX>	alert.title-loc-args	Each value for push:alert:title-loc-arg:<IDX> params will be included to string array depending on <idx> order. For example: push:alert:title-loc-arg:0=First, push:alert:title-loc-arg:5=Third push:alert:title-loc-arg:1=Second will be submitted as ["First", "Second","Third"] Values in the resulting array will be substituted one by one for the application string which corresponds to push:alert:title-loc-key value from the application strings
push:alert:subtitle-loc-key	alert.subtitle-loc-key	A key of the subtitle string in the receiving application's localized string list to be shown for the push notification Clears any previously-set literal subtitle. The message in the applications string list may optionally have placeholders, which will be populated by values from the given subtitle-loc-arg list
push:alert:subtitle-loc-arg:<IDX>	alert.subtitle-loc-args	Each value for push:alert:subtitle-loc-arg:<IDX> params will be included to string array depending on idx order. For example: push:alert:subtitle-loc-arg:1=First push:alert:subtitle-loc-arg:5=Third push:alert:subtitle-loc-arg:1=Second will be submitted as ["First", "Second","Third"] Values in the resulting array will be substituted one by one for the application string which corresponds to push:alert:subtitle-loc-key value from the application string s
push:alert:loc-key	alert.loc-key	Key of a message in the receiving application's localized string list to be shown for the push notification Clears any previously-set literal alert body. The message in the applications string list may optionally have placeholders, which will be populated by values from the given loc-arg list
push:alert:loc-arg:<IDX>	alert.loc-args	Each value for push:alert:loc-arg:<IDX> params will be included to string array depending on idx order. For example: push:alert:loc-arg:1=First push:alert:loc-arg:5=Third push:alert:loc-arg:1=Second will be submitted as ["First", "Second","Third"] Values in the resulting array will be substituted one by one for application string which corresponds to push:alert:loc-key value from the application strings
push:alert:summary-arg	alert.summary-arg	The summary argument for this notification. The string the notification adds to the category’s summary format string.
push:alert:summary-arg-count	alert.summary-arg-count	The summary argument count for this notification. The number of items the notification adds to the category’s summary format string. By default, all notifications count as a single "item" in a group of notifications. The summary argument count controls how many "items" in a "stack" of notifications are represented by a specific notification. If, for example, a notification informing a user that seven new podcasts are available, it might be helpful to set the summary argument count to 7. When "stacked," the notification would contribute an item count of 7 to the total number of notifications reported in the summary string (for example, "7 more podcasts")
push:soundx:critical	sound.critical	Critical alert flag. Set to true to enable the critical alert (false if not specified)
push:soundx:name	sound.name	Name of a sound file in your application's main bundle or in the Library/Sounds folder of your application's container directory. Specify the string "default" to play the system sound. Use "push:sound" if no critical sound or volume flag specified
push:soundx:volume	sound.volume	Volume for the critical alert’s sound (1.0 if not specified) Set this to a value between "0.0" (silent) and "1.0" (full volume)
push:thread-id	thread-id	The thread ID for this notification. According to the APNs documentation, the thread ID is: …a string value that represents the app-specific identifier for grouping notifications. The system groups notifications with the same thread identifier together in Notification Center and other system interfaces. ... By default, no thread ID is included
push:category	category	The name of the action category name for interactive remote notifications. According to Apple's documentation, this should be: ...a string value that represents the identifier property of the object you created to define custom actions.
push:target-content-id	target-content-id	The identifier of the window to be brought forward by this notification. By default, no target content ID is included.
push:appdata:n:<key1> push:appdata:s:<key2> push:appdata:o:<key3> push:appdata:n:<key4>:<IDX> push:appdata:s:<key4>:<IDX>	custom dictionary	Application-specific data. For array arguments index should start from "1". Data goes to the custom dictionary. It could be the pairs key→string_value, or key4jsonValue → json_str custom dictionary: { "key1": "value", "key2": "value2", ... } Thus options field is a simple map of string→string, to understand the type of the keys' value the following suffixes will be used: n: number s: string o: object (JSON parsable string) Array values should be homogeneous: number or string. "push:appdata:n:key4:1": "9", "push:appdata:n:key4:2": "10" will be go into the custom dictionary as the following array: "key4": [9, 10] "push:appdata:s:names:2": "Bill", "push:appdata:s:names:1": "Jack", will be go into the custom dictionary as the following array: "names": ["Jack", "Bill"]

APN Payload - Field Level Mapping Examples

Example 1

SCG Payload

curl -X POST \HOST/scg-external-api/api/v1/messaging/message_requests/ \-H 'Authorization: Bearer {Token} \-H 'Content-Type: application/json' -d '{    "to": ["psh:apn@Xa13m001g9co35SkkcHeE6@b27fe514f9f7fae149491cdd101f917ff1ec6249ee9f33f0649070f48cc8d860" ],    "from": "Xa13m001g9co35SkkcHeE6",    "body": "non localized body",    "options":{      "push:alert:loc-key": "localized-body-with-2-placeholders",      "push:alert:loc-arg:1": "value for first body placeholder",      "push:alert:loc-arg:2": "value for second body placeholder",      "push:badge": "4",      "push:alert:title": "non localized title",      "push:alert:title-loc-key": "localized-title-with-3-placeholders",      "push:alert:title-loc-arg:1": "value for first title placeholder",      "push:alert:title-loc-arg:2": "value for second title placeholder",      "push:alert:title-loc-arg:3": "value for third title placeholder",      "push:alert:subtitle": "not localized message subtitle",      "push:alert:subtitle-loc-key": "localized-subtitle-with-1-placeholder",      "push:alert:subtitle-loc-arg:1": "value for first subtitle placeholder",      "push:alert:launch-image":"launch-image-resource",      "push:alert:summary-arg":"summary arg value",      "push:alert:summary-arg-count": 25,      "push:sound":"non-critical-sound/cat.wav",      "push:soundx:name": "critical-sound/cat.wav",      "push:soundx:critical": true,      "push:soundx:volume": 0.80,      "push:thread-id": "thread id value",      "push:category": "category value",      "push:target-content-id": "target content id value",      "push:alert:tag": "tag value",      "push:alert:click_action": "click action value",      "push:alert:ticker": "ticker value",      "push:alert:sticky": true,      "push:alert:event_time": 1611014400000,      "push:alert:local_only": true,      "push:alert:notification_priority": "PRIORITY_MIN",      "push:appdata:o:address": "{\"zip\":\"223344\", \"street\": \"125 Avenue\", \"apt\":9, \"city\": \"New-York\", \"info\":{\"male\":true, \"ages\":[5,8,20]}}",      "push:appdata:s:appointmentDate": "01.01.2021",      "push:appdata:n:seats:1": "9.0",      "push:appdata:n:seats:2": "10",      "push:appdata:s:names:1": "Jack",      "push:appdata:s:names:2": "Bill"    }}'

Example 2

APN Payload

{"address": {"zip": "223344","street": "125 Avenue","apt": 9.0,"city": "New-York","info": { "male": true, "ages": [5.0, 8.0, 20.0] }},"names": ["Jack", "Bill"],"aps": {"badge": 4,"alert": {"loc-args": ["value for first body placeholder","value for second body placeholder"],"launch-image": "launch-image-resource","subtitle-loc-args": ["value for first subtitle placeholder"],"loc-key": "localized-body-with-2-placeholders","summary-arg": "summary arg value","subtitle-loc-key": "localized-subtitle-with-1-placeholder","summary-arg-count": 25,"title-loc-key": "localized-title-with-3-placeholders","title-loc-args": ["value for first title placeholder","value for second title placeholder","value for third title placeholder"]},"sound": { "name": "critical-sound/cat.wav", "critical": 1, "volume": 0.8 },"category": "category value","target-content-id": "target content id value"},"scg-message-id": "mKS-pKFyGMjRYIvbtnYdgkVf95","appointmentDate": "01.01.2021","seats": [9.0, 10]}