REFERENCE
PushNotification Class
PushNotification
is used to configure push notifications and send them from an Apex trigger.
Namespace
Messaging
Example
This sample Apex trigger sends push notifications to the connected app named
Test_App
, which corresponds to a mobile app on iOS mobile clients. The trigger fires after cases have been updated and sends the push notification to two users: the case owner and the user who last modified the case.
trigger caseAlert on Case (after update) { for(Case cs : Trigger.New)
{
// Instantiating a notification
Messaging.PushNotification msg = new Messaging.PushNotification();
// Assembling the necessary payload parameters for Apple.
// Apple params are:
// (<alert text>,<alert sound>,<badge count>,
// <free-form data>)
// This example doesn't use badge count or free-form data.
// The number of notifications that haven't been acted
// upon by the intended recipient is best calculated
// at the time of the push. This timing helps
// ensure accuracy across multiple target devices.
Map<String, Object> payload =
Messaging.PushNotificationPayload.apple(
'Case ' + cs.CaseNumber + ' status changed to: '
+ cs.Status, '', null, null);
// Adding the assembled payload to the notification msg.setPayload(payload);
// Getting recipient users
String userId1 = cs.OwnerId;
String userId2 = cs.LastModifiedById;
// Adding recipient users to list
Set<String> users = new Set<String>(); users.add(userId1);
17
Reference PushNotification Constructors
}
} users.add(userId2);
// Sending the notification to the specified app and users.
// Here we specify the API name of the connected app.
msg.send('Test_App', users);
IN THIS SECTION:
PushNotification Constructors
PushNotification Methods
PushNotification Constructors
The following are the constructors for
PushNotification
.
IN THIS SECTION:
PushNotification()
Creates a new instance of the
Messaging.PushNotification
class.
PushNotification(payload)
Creates a new instance of the
Messaging.PushNotification
class using the specified payload parameters as key-value pairs. When you use this constructor, you don’t need to call setPayload
to set the payload.
PushNotification()
Creates a new instance of the
Messaging.PushNotification
class.
Signature public PushNotification()
PushNotification(payload)
Creates a new instance of the
Messaging.PushNotification
class using the specified payload parameters as key-value pairs.
When you use this constructor, you don’t need to call setPayload
to set the payload.
Signature public PushNotification(Map<String,Object>
payload
)
Parameters
payload
Type:Map<String, Object>
The payload, expressed as a map of key-value pairs.
18
Reference
PushNotification Methods
The following are the methods for
PushNotification
. All are global methods.
IN THIS SECTION:
send(application, users)
Sends a push notification message to the specified users.
setPayload(payload)
Sets the payload of the push notification message.
setTtl(ttl)
Reserved for future use.
send(application, users)
Sends a push notification message to the specified users.
Signature public void send(String application, Set<String> users)
Parameters
application
Type: String
The connected app API name. This corresponds to the mobile client app the notification should be sent to.
users
Type: Set
A set of user IDs that correspond to the users the notification should be sent to.
Example
See the Push Notification Example .
setPayload(payload)
Sets the payload of the push notification message.
Signature public void setPayload(Map<String,Object> payload)
Parameters
payload
Type: Map<String, Object>
The payload, expressed as a map of key-value pairs.
PushNotification Methods
19
Reference PushNotificationPayload Class
Payload parameters can be different for each mobile OS vendor. For more information on Apple’s payload parameters, search for
“Apple Push Notification Service” at https://developer.apple.com/library/mac/documentation/ .
To create the payload for an Apple device, see the PushNotificationPayload Class
.
Example
See the Push Notification Example .
setTtl(ttl)
Reserved for future use.
Signature public void setTtl(Integer ttl)
Parameters
ttl
Type: Integer
Reserved for future use.
PushNotificationPayload Class
Contains methods to create the notification message payload for an Apple device.
Namespace
Messaging
Usage
Apple has specific requirements for the notification payload. and this class has helper methods to create the payload. For more information on Apple’s payload parameters, search for “Apple Push Notification Service” at https://developer.apple.com/library/mac/documentation/ .
Example
See the Push Notification Example .
IN THIS SECTION:
PushNotificationPayload Methods
PushNotificationPayload Methods
The following are the methods for
PushNotificationPayload
. All are global static methods.
20
Reference PushNotificationPayload Methods
IN THIS SECTION:
apple(alert, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
apple(alertBody, actionLocKey, locKey, locArgs, launchImage, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
apple(alert, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
Signature public static Map<String,Object> apple(String alert, String sound, Integer badgeCount,
Map<String,Object> userData)
Parameters
alert
Type: String
Notification message to be sent to the mobile client.
sound
Type: String
Name of a sound file to be played as an alert. This sound file should be in the mobile application bundle.
badgeCount
Type: Integer
Number to display as the badge of the application icon.
userData
Type: Map<String, Object>
Map of key-value pairs that contains any additional data used to provide context for the notification. For example, it can contain IDs of the records that caused the notification to be sent. The mobile client app can use these IDs to display these records.
Return Value
Type:Map<String, Object>
Returns a formatted payload that includes all of the specified arguments.
Usage
To generate a valid payload, you must provide a value for at least one of the following parameters: alert
, sound
, badgeCount
.
Example
See the Push Notification Example .
21
Reference PushNotificationPayload Methods
apple(alertBody, actionLocKey, locKey, locArgs, launchImage, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
Signature public static Map<String,Object> apple(String alertBody, String actionLocKey, String locKey, String[] locArgs, String launchImage, String sound, Integer badgeCount,
Map<String,Object> userData)
Parameters
alertBody
Type: String
Text of the alert message.
actionLocKey
Type: String
If a value is specified for the
actionLocKey
argument, an alert with two buttons is displayed. The value is a key to get a localized string in a
Localizable.strings
file to use for the right button’s title.
locKey
Type: String
Key to an alert-message string in a
Localizable.strings
file for the current localization.
locArgs
Type: List<String>
Variable string values to appear in place of the format specifiers in
locKey
.
launchImage
Type: String
File name of an image file in the application bundle.
sound
Type: String
Name of a sound file to be played as an alert. This sound file should be in the mobile application bundle.
badgeCount
Type: Integer
Number to display as the badge of the application icon.
userData
Type: Map<String, Object>
Map of key-value pairs that contains any additional data used to provide context for the notification. For example, it can contain IDs of the records that caused the notification to be sent. The mobile client app can use these IDs to display these records.
Return Value
Type: Map<String, Object>
Returns a formatted payload that includes all of the specified arguments.
22
Reference Apex Limits Functions for Push Notifications
Usage
To generate a valid payload, you must provide a value for at least one of the following parameters: alert
, sound
, badgeCount
.
Apex Limits Functions for Push Notifications
Use the Apex limits functions for push notifications to get usage information.
System.Limits
class: getLimitMobilePushApexCalls()
Returns the total number of Apex calls that are allowed per transaction for mobile push notifications.
getMobilePushApexCalls()
Returns the number of Apex calls that have been used by mobile push notifications during the current metering interval.
Push Notifications Resource
Send a mobile push notification to connected apps on users’ devices. This resource is only accessible when the session is established with a connected app that is developed in the same organization or installed in the same package as the recipient’s connected app.
Resource
/connect/notifications/push
Available version
31.0
Requires Chatter
No
HTTP methods
POST
Request body for POST
Root XML tag
<pushNotification>
JSON example
{
}
Properties
"appName" : "TestApp",
"namespace" : "abc",
"userIds" : ["005x00000013dPK", "005x00000013dPL"],
"payload" : "{'aps':{'alert':'test', 'badge':0, 'sound':'default'}}"
Name Type
appName namespace
String
String
Description
The namespace of the connected app that the push notification is sent to.
Required or
Optional
The API name of the connected app that the push notification is sent to.
Required
Required if the namespace is set
Available
Version
31.0
31.0
23
Reference Push Notification Limits
Name
payload userIds
Request parameters for POST
Type Parameter
Name
appName
String namespace payload userIds
String
String
String[]
Type
String
String[]
Description Required or
Optional
Required The push notification payload in JSON format.
The push notification recipient user ids.
Required
Available
Version
31.0
31.0
Description
The API name of the connected app that the push notification is sent to.
Required or
Optional
Required
The namespace of the connected app that the push notification is sent to.
Required if the namespace is set
Required The push notification payload in JSON format.
The push notification recipient user ids.
Required
Available
Version
31.0
31.0
31.0
31.0
Push Notification Limits
Push notification limits apply to test push notifications as well as to production notifications.
Note: The limits described here are for core Salesforce push notifications. They do not apply to Marketing Cloud MobilePush notifications. For further information on Marketing Cloud usage, see developer.salesforce.com/docs/atlas.en-us.mc-sdks.meta/mc-sdks/mobile-push-sdk.htm
.
The maximum push notifications allowed for each mobile app associated with your Salesforce org depends on the type of app.
Mobile application type
Provided by Salesforce (for example, the Salesforce app)
Developed by your company for internal employee use
Installed from the AppExchange
Maximum notifications per app per day
50,000
35,000
5,000
Only deliverable notifications count toward this limit. For example, consider the scenario where a notification is sent to 1,000 employees in your company, but 100 employees haven’t installed the mobile application yet. Only the notifications sent to the 900 employees who have installed the mobile application count toward this limit.
Each test push notification that is generated through the Test Push Notification page is limited to a single recipient. Test push notifications count toward an application’s daily push notification limit.
24
Reference Error Messages for Push Notifications
Error Messages for Push Notifications
If you get an error message while sending a push notification from the Send Test Notification page, check the following table for suggestions on how to fix the error.
Message
Daily push rate limit has been exceeded for this connected application
Certificate is not accepted by Apple Push Notification service
Certificate is revoked
Certificate expired
Certificate not valid yet
Invalid certificate or password
Invalid recipient or payload
Payload exceeds maximum size
Unable to load push notifications settings
Suggested Resolution
Because the daily limit is nonnegotiable, no resolution is available.
Replace the certificate with a valid type.
Supply valid certificate.
Renew certificate.
Retry later.
Replace the certificate with a valid type.
Check your input for errors.
Reduce size of payload.
Confirm that settings are present on connected app.
Recipient field contains invalid device token
Invalid device token length
Provide valid device token.
Token was entered incorrectly or is corrupt. Re-enter token.
Error while sending notification. Confirm certificate is for the correct
Apple environment.
Confirm that correct certificate is being used (for example, sandbox versus production).
Apple Push Notification service is unavailable.
Unable to connect to Apple Push Notification service
Retry later.
Retry later.
Unable to connect to Salesforce proxy. Contact Salesforce support if issue persists.
Retry later.
Request blocked by Salesforce proxy. Contact Salesforce support if issue persists.
Retry later.
Apple Push Notification service returned unknown error
Badge must be a number
Contact Apple or retry later.
Re-enter the badge value as an integer.
Payload must be in a valid JSON format
Recipient is required
Format payload correctly.
You must enter a value for at least one of the following fields: Alert,
Badge, Sound, or Custom Payload
Enter a valid value for one of the fields.
Provide device token.
Google Cloud Messaging authentication error Consult the GCM documentation at developer.android.com
.
Possible causes:
•
Authorization header is missing or contains invalid syntax.
25
Reference Debug Log Events
Message Suggested Resolution
•
Invalid project number was sent as key.
•
Key is valid, but GCM service is disabled.
•
Request originated from a server that is not white-listed in the server key IP addresses.
Internal error in the Google Cloud Messaging server, or the server is temporarily unavailable
Retry later.
Registration ID in the Recipient field is formatted incorrectly
Payload exceeds maximum size
Verify that mobile app is providing valid registration ID, or manually enter valid registration ID.
Reduce size of payload.
Recipient field contains registration ID that is not valid for the connected application’s API server key
Recipient is required
Provide correct server key for the app.
Select recipient or provide registration ID.
Recipient field contains invalid registration ID
An unexpected error occurred. Please contact the SFDC support team.
Update recipient’s device registration ID.
GCM server returned an unexpected error. Please contact the SFDC support team.
Contact salesforce.com.
Contact salesforce.com.
Debug Log Events
The mobile push notification service logs events that are useful to understand when you are monitoring an Apex debug log.
Events
The following events are supported:
•
PUSH_NOTIFICATION_INVALID_APP
•
PUSH_NOTIFICATION_INVALID_CERTIFICATE
•
PUSH_NOTIFICATION_INVALID_NOTIFICATION
•
PUSH_NOTIFICATION_NO_DEVICES
•
PUSH_NOTIFICATION_NOT_ENABLED
•
PUSH_NOTIFICATION_SENT
For more information on these events, log levels and categories, and how to use the Developer Console or monitor a debug log, see the
Force.com Apex Code Developer's Guide
.
26
