Push

Overview

Push channel refers to both mobile (iOS, Android) and web push.

Each push message can be sent to all platforms at once or to a subset of them. By default only iOS and Android platforms are enabled, but this can be changed at any moment.

Your message can be previewed on iOS, Android, Web (iOS) and Web (Windows).

A push message is composed of:

• A title

• A message body

• (optional) A custom icon (Android & Web only)

• (optional) An image (iOS, Android and web notifications for Chrome)

• (optional) A deeplink redirection

• Advanced settings (see dedicated section)

Title and Message body

This is the most important part of your push notification, make sure your message is not too long and to write it accordingly to your targeted audience.

Emoji emoticons

You can add emoji emoticons to the title or the body of your iOS, Android, Windows or web push notifications.

If you want to insert an emoji in your message you can:

• Chrome 68+: Right-click any text field and select "Emoji" or "Emoji & Symbols".

• Windows: Simply press the Windows key + the period button to display Windows's emoji keyboard on Windows 10. In case you are using an older version of Windows, you can copy-paste an emoji from emojipedia: iOS / Android / Windows.

• Mac: Press CTRL + CMD + Space to display the emoji keyboard and pick an emoji.

• Custom emojis: Some device manufacturers use a set of custom emojis. See how they look here: Samsung / LG.

• Android 4.4: On Android versions before 4.4, emoji emoticons might not be displayed correctly.

Image & Custom Icon

You have two options to add an attachment:

• Browse media from your computer.

• Use a URL to your media : These URL can use personalization.

Image (optional)

Batch lets you send large-format notifications with a large image attachment on iOS, Android and Chrome (Web). We require a landscape image, PNG, JPG or WebP, with a minimum width and height of 200px (max. 10MB). For web push notifications, the image is displayed only on Chrome for Windows and Android, but it will not appear on other browsers like Chrome (macOS) or Firefox.

Custom Icon (optional)

On Android and Web, you can add a specific icon for the notifications sent by a push campaign. Batch requires a square image, PNG, JPG or WebP, with a minimum width of 192px. On Web, if a default icon is set in the settings, this custom icon overrides it. The custom Icon is not an iOS setting and does not impact iOS messages.

Deeplink URL (optional)

Deeplinks allow you to direct users to a specific place in your app. Batch Push campaigns can accept this link scheme to direct users to a particular area within your app upon opening the push notification (i.e. The news you mention in your notification, etc).

Please note that the Deeplink URL must be a link based on a URL scheme that you specify within your app and should begin with "app://", "http://", or "https://". URLs starting with "www." are not compliant.

If the same push orchestration is targeting several platforms, the deeplink URL can be specified by platform.

Advanced settings

Custom payload

An optional JSON string that can contain additional parameters that your application can handle when receiving push notifications if configured to do so. The root of the JSON must be an Object and cannot have the reserved key com.batch. You can use {BATCH:TITLE}, {BATCH:BODY} and {BATCH:DEEPLINK} variables. They will be replaced.

For example, you can use the custom payload to:

• Set a badge value for your app icon on iOS

• Customise your notification sound on iOS

• Add action buttons to your notification

• Send silent notifications

FCM/APNS Priority

Defines the priority of your message on iOS (APNS), Android (FCM) and Web. The default value is high.

On Android, you can use the high priority if you have a messaging/voip app and if you notice delivery issues due to native (Doze) or constructor related (Samsung Smart Manager, etc) energy saving features.

FCM Collapse key

Defines how notifications are managed when an offline device goes online. If enabled, the device will only show the most recent notification. If disabled, it will show all the notifications received when the device was offline.

You should disable the collapse key if all your notifications matter (E.g. messages, etc). You can use up to 3 different collapse keys if you want users to get only one notification of each kind when coming online (E.g. marketing message, alert, etc).

Expiration (TTL)

You can set an expiration delay or a Time to Live (TTL) in hours for your notification. The notification won't be displayed if the device doesn't receive the notification or doesn't come back online within this time.

By default, Batch sets a TTL of 14 days for all the notifications you send. If your user's device comes back online before being off for two weeks, it will display the last notification you sent to your user (iOS) or all the notifications sent over the previous two weeks (Android and web push).

In addition to setting an expiration delay for your push campaign, you can set a global expiration delay that will be applied to all your notifications. This can be done from the dashboard settings > Channels > Push settings.

Send a Test

• When specifying a Custom ID, the test will only be sent to installations on platforms enabled for the given push message. For example, if the push message is configured for Android and Web only, no test will be sent to an iOS installation.

• Similarly, if an installation ID is specified but corresponds to a platform not enabled for the push message, the test will not be sent.

• Other behaviors are similar to test messages across all channels. See more details here.

Safari APNS

For web push, Safari APNS is no longer supported. As of macOS Ventura (13.0), Safari implements the same Web Push Protocol other browsers do and does not require any additional configuration from your part.

Inbox

Inbox is an optional feature. If you are interested, please contact us.

The Inbox API allows you to fetch and process notifications that users have previously received, even if their device was offline. You can then do anything you want with the data, such as making a "notification center", where the user can catch up with previous notifications in a list.

The API gives you access to the entire notification, including its raw payload. It also lets you know if the notification has already been read. Once received/stored in the inbox, your push notifications will remain for a 3 months period.

Zoom on how Mobile Push works

Batch relies on Apple (APNS: Apple Push Notification Service) and Google (FCM: Firebase Cloud Messaging) push services to send push notifications on iOS and Android.

Understanding How Batch's SDK Works

Batch SDK must be integrated into your app. Your integration is attached to an app on Batch's side thanks to the "API key" you specified in your code when you completed the integration.

On the first app open, the SDK will start and Batch will register a new install. For every new install, Batch generates an anonymous "installation ID".

All the data collected from the app until users uninstall it will be attached to that "installation ID":

Collecting a Push Token

In order to send a push notification to a device, Batch needs to collect a "token". That token is anonymous and delivered by Apple and Google push services.

Here is how Batch collects a new token:

1. The app requests and receives a token from APNS/FCM. On iOS, this can happen when the app starts or when users accept push notifications, depending on the background refresh support.

2. Batch SDK collects that token and sends it to Batch servers.

The token is refreshed on every app start. This makes sure Batch always has a valid token to push your user.

Sending a Mobile Push Notification

In order to send a push notification to several devices, Batch servers provide the list of tokens that need to be pushed to the Apple / Google push notification service. Batch also provides a payload, containing all the data the app needs to display properly the notification (message, image, deeplink, etc).

Then, Apple/Google push notification service handles the delivery to the device. They provide feedback on errors or issues (e.g. invalid tokens, push certificate issues, etc). Batch cleans automatically your userbase based on this feedback. Batch SDK also sends feedback to Batch Servers when users click a notification.

Zoom on how Web Push works

Batch supports sending push notifications directly to web browsers, on desktop and mobile, even if your website is closed. Batch relies on two different technologies to deliver push notifications to the browser of your users, on desktop or mobile:

• The Push API W3C standard

• Service Workers

Any browsers implementing both technologies will be compatible with our Web SDK and will be able to receive push notifications: Google Chrome, Mozilla Firefox and any Chromium-based browsers (Microsoft Edge, Opera, Vivaldi, etc).

Understanding How Batch Works

Integrating Batch into your website is simple. You must:

1. Upload Batch's service worker to the root of your website

2. Add Batch's javascript tag to the code of your web pages

Your integration is attached to an app on Batch's side thanks to the "API key" specified in the javascript tag the dashboard automatically generates for you.

On the first session, the javascript tag will start and Batch will register a new install. For every new install, Batch generates an anonymous "installation ID".

All the data collected from the website until users clear site data will be attached to that "installation ID".

Collecting a Token

In order to send a push notification to a device, Batch needs to collect an endpoint. That endpoint is anonymous and delivered by the servers of each browser (e.g. Google, Mozilla, etc).

Here is how Batch collects an endpoint and generates a token:

1. The javascript tag triggers the native permission prompt.

2. If users turn on push notifications, the browser requests an endpoint to the push notification service.

3. The push notification service then generates a public endpoint and sends it to the browser.

4. Batch service worker collects that endpoint and the javascript tag sends it to Batch servers.

Batch servers store that endpoint for the installation and generate a "token". That token contains:

• An endpoint: the anonymous id generated by the push notification service for the browser (endpoint)

• The public key of the user's browser that allows it to decode the notification Batch will send (p256dh). The browser of every subscriber has a different public key.

• A secret key (auth).

Here is what a token looks like:

{
	"endpoint": "https://fcm.googleapis.com/fcm/send/f1JDSGNXoZM:APD91bFRRV4I-WCFDcEmSNGYii_7MyzG8gVgP0bYWGknKoNEmPkuDpUdkAKqb6O0Dr0xTO_2xDXqDnp4quk7iL_5PK3-J22RPrT-9Hsb4c_G4SBxNHqPX7Do5VHvNAm_SOk_foHGtA5u",
	"keys": {
		"p256dh": "BC2bogMsUCbFwomx4l1gXD984UYeNrz5qh3x_pHCt-UKfNFNaJp6xoQQo7MYqi_aglI780qcraGSut1CvRs67NI",
		"auth": "RFKT6wLk1X5lPwsMTOyKcA"
	}
}

Sending a Web Push notification

Here is how Batch sends push notifications to your users:

1. First, Batch encodes the content of the notification for every subscribed browser, based on the public key. The message sent from Batch can only be decoded by your user's browser.

2. Batch servers send the notification over HTTPS to the push notification service, signing the requests using a "private VAPID key" known exclusively by Batch.

3. Then the push notification service only reads the header to know which endpoint should be targeted. It cannot decode the message. The push notification service will also check if Batch is allowed to push that browser based on the private VAPID key and check if the endpoint is still valid (e.g. in case users cleared site data or uninstalled the browser).

4. Finally, the browser receives the push notification. Batch service worker decodes it and displays it.

Batch uses the feedback received from the push service to delete tokens that may be invalid in your profile base. Batch Service Worker will also send feedback to Batch servers when users click the notification. You can find both information in your campaign reports.