📍
New Version (2022-12-05)
This page describes the latest version of Taboola Web Push.
(For the older, deprecated version, go here.)

Introduction

Taboola Web Push enables you to re-engage visitors that opted in via a 1-click subscription.

Subscribed users receive push notifications, even when not on your website.

This guide explains how to integrate Taboola Web Push into your webpages.

Integration steps

Overview

🚧
Integration flow

Enable your domain-specific accounts for Web Push.

This step is performed by Taboola , at your request.

Integrate Web Push for the given domain.

Integrate Web Push for given pages in that domain.

(Optional) Integrate additional features.

Step 1: Enable accounts for Web Push

To enable your domain-specific accounts for Web Push, Taboola will share a Google Sheet with your team:

In the sheet provided, fill in a list of domains for which you require Web Push.
For each domain listed, your Taboola Account Manager will fill in the relevant fields, including a numeric publisher_id (aka Account ID).
Once Taboola has enabled a given account for Web Push, use the publisher_id provided in that row for the integration (see the sections below).

If you are unsure if Taboola enabled a given account, consult with your Taboola Account Manager.

📘
publisher_id guidelines

Each domain requires its own publisher_id.

Your Publisher ID (aka Account ID) is a unique, numeric ID - e.g. 123456.

Before using a given Publisher ID, confirm that Taboola has enabled that account for Web Push.

Step 2: Integrate Web Push for a given domain

Add a file called sw.js to the root of that domain.
This file must contain the following, single line of code:

importScripts("https://cdn.taboola.com/webpush/tsw.js");

📘
2 filenames

The name of the file is sw.js.

The path within the file points to tsw.js.

The above 2 filenames are intentionally different, and should not be changed.

Step 3: Integrate Web Push for pages in that domain

Now that you have integrated Web Push for the domain, you need to integrate it for the relevant pages under that domain.

In the <head> section of the page, add the following<script>:

Make sure to include an async attribute.

<script async src="https://cdn.taboola.com/webpush/publishers/{publisher_id}/taboola-push-sdk.js"></script>

🚧
Publisher ID

Replace the {publisher_id} placeholder with your domain-specific publisher_id, as provided by Taboola - e.g. 123456.

For example, if your Taboola Publisher ID is 123456, then the updated URL will be:
src="https://cdn.taboola.com/webpush/publishers/123456/taboola-push-sdk.js"

Note: make sure to remove the curly braces.

(Optional) Pass a traffic source for revenue attribution:

<script>
    // (Optional) Pass a traffic source for revenue attribution.
    // If you choose to include this line, you must place it *after* `taboola-push-sdk.js` (above).   
    // Naming convention: '<source name>_<campaign id>' e.g. 'taboola_1234'.
    Hood('utm', 'source', 'taboola_1234') // 'Hood' is declared in `taboola-push-sdk.js` (above).
</script>

📘
Traffic source

Providing a traffic source allows you to perform revenue attribution.

Use the following naming convention: '<source name>_<campaign id>' e.g. 'taboola_1234'.

🚧
If you choose to include the above line, you must place it after taboola-push-sdk.js (from step 1).

A sample page

For reference, a sample page is provided below:

  <head>
    <title>Test Page</title>
    <!-- Replace the `{publisher_id}` placeholder with your actual Publisher ID e.g. `123456`. -->
    <!-- E.g. if your Taboola Publisher ID is `123456`, then the updated URL will be:          -->
    <!-- src="https://cdn.taboola.com/webpush/publishers/123456/taboola-push-sdk.js"           -->
    <script async src="https://cdn.taboola.com/webpush/publishers/{publisher_id}/taboola-push-sdk.js"></script>
  </head>
  <body>
    <script>
      // (Optional) Pass a traffic source for revenue attribution.
      // If you choose to include this line, you must place it *after* `taboola-push-sdk.js` (above).
      // Naming convention: '<source name>_<campaign id>' e.g. 'taboola_1234'.
      Hood("utm", "source", "taboola_1234"); // 'Hood' is declared in `taboola-push-sdk.js` (above).
    </script>
    <!-- When the user clicks on the button, the event listener displays the push permission prompt: -->
    <button onclick="showTBLPushPrompt();">Show</button>
  </body>
</html>

🚧
publisher_id
Make sure to fill in your own publisher_id, as indicated by the code snippet comment.

📘
Testing the sample page

To test the sample page in Firefox, click on the button provided.

For all other web browsers, simply open the sample page.

For more information about Firefox-specifc beahavior, see the next section.

For additonal testing tips, see the end of this guide.

Supported browsers

📘
Supported browsers
Taboola Web Push works in any browser that supports the Web Push API - e.g.:
Desktop - Chrome, Firefox, Opera and Edge.*
Mobile - Chrome, Firefox, Opera, Samsung Internet Browser and UC Browser.*
For an up-to-date list of supported browsers, check online resources, such as caniuse.com.
* See the Firefox note below.

📘
Firefox (72 and higher)
Unlike most web browsers, Firefox will not allow you to display a push permission prompt, until the user has clicked on the page.
Until then, Firefox hides the push permission prompt, and displays a notification icon in the search bar. This icon usually goes unnoticed.
Recommended strategy:
To address the above restriction, consider adding an event listener to 1 or more elements on your page - e.g. to your cookie-consent banner.
When the user clicks on the consent banner (for any reason), a push permission prompt is triggered.
Example:

<div id=”cookies_banner” onclick="showTBLPushPrompt()"> </div>
showTBLPushPrompt()

This function is located in taboola-push-sdk.js (see above). When invoked, it displays the push permission prompt.

Tips & guidelines

📘
Start with a test page
Before rolling out to an entire site, consider starting with a test page:

Perform the integration on a test page under your Staging Domain.

Contact Taboola to verify the integration.

Perform the integration on a test page under your Production Domain.

Contact Taboola to verify the integration.

Once your integration has been verified by Taboola for a test page, repeat it for all relevant pages in that domain.

📘
Testing the same page multiple times
To test the same page multiple times on Google Chrome (without using BrowserStack, or similar):

Open the test page.

Click on the View site information icon, on the left side of the address bar:

Click on Reset permissions (under Notifications).

Reload the page.

The above instructions apply to Google Chrome.

When testing, make sure that you do not have an ad blocker enabled.

What's next?

👍
If you have not already done so, make sure to take a look at our additional features.