OS1 Services
Messaging and Mobile Push Noti...

Mobile Push Notifications

7min
overview developers can use the mobile push notifications apis to register their android or ios applications and receive push notifications these apis allow for customization of message formats with text, images, and action buttons additionally, developers can specify delivery options such as priority, expiration time, and device targeting the apis are compatible with both android and ios platforms, which enables developers to send notifications to users across different devices from a unified interface integration flow register a mobile application in firebase cloud messaging (fcm) register the notification configuration in the notification service send mobile push notifications step 1 register a mobile app in fcm before configuring a mobile app for the notification service, call registermobileappnotification to add fcm app credentials, including the project id, client email, and private key to the secure data storage (sds) service vault mobile app registration uses the following parameters parameter description name the application name appplatform the application platform enum \[android, ios] appid application id generated on firebase/apn project enablenotification a boolean indicating whether notifications are enabled for the app default true accountconfig projectid sds key for the globally unique, user assigned id of the parent project for the app accountconfig clientemail sds key for firebase service account accountconfig privatekey sds key for private key for firebase service account this is required below is a sample request for registering a mobile app on the android platform register mobile app { "name" "my app", "appplatform" "android", "appid" "com example myapp", "enablenotification" true, "accountconfig" { "android" { "projectid" "my project id", "clientemail" "client email\@example com", "privatekey" "private key 123" } } } upon success, the response will include a unique id for the registered app step 2 register the notification configuration call registerappnotificationconfig to set the default configuration for your notifications on the android or ios platform each platform has it's own configuration options parameter description collapsekey the collapse key for the message the collapse key serves as an identifier for a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed priority fcm concept that controls when the message is delivered ttl time to live duration of the message in milliseconds restrictedpackagename package name of the application where the registration tokens must match in order to receive the message icon icon resource for the android notification color notification icon color in #rrggbb format sound file name of the sound to be played when the device receives the notification tag notification tag this is an identifier used to replace existing notifications in the notification drawer if not specified, each request creates a new notification clickaction action associated with a user click on the notification if specified, an activity with a matching intent filter is launched when a user clicks on the notification bodylockey key of the body string in the app's string resource to use to localize the body text bodylocargs an array of resource keys that will be used in place of the format specifiers in the bodylockey titlelockey key of the title string in the app's string resource to use to localize the title text titlelocargs an array of resource keys that will be used in place of the format specifiers in titlelockey channelid the android notification channel id (new in android o) the app must create a channel with this channel id before any notification with this channel id can be received if you don't send this channel id in the request, or if the channel id provided has not yet been created by the app, fcm uses the channel id specified in the app manifest ticker sets the "ticker" text, which is sent to accessibility services prior to api level 21 (lollipop), sets the text that is displayed in the status bar when the notification first arrives sticky when set to false or unset, the notification is automatically dismissed when the user clicks it in the panel when set to true, the notification persists even when the user clicks it eventtimestamp for notifications that inform users about events with an absolute time reference, sets the time that the event in the notification occurred notifications in the panel are sorted by this time localonly sets whether or not this notification is relevant only to the current device some notifications can be bridged to other devices for remote display, such as a wear os watch this hint can be set to recommend this notification not be bridged notificationpriority sets the relative priority for this notification this priority is processed by the client after the message has been delivered defaultsound if set to true, use the android framework's default sound for the notification defaultvibratetimings if set to true, use the android framework's default vibrate pattern for the notification defaultlightsettings if set to true, use the android framework's default led light settings for the notification vibratetimingsmillis set the vibration pattern to use pass in an array of milliseconds to turn the vibrator on or off the first value indicates the duration to wait before turning the vibrator on the next value indicates the duration to keep the vibrator on subsequent values alternate between duration to turn the vibrator off and to turn the vibrator on visibility sets the visibility of the notification notificationcount sets the number of items this notification represents may be displayed as a badge count for launchers that support badging imageurl url of an image to be displayed in the notification parameter description priority fcm concept that controls when the message is delivered imageurl url of an image to be displayed in the notification sound notification tag this is an identifier used to replace existing notifications in the notification drawer if not specified, each request creates a new notification criticalsound volume the sample requests below registers app notification configurations for android and ios android config { "name" "my android app", "appplatform" "android", "appid" "com example myandroidapp", "enablenotification" true, "accountconfig" { "android" { "projectid" "android project id", "clientemail" "android client email\@example com", "privatekey" "android private key 123" } }, "androidconfig" { "collapsekey" "my collapse key", "priority" "high", "ttl" 3600000, "restrictedpackagename" "com example myandroidapp", "icon" "ic notification", "color" "#ff0000", "sound" "default", "tag" "my notification tag", "clickaction" "open activity 1", "bodylockey" "notification body", "bodylocargs" \[ "arg1", "arg2" ], "titlelockey" "notification title", "titlelocargs" \[ "arg1", "arg2" ], "channelid" "channel id 1", "ticker" "new notification", "sticky" false, "eventtimestamp" "2023 06 20t10 00 00z", "localonly" false, "notificationpriority" "default", "defaultsound" true, "defaultvibratetimings" true, "defaultlightsettings" true, "vibratetimingsmillis" \[ 1000, 500, 1000, 500 ], "visibility" "public", "notificationcount" 3, "imageurl" "https //example com/image jpg" } } ios config { "name" "my ios app", "appplatform" "ios", "appid" "com example myiosapp", "enablenotification" true, "accountconfig" { "ios" { "projectid" "ios project id", "clientemail" "ios client email\@example com", "privatekey" "ios private key 123" } }, "iosconfig" { "priority" 10, "sound" "default", "volume" 1 0, "criticalsound" true, "imageurl" "https //example com/image jpg" } } upon success, the response will include a unique id for the registered notification configuration step 3 send mobile push notifications call sendmobilepushnotifications to send mobile push notifications for the android or ios platform this call supports multiple notifications in a single api call, and notifications to multiple devices the following examples show the following sending multiple notifications to a single device sending notifications to multiple devices multiple notifications to a single device { "notifications" \[ { "appplatform" "android", "devicetokens" \[ "android device token" ], "body" { "title" "android notification 1", "body" "this is the first notification message for the android device ", "data" { "key1" "value1", "key2" "value2" } }, "androidconfig" { "collapsekey" "android collapse key 1", "priority" "high", "ttl" 3600000, "notificationpriority" "default", "defaultsound" true, "defaultvibratetimings" true } }, { "appplatform" "android", "devicetokens" \[ "android device token" ], "body" { "title" "android notification 2", "body" "this is the second notification message for the android device ", "data" { "key3" "value3", "key4" "value4" } }, "androidconfig" { "collapsekey" "android collapse key 2", "priority" "normal", "ttl" 5400000, "notificationpriority" "high", "defaultsound" false, "defaultvibratetimings" false } } ] } notification to multiple devices { "notifications" \[ { "appplatform" "android", "devicetokens" \[ "android device token 1", "android device token 2" ], "body" { "title" "new android notification", "body" "this is a sample notification message for android devices ", "data" { "key1" "value1", "key2" "value2" } }, "androidconfig" { "collapsekey" "android collapse key", "priority" "high", "ttl" 3600000, "notificationpriority" "default", "defaultsound" true, "defaultvibratetimings" true } }, { "appplatform" "ios", "devicetokens" \[ "ios device token 1", "ios device token 2" ], "body" { "title" "new ios notification", "body" "this is a sample notification message for ios devices ", "data" { "key1" "value1", "key2" "value2" } }, "iosconfig" { "priority" 10, "sound" "default", "volume" 1 0, "criticalsound" true } } ] } in this example, the request body includes the following properties notifications an array of notification objects for the same device android notification 1 appplatform the platform of the app (in this case, "android") devicetokens an array containing a single device token for the android device body an object containing the notification content for the first notification androidconfig an object containing android specific notification configuration for the first notification android notification 2 appplatform the platform of the app (in this case, "android") devicetokens an array containing the same device token for the android device body an object containing the notification content for the second notification androidconfig an object containing android specific notification configuration for the second notification this request sends multiple notifications to a single android device using different notification content and android specific configuration options for each notification note make sure to replace the android device token with the actual device token of the android device you want to send the notifications to in this example, the request body includes the following properties notifications an array of notification objects for different platforms android notification appplatform the platform of the app (in this case, "android") devicetokens an array of device tokens for android devices body an object containing the notification content for android devices androidconfig an object containing android specific notification configuration ios notification appplatform the platform of the app (in this case, "ios") devicetokens an array of device tokens for ios devices body an object containing the notification content for ios devices iosconfig an object containing ios specific notification configuration this request sends notifications to multiple devices across different platforms (android and ios) using the provided notification content and platform specific configuration options note make sure to replace the tokens arrays with the actual device tokens you want to send the notifications to for each platform upon success, the response includes an accepted message parameter