Direct Integration Guide

This page details the steps needed to integrate web push notifications using the preferred method of using a service worker directly on your website. Using this method:

• You will need to create or update a service worker at the root of your website.

• Notifications sent to users will appear as coming directly from your domain name.

Requirements

• You must be able to configure the service worker at the root scope of your website.

• The service worker must be loaded from the same domain as your website — i.e., it cannot be loaded from a CDN or other third-party location.

• You must be able to include Fanplayr's web push notification script within the service worker.

If you are unable to meet the requirements of this method, see Popup Integration for an alternative method.

Limitations

Browser Support

Supported by modern web browsers and operating systems which implement the Push API.

Device	Browser	Support
Desktop	Chrome	v42+
Desktop	Edge	v17+ Note: Edge often hides notification requests behind a small "bell" icon (🕭) in the URL bar, making it harder for users to notice the request.
Desktop	Firefox	v44+
Desktop	Opera	v29+
Desktop	Safari	v16+ on macOS Ventura
Mobile	Chrome Android	v42+
Mobile	Firefox for Android	v48+
Mobile	Opera for Android	v29+
Mobile	Safari on iOS	Not supported

When using a Fanplayr widget to prompt users to subscribe you should make use of the "Can Subscribe to Web Push Notifications" segmentation filter to ensure that only users who currently do not have a subscription and have a supported web browser are targeted with the widget.

User Experience

1. Request permission to send notifications: Users who have not yet subscribed to notifications are shown a widget with a message prompting them to subscribe (e.g. "Stay up to date with our latest news and offers"). When the user clicks the primary call to action, the browser prompts them for permission to send push notifications.

2. User grants permission: If the user agrees to receive push notifications, they can click "Allow" or "Yes" on the browser prompt. At this point a subscription is created and stored in Fanplayr's database, which is then used to send notifications.

3. Fanplayr sends push notifications: Your business sends notifications to subscribed users through Fanplayr's messaging service. Users will be able to see these notifications on their device whenever their browser is open, even if they are not directly visiting your website.

Best Practices

It is highly recommended to use Fanplayr's Targeting features to display an intermediate widget which asks users if they are interested in subscribing to notifications before actually requesting the browser permission. This is important for a number of reasons:

• If a user blocks the browser permission request to enable notifications you will not be able to request permission again unless the user explicitly resets the permission in their browser settings.

• Many web browsers are becoming increasingly restrictive and can prevent showing permission requests when they are generated programmatically without any user interaction — i.e., avoid showing the browser permission request immediately when a user arrives on the page, instead show them a call to action which when clicked, triggers the request.

Integration Guide

You must be able configure the service worker at the root scope of your website. This can be achieved in one of two ways:

• By hosting the service worker JavaScript file at the root of your website — e.g., if your domain is mybrand.com and your service worker file is located at https://mybrand.com/service-worker.js, then the service worker will be active at the root by default.

• Alternatively, by hosting the service worker JavaScript file at a subdirectory and ensuring that the response for the file from the server contains a special header Service-Worker-Allowed: /, allowing the browser to make it active at the root of the website.

Follow one of the instruction guides below that best matches your scenario:

If your website ALREADY has a service worker

Follow this section if your website already has a service worker. It will guide you on how to include Fanplayr's web push notification script in your existing service worker code.

It is assumed that your existing service worker meets the requirements outlined at the beginning of this document, namely that it is configured to run at the root scope of your website.

1. Include our script in your existing service worker

Add the following content to your service worker JavaScript file to import Fanplayr's script for handling web push notifications:

var fanplayrOptions = {
  version: 1,
  // When `true`, Fanplayr will add "install" and "activate" event handlers
  // to the Service Worker which will cause it to be installed and activated
  // immediately without waiting for any caches to load.
  // Set to `fa  lse` if your Service Worker implements either of these events.
  immediate: true
};
importScripts('https://static.fanplayr.com/client/sw.js?v=' + fanplayrOptions.version);

Note: Consider carefully if the immediate option should be enabled based on your website's needs and the existing logic in your service worker.

2. Include HTML snippet

Include the following HTML on all pages of your website. This instructs Fanplayr's Targetign JavaScript library that your service worker is configured to use this feature.

<script>
window.fanplayrServiceWorker = true;
</script>

If your website DOES NOT have a service worker

Follow this section if your website does not already use a service worker. It will guide you on how to create one.

1. Create and upload service worker file

Create a new JavaScript file at the root of your web server named service-worker.js, with the contents shown below.:

importScripts('https://static.fanplayr.com/client/sw.js');

Ensure that this file is served with the correct content type of Content-Type: text/javascript by your web server.

Example 1

Your domain name is mybrand.com and you can upload the service worker file at the root of your website so that it is accessible at https://mybrand.com/service-worker.js.

Example 2

Your domain name is mybrand.com, but you cannot upload the service worker file at the root of your website (perhaps because you are using a hosted e-commerce website that does not allow uploading files at the root).

Instead, you upload the file to an "assets" subdirectory to be accessible at https://mybrand.com/assets/service-worker.js. You also configure your web server to include the Service-Worker-Allowed: / header in the file response so that browsers can use it as a service worker at the root of your website.

2. Include an HTML snippet

Do not perform this step unless explicitly requested.

Include the following HTML snippet on all pages of your website. This script instructs browsers to use the JavaScript file you created in the previous step as a service worker for your website.

<script
  src="https://static.fanplayr.com/client/sw-load.js"
  data-path="/service-worker.js"
></script>

Note: If you used an alternative filename for the service worker, ensure you update the data-path attribute in the script to match it

If your website DOES NOT have a service worker AND you are using Fanplayr's Salesforce Commerce Cloud plugin

Follow this section if you are using Fanplayr's SFCC plugin and do not already have a service worker on your website. If you already have a service worker, please follow the instructions in, If your website ALREADY has a service worker.

1. Enable the service worker

Navigate to the Fanplayr plugin configuration page and enable the service worker as shown in the screenshot below:

2. Make the service worker accessible from the root

1. Within SFCC, navigate to Business Manager / Merchant Tools / SEO / Aliases.

2. Edit the alias config to add the following route, adjusting as necessary to match your hostname.

{
  "my-store.demandware.net" : [
    {
      "if-site-path": "/serviceWorker.js",
      "pipeline": "Fanplayr-ServiceWorker"
    }
  ]
}

Migrating Existing Subscribers

If you have previously used another service for web push notifications on your website it may be possible to migrate some of the recent subscriptions created for your users provided that:

1. You can provide Fanplayr with an export of the details of active user subscriptions from the other service. At a minimum, it must include the following details for each user subscription:

   • Subscription endpoint (example below)

   • Subscription p256dh key (example below)

   • Subscription auth key (example below)

2. You can provide Fanplayr with the web push VAPID public and private key pair which were used to generate the subscriptions (example below)

# Public VAPID key eaxmple:
BCK1IQyb-o7-uqWBMgGM0UMZ_kRhvgr2evq3c0Yz2ZQsjH0mz1rxbq3j5i7mOlT7bljgq5lHBmPuvFmZ1jtNQV4

# Private VAPID key example:
XG5k9uNkfqbc9rW0_fsJmbSZfVYUKsEdtc7PeB2vU6s

# Subscription endpoint example (one per user):
https://fcm.googleapis.com/fcm/send/e9urHUUzfsc:APA91bEqiCiCLbxYiyoP0iuqxUwzzVOkMLic6CHgb7A0J4u75ME6EOFng_ts1b1-wJoIwaeSecH5ucvaxZ-9o08VaI4DwXpNPfmcvOPoXMZVLYJ9VXFCffakDDgVKU3xDAEO-wDq-Vrt

# Subscription p256dh key example (one per user):
BJWvtiOEpgYCMFYHM8_hHo8bxm294DyFzOgpOubsRc21MVfl4z6BklEGzYVvYu3JVO7AjrghxCAcA5BPDlacT9s

# Subscription auth key example (one per user):
OEBqFrdGvONmWXP-BDN4Qg

Migration Limitations

1. It is important to understand that Fanplayr may only be able to migrate a portion of the subscriptions from a previously used service due to some subscriptions becoming naturally inactive or having expired in the meantime.

2. It is also important to understand that the options for sending notifications to migrated subscriptions may be limited until the user returns to the website after Fanplayr Targeting has been integrated on your site.

   • This is because Fanplayr will not have any knowledge of the user from their migrated subscription alone and would require the user to return to the website with their subscription in order to internally associate Fanplayr's knowledge of the user with the subscription.

   • In the meantime, it should still be possible to send push notifications targeting all subscribers without filters.

Troubleshooting

Service worker is not detected

If you are using Fanplayr's sw-load.js script, you must ensure that this is included on your webpage before Fanplayr's tracking code.

Cannot upload service worker JavaScript file to root

If you are unable to upload the service worker JavaScript file to the root of your server then you may be able to proceed if you can upload it elsewhere with specific headers.

1. Ensure your server is delivering the service worker file with the following headers:

   1. Content-Type: text/javascript

   2. Service-Worker-Allowed: /

2. If you are manually registering the service worker (not using our sw-load.js script) then you will need to update your code to force the worker to be loaded at the root scope. For example:

<script>
if ('serviceWorker' in navigator) {
  // Note: Replace PATH_TO_SERVICE_WORKER with correct path on your server.
  navigator.serviceWorker.register('/PATH_TO_SERVICE_WORKER/serviceWorker.js', {
    // Force service worker to load in root scope.
    scope: '/'
  }).then(function() {
    window.fanplayrServiceWorker = true;
  });
}
</script>