Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Here is how to integrate Batch scripts using a Tag Manager that does not support the most recent JavaScript versions.
Batch methods available in our documentation (for example to collect profile data) are written in the latest available version of JavaScript. However, some Tag Management Systems do not support ECMAScript 6.
In some cases, Batch JavaScript tags are not supported by default by Tag managers like Google Tag Manager (GTM) and Tag Commander due to the use of arrow functions.
In order to use the preconfigured JavaScript tags in these Tag Managers, you must remove all the arrow functions it contains. This can be done easily by using a tool like Babel.
You can use our to convert Batch tags into a JavaScript format compatible with Tag Management System tools.
Ensure that the plugin @babel/plugin-transform-arrow-functions is added in the bottom left corner of Babel.
Adapting your web push implementation to display Firefox and Safari's native permission prompt using user gestures.
Unlike the majority of browsers, Firefox and Safari do not allow publishers to trigger the push permission prompt without a prior user gesture (version 72 and above for Firefox). That user action should be a click on a webpage element (the click must not be a redirection, and the scroll doesn't work as a user gesture).
If no user gesture is defined, the native behaviour of these browsers would be hiding the permission prompt and either displaying an icon in the search bar for Firefox or nothing on Safari, thus making it hardly noticeable for website visitors:
Therefore, when integrating Batch web push, you should take into account these browsers' specificities. We suggest you do that by either:
That user gesture will trigger the display of the native permission prompt. This can be a click on your cookie consent request for example:
This can be done by calling the following Javascript function at the chosen event:
Ideally, you should set several user gestures in order to display the opt-in request to a majority of users during their browsing.
Depending on the browsers' requirements, this method might not always trigger the native notification prompt. You should always test this implementation, and optionally consider option B below.
You can also use . A click on the "Accept" button will be considered as a user gesture, thereby triggering the display of the native permission request:
This is a great solution to quickly launch a web push on your website.
To implement this, you would have to define a Custom UI object for Firefox and Safari only (the permission request remains native for other browsers):
However, we observe that the opt-in rate is not as good with this pre-permission prompt, compared to the native prompt only. That's why you should deploy it only on Firefox and Safari, and not on other browsers which don't have the same restrictions.
We also encourage you to implement one or several custom user gestures on Firefox and Safari for the next release, as detailed in the first section of this article.
function displayNativePermissionRequest(){
if (navigator.userAgent.indexOf("Firefox") !== -1 || (navigator.userAgent.indexOf("Safari") !== -1 && navigator.userAgent.indexOf("Chrome") === -1)) {
batchSDK(function(api){api.ui.show('native', true)});
}
}var batchSDKUIConfig = { native: {}
}
if(navigator.userAgent.indexOf("Firefox") !== -1 || navigator.userAgent.indexOf("Safari") !== -1 && navigator.userAgent.indexOf("Chrome") === -1) {
batchSDKUIConfig = {
alert: { icon: 'https://mydomain.com/icon.png',
backgroundColor: '#FFFFFF',
text: 'Subscribe to our notifications!',
}
}
}
batchSDK('setup', {
...
ui: batchSDKUIConfig
});
Here is all you need to know to review your web push integration in a preprod environment.
If you tried to test your web push integration and got a "401 unauthorized" error in the console of your browser, you most likely need to take the following steps :
Go to the Settings > Channels > Website section of your dashboard and add your test URLs in the "Allowed dev origins" field.
Add the following parameter to the Batch JavaScript tag on your website:
Don't forget to remove this line for the production environment.
dev: true
You can change the display duration of the web push notifications you receive from your computer's settings.
Batch keeps the default display time of the user's system to ensure the best user experience.
The default display duration may vary depending on the browser (Chrome, Firefox, etc.), the browser version, the OS, etc. It is generally set to 5 seconds by default. You can make it longer or shorter with your computer's settings.
Click Start > Settings to open the Settings window and then click Ease of Access.
Select Display in the left bar and define the display time in the field Show notifications for:
You will find a similar drop-down menu for earlier versions of Windows under:
PC Settings > Ease of Access > "Show notifications for".
PC Settings > Ease of Access > Other options > "Show notifications for".
Control Panel > All Control Panel Items > Ease of Access > Make it easier to focus on tasks > "Adjust time limits and flashing visuals".
The display time can not be changed from the Settings preferences on macOS, but only by using a Terminal command.
Open Terminal (use Finder and go to Applications > Utilities > Terminal). Type the following into Terminal:
Replace {duration} with the desired display duration in seconds, e.g. 15 seconds:
For macOS Sierra, El Capitan, and earlier, remove "-int" from the command.
To reset the default duration (generally 5 seconds), use this command:
Once the display duration is over, the notification does not disappear permanently. You can find it back in your Notification Center (accessible from the right side of your screen on macOS and Windows 10).
defaults write com.apple.notificationcenterui bannerTime -int {duration}defaults delete com.apple.notificationcenterui bannerTimeHere is a step-by-step guide on how to integrate Batch into your website managed with SalesForce Commerce Cloud.
Basic web push integration relies on two parts: adding a JavaScript tag to the pages of your website and uploading Batch's Service Worker to the root of your website.
If you are using Salesforce Commerce Cloud (SFCC) as a CRM for your website, you won't have access to the root of your website to upload Batch's Service Worker.
Here are the necessary steps to complete the web push integration with SFCC:
In case the steps described above do not apply to you, here is a link where you can find other options: .
Once the Service Worker is added, you can complete the integration by following this guide:
Depending on your environment, you may need to configure your website to authorize Batch.
If you use a Content Security Policy (CSP) that involves "worker-src"/"connect-src"/"script-src" rules (or if you plan to set up one), some configuration is required for web push to work on your website.
Batch requires a Service Worker to be installed to handle push notifications.
The minimal CSP directive is:
Why:
'self' matches your website's origin, as this is where the Service Worker is hosted
via.batch.com is where the SDK is hosted, which will be loaded from the snippet we ask you to host on your website when setting up the Service Worker
Here are the minimum directives that you need to add to your CSP to authorize the Batch JavaScript tag:
Why: connect-src needs two domains as the SDK will use the Fetch API to download a file hosted on via.batch.com and then communicate with our backend services, which are on ws.batch.com.
Why: script-src needs to be via.batch.com as this is where the SDK and its modules are hosted.
If you configure Batch using a script tag, you may also need to allow those:
We recommend that you use a nonce instead, as unsafe inline mostly defeats the CSP's purpose. You can find more info on the MDN CSP documentation.
As all websites are different, you will need to configure your CSP further in order to adapt the above recommendations to your environment. We recommend that you first use the “report only” mode for testing purposes and remove it once you're confident that your CSP works in all browsers.
connect-src https://via.batch.com https://ws.batch.comscript-src https://via.batch.com worker-src 'self' https://via.batch.comscript-src 'unsafe-inline'
Apple has introduced support for Web Push in PWAs starting with iOS 16.4.
This guide assumes that Batch Web SDK is already up and running on your website: you should be able to subscribe to and receive notifications using Safari on macOS 13 (or higher) before going forward.
To be able to subscribe to Web Push notifications on their phones and tablets, iOS users have to install your website as an app. But in order to be installable, your website must be a Progressive Web Application (PWA).
PWAs bridge the gap between websites and native apps by offering capabilities previously reserved for native apps to websites. PWAs are first and foremost Websites following the latest best practices and technologies but can be enhanced with deeper system integration for users who install them.
PWAs are websites with a couple of extra requirements:
They must be served over https
They must have a
They must have a Service Worker
Good news: you've already done this part when integrating our web SDK 🎉
First things first, let's create your manifest.
For this example, we will call our manifest manifest.json and host it on our website's root. You can name it however you want or host it on a CDN, but we will not cover this.
Open an editor, create a file named manifest.json, paste the following content and replace the default values:
Note that this is a minimal manifest. See or for more info.
Remove the comments, and upload this file to your website's root (/).
Then, add the following meta tag on your pages, in <head>:
Upload/deploy your website and you're done!
You will need an iPhone or iPad running iOS 16.4 or newer to test the integration.
Even though you've turned your website into a PWA, Batch Web SDK will not show the pre-subscription prompt that shows up on your mac's Safari: you need to install your PWA.
Asking for notification permission on iOS, just like on macOS Safari, can only be done after the user interacts with your website. Batch can provide this with our feature.
Here is how to do it:
Open your website in Safari
Press the "Share" button at the bottom of your screen
Select "Add to Home Screen" You should then see your PWA's Title and Icon as defined in the manifest. If the icon is a preview of the website, Safari failed to recognize your Manifest.
Exit Safari: your PWA will be available on your lockscreen.
Now that it is installed, open it. If configured, Batch Web SDK will show a UI component prompting you to subscribe to notifications. Subscribe, and you should see the iOS permission request. You're done!
As the Safari Inspector is not available for installed PWAs, you will need to add a way (hidden button, secret tap sequence, etc...) to call the batchSDK('ui.showPublicIdentifiers') JavaScript method so that Batch displays the Installation ID needed to test your Web Push notification.
If you are having trouble figuring out why your manifest doesn't work, use Chrome's inspector (using the Application tab) to find out why. Safari can also print useful errors in its .
Here is everything you need to know on how to migrate your tokens from your current web push provider to Batch.
If you are already using web push notifications with another provider, then you probably want to migrate your existing userbase to Batch. The methodology described below will allow you to transfer to Batch all users who are already subscribed to notifications on your website.
The user's tokens will be migrated to Batch as they return to your website, and they will not be requested to provide push permission again.
Follow this guide to ensure that the JavaScript tag has been added to the pages of your website.
Once you have followed the steps to , you may need to check if the JavaScript tag that launches Batch is correctly added to your website.
Here is how to do it using Firefox and Chromium-based web browsers:
Right-click anywhere on your website, then click "Inspect".
You can integrate a custom toggle switch into your website to manage web push notifications easily (opt-in and opt-out).
By default, users can manage their push preferences from their browser settings on desktop and mobile ().
Instead of making your users dive into their browser settings, you can give them the option to disable/enable push notifications directly from your website using a toggle switch.
The following steps will help you set up this button on your website.
{ ...
"your-host" : \[
...,
{
"if-site-path": "/batchsdk-worker-loader.js",
"pipeline": "ServiceWorker-GetFile"
}
\]
}Remove the code used to initialize the SDK of the previous web push provider, and any code calling its functions.
Keep the existing service worker file, on its current scope, without modifying it.
By keeping the file untouched, the previous service worker will not be updated until the user returns to the website and will still be able to display a push notification. See the Accelerate the migration part below for more details.
If you are using a shared service worker (e.g., PWAs) and want to keep sending push notifications from your previous tool, you can upload Batch's service worker file separately.
Follow the Batch web integration steps.
The Batch service worker must be added in a separate scope from the other solution's service worker: Registering a custom Service Worker.
The previous configuration remains cached until users return to the website. This means that you can send push campaigns from your old tool in addition to the push notifications sent with Batch. This will allow you to continue to address your entire opt-in base while accelerating the migration process:
New users and those who have already returned to the website will be targeted by Batch notifications, as their token is attached to the new Batch web push project, and the push will be interpreted and displayed by the Batch service worker.
Old opt-in users who have not yet returned to the website will be targeted by the notifications of your previous tool, because their token is still attached to the old web push project, and the notification will be displayed by the service worker of the previous provider.
You can also use any other channel to bring traffic to your website (e.g., Email).
Make sure not to send the same push notifications from Batch and your old push solution as a part of your userbase could be reached via both and might receive duplicated content.
The web push format does not allow to import the tokens at once as for mobile apps.
Each service worker expects information in non-standard fields (e.g., title, description, etc.) to display the message contained in the received notification. These fields are different for each provider, and there can only be one service worker on a website.
As long as the user has not returned to the site, the SDK and service worker of the previous provider are still running. If this user is targeted by a notification sent from Batch, the notification would be badly displayed or not displayed at all, because it will be interpreted by the service worker of the previous provider.
Once the integration is complete, you can verify that the migration is successful and that the old tokens are attached to the new Batch web push project.
Here are two simple steps to follow:
Subscribe to push notifications on your website before Batch goes live, with the old configuration
Go back to the website after the release of Batch, then send yourself a test push from the dashboard. Here is how to do it: How can I send a test notification to my web browser?
If the push is well received, it means that the push token has been attached to the new Batch web push project.
Congrats, you can now use Batch to its full potential 🚀
This manifest needs to be referenced in your website using an HTML <head> tag.
In the section that opens, press Ctrl + F (on Windows) or ⌘+F (on Mac) to open the search bar.
Look for text contained in the tag (for example "batchsdk(").
Press ⏎ Enter on your keyboard until you see the code of the tag:
Right-click anywhere on your website then click "Inspect Element".
In the section that opens, press Ctrl + F (on Windows) or ⌘ + F (on Mac) to open the search bar.
Look for text contained in the tag, for example, "batchsdk( ".
Press ⏎ Enter on your keyboard until you see the code of the tag:
Check the following options:
Ensure that you deployed the JavaScript tag on the correct website (e.g., staging instead of production). If you used Google Tag Manager, make sure you followed these steps: How to integrate Batch's snippet using Google Tag Manager?
You may also have added the JavaScript tag as an external script. For example:
In this case, ensure that this reference is available in the source code of the page (as described above) and that the referenced script corresponds to the tag.
The snippet should be triggered on all your website's pages (Select "All pages" as a firing trigger) unless there are subdomains you want to exclude, in which case you should add exceptions.
To add an exception to your tag triggers, you should create a new trigger that will be used as an exclusion trigger.
If you want to exclude all subdomains, use the following condition:
If you want to exclude a list of subdomains, use the following conditions:
Once your exclusion trigger has been created, add it to your tag's trigger settings as an exception:
That’s it, when you are all set, release the new tag in staging or in production. Make sure you test your integration correctly by following the steps described here: Testing my web push integration.
First, you need to obtain the users' opt-in status to update the button's status. You can use this method :
Keep in mind that notifications management may happen at two different levels:
At the SDK level
In users' browser settings: on this level, you cannot control notifications with a toggle switch button as described above.
You will find more details in the Batch Web API Reference.
Follow this guide to make sure Batch is integrated correctly into your website before going live.
Once you have completed the steps described in the , several elements should be checked to make sure you will be able to use Batch to its full potential.
There are two scenarios if you integrate web push:
In this case, follow these steps:
Allow push notifications and try sending a test notification to your browser (repeat the same step on Chrome, Firefox, and Safari).
Here is how to do it:
Ensure icons match the required size and format ().
In particular, make sure that the small icon has a transparent background and is properly displayed (i.e., not a gray circle) on Android.
Here is .
If you choose to use Batch pre-permission prompts to , ensure it is displayed when you land on the website and fits the custom UI that you want to display.
If you choose to, make sure it is sent to Batch when you log in to the website using the Profile view on the dashboard (Profiles > Search Profiles) and your .
The Custom User ID must be reset when the user logs out of the website. (i.e., the field must be empty)
If you choose to detected by the SDK with the language displayed on the website for this user, you can check that it is updated correctly using the Profile view on the dashboard (Profiles > Search Profiles) and your .
Use the Refresh button to see the latest data.
In this case, check the following:
Make sure you between each test.
If you deployed Batch on a staging version of your website, make sure your JavaScript tag contains the "dev: true" parameter and you added your staging domain name to the list of "Allowed dev origins", from the dashboard Settings > Channels > Website.
If you deployed Batch in production, make sure you removed the "dev: true" parameter from the Javascript tag.
Make sure that the Service Worker is well integrated at the root of your website: type the name of the service worker after the domain name (e.g., ). You may have chosen to add the service worker in a subfolder, in which case the path must be indicated in the JavaScript tag (see ). In case you integrated it with an existing service worker, ensure you followed all steps of this .
Ensure that your test website is secure. For any service worker to work, it is essential to use HTTPS and to have an accepted/valid certificate.
{
"short_name": "Batch store", // Name of your app if the "name" doesn't fit
"name": "Batch Store", // Name of your app on the homescreen
"icons": [
{
"src": "https://cdn.glitch.global/20fbe514-82ff-481c-affd-936b061873bb/pwa_logo.png?v=1676644156289", // Icon URL. Can be hosted on a CDN.
"type": "image/png", // Icon mimetype
"sizes": "235x235" // Your icon size
}
],
"id": "/",
"start_url": "/", // URL that will be loaded by the system when launching your PWA. You can set tracking parameters here. Example: "/?utm_source=pwa".
"background_color": "#FFFFFF", // The background that should be displayed behind your logo while the PWA is loading
"display": "standalone", // This tells iOS to display your app without the Safari interface. Without it, Web Push notifications are NOT enabled by iOS!
"scope": "/",
"theme_color": "#FFFFFF", // Your website's accent color
"description": "Batch's Demo Store PWA" // Website description.
}<html>
<head>
<link rel="manifest" href="manifest.json">
</head>
</html><script async="" src="//static/js/pushweb.min.js"></script>batchSDK(function(api) {api.unsubscribe();});batchSDK(function(api) {api.subscribe();});batchSDK(function (api) {api.isSubscribed()});
<input type="checkbox" id="toggle" onclick="validate();" /><script type="text/javascript">
function validate() {
if (document.getElementById("toggle").checked) {
batchSDK(function(api) {api.subscribe();});
} else {
batchSDK(function(api) {api.unsubscribe();});
}
}
</script>
