Web notifications

Web push notifications are delivered to a person’s browser if they have given permission (via a capture widget) to receive them.

When you create a push campaign, Ortto attempts to deliver the notification when a subscribed customer is online, within the notification lifespan or time to live (TTL) you set.

Here is an overview of how web push notifications work:

1. You add a service worker to your website.
2. You create a capture widget that requests push permission.
3. Once you have turned the capture widget ON, on your website a visitor/customer clicks "Allow" to provide their permission to receive notifications.
4. The customer’s permission (subscription) is recorded by Ortto’s server.
5. Permission data is sent to the service worker.
6. You create a web push campaign and the campaign event is sent to the service worker, which waits until the customer goes online (opens their browser). The customer only needs to open their browser to be considered online/active, they don’t need to visit the website the notification is sent from.
7. The service worker sees the customer is online and delivers the notification (provided the notification has not exceeded its TTL).

Prerequisites

Web notifications require the use of a JavaScript service worker (SW) file, created by Ortto, installed in your website (at the domain from which you wish to send notifications). The SW listens for notification events (sent from Ortto when you create a web push campaign) in the background, then delivers the notification to the recipient (provided all criteria has been met).

The SW imports a script written by Ortto, which processes the push notification events. You can download an SW file from Ortto, or use or modify an existing SW yourself.

Once the SW is added to your website, in Ortto navigate to Settings > Push notifications > Web notifications > Domains to add your domain and paste the corresponding URL in the Service worker URL field.

Download Ortto’s service worker

In your account Settings > Push notifications > Web notifications > Domains, click the Download our service-worker.js link to download a SW file.

We recommend adding the SW file to the root directory of your website to provide the greatest scope in handling notification events. If you need to host the SW in another directory, learn more about Hosting the service worker in a subdirectory.

Use your own service worker

Use your own SW by adding the following copyable code (hover over the top-right corner for a copy function) to your existing service worker. If the file is not in your website’s root directory, learn more about Hosting the service worker in a subdirectory.

javascript
 
importScripts('https://cdn3l.ink/push-service-worker-script.js');

Hosting the service worker in a subdirectory

If you need to host the service worker outside of your root directory, you need to configure your server to return Service-Worker-Allowed: / in the HTTP response header.

Usually the scope of the service worker is limited to the directory in which it is located. However, configuring Service-Worker-Allowed: / enables you to increase the scope of pages that the service worker can control (to include the full scope of the domain).

To install the service worker in a subdirectory:

1. Download Ortto’s service worker or use your own.
2. Add the service-worker.js file to the relevant subdirectory for your website.
3. Modify the HTTP response header handled by your server to return Service-Worker-Allowed: /

Learn more about configuring the header under Service worker script response.

Web notifications setup

In your Ortto account, configure web notification settings via Settings > Push notifications > Web notifications.

On the Web notifications page, at Status you can toggle the web notifications feature ON/OFF.

At Domains, ensure you have added a link to a service worker for your website. Learn more about adding a service worker under Prerequisites.

When your service worker has been confirmed as valid, you’ll see a confirmation that your domains are connected.

At Branding, the Site URL will be populated with the website URL set in your general settings (at Settings > General). Add a Logo (with a maximum size of 900 KB) to represent your organization.

At Permission prompts, you’ll see a list of the capture widgets you’ve configured to collect a person’s push notification permissions. Clicking on one of the widget names will take you to the widget view (where you can edit the widget).

When you’ve finished configuring web notifications, click Save at the bottom of the page.

Unidentified users

The default setting for unidentified users is to Store as a contact once identified. This means that if you create a capture widget with a Request push permission function but no means of capturing contact data (such as a form for email), by default an unidentified user (a person who does not exist as a contact in your CDP) who chooses to "Allow" or "Block" notifications will not be added as a contact to your CDP. However, we will store the permission response so that if the visitor becomes a CDP contact in future, we can associate the notification permission response with them.

Alternatively, you can select Store as contact immediately to collect unidentified user responses and store these users as contacts in your CDP. In this case, the contact will have limited data associated with them but can be included in an audience for future push campaigns. Capturing unidentified user as contacts may result in duplicate contacts.

Unidentified users are captured by their session ID (similar to how Ortto associates web session activities from website session tracking with an anonymous user).