Introduction

This page explains how to integrate Taboola's Web Push with your website.

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

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

First steps

Obtain your SDK keys

In order to provide you with your SDK keys, a Google Sheet will be shared with your team.

In the sheet provided:

  1. List the domains for which you would like to enable Web Push.
  2. For each domain listed, your Taboola Account Manager will fill in an activation_key and public_key.

πŸ“˜

Each domain requires its own activation_key and public_key.

Domain-level integration

Add sw.js

Add a file called sw.js to the root directory of the domain, with a single line of code:

importScripts("https://cdn.ocmhood.com/sdk/osw.js");

Page-level integration

To enable Web Push on a given page, perform all the steps outlined below.

Add scripts to <head>

In the <head> section of the page:

  1. Add the following <script> tag, in order to import id.js:
<script src="https://cdn.taboola.com/webpush/id.js"></script>
  1. Just beneath the above tag, add the following <script> tag, and replace the param values:
<script>
    var actCode = ACTIVATION_KEY; // Fill in your domain-specific `activation_key`, as provided by Taboola.
    var apiKey = PUBLIC_KEY; // Fill in your domain-specific `public_key`, as provided by Taboola.
    var partnerName = PARTNER_NAME; // Fill in your organization name. Must be the same across *all domains* in your network.
</script>

πŸ“˜

Params

  • ACTIVATION_KEY - Your domain-specific activation_key, as provided by Taboola.
  • PUBLIC_KEY - Your domain-specific public_key, as provided by Taboola.
  • PARTNER_NAME - Your organization name. Must be the same across all domains in your network.

Add scripts to <body>

In the <body> section of the page:

  1. Add the following <script> tag, in order to import push.js:
<script src="https://cdn.taboola.com/webpush/push.js">
  1. (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* `push.js` (above).   
    // Naming convention: '<source name>_<campaign id>' e.g. 'taboola_1234'.
    Hood('utm', 'source', 'taboola_1234') // The 'Hood' object is declared in `push.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 push.js (above).

A sample test page

For reference, a sample test page is provided below.

🚧

Make sure to fill in your own values, as described in the comments.

<!DOCTYPE html>
<html>

<head>
    <title>Test Page</title>
    <script src="https://cdn.taboola.com/webpush/id.js"></script>
    <script>
        var actCode = ACTIVATION_KEY; // Fill in your domain-specific `activation_key`, as provided by Taboola.
        var apiKey = PUBLIC_KEY; // Fill in your domain-specific `public_key`, as provided by Taboola.
        var partnerName = PARTNER_NAME; // Fill in your organization name. Must be the same across *all domains* in your network.
    </script>
</head>

<body>
    <script src="https://cdn.taboola.com/webpush/push.js">
    </script>
    <script>
        // (Optional) Pass a traffic source for revenue attribution.
        // If you choose to include this line, you must place it *after* `push.js` (above).   
        // Naming convention: '<source name>_<campaign id>' e.g. 'taboola_1234'.
        Hood('utm', 'source', 'taboola_1234') // The 'Hood' object is declared in `push.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>

General tips and guidelines

πŸ“˜

Supported browsers

Taboola's 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:

<!-- When the user clicks on the consent banner, for *any* reason, the listener is invoked: -->
<div id=”cookies_banner” onclick="showTBLPushPrompt()"> </div>

showTBLPushPrompt()

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

πŸ“˜

Start with a test page

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

  1. Implement the SDK for single test page on a Staging Domain.
  2. Contact Taboola to verify the integration.
  3. Implement the SDK for single test page on your Production Domain.
  4. Contact Taboola to verify the integration.
  5. Once your integration has been verified by Taboola for a test page, repeat it for all relevant pages in that domain.