Guides
Guides

Web Push (Manual integration)

📍

You are viewing the manual integration doc. For the WordPress Plugin doc, see here.

Overview

Taboola Web Push allows you to re-engage and monetize visitors, even when not on your website.

To receive notifications, users can opt in via a 1-click subscription flow.

📘

End-to-end flow

Getting started

  1. Reach out to your Taboola Account Manager for your Web Push accounts.

Integration

  1. Integrate Web Push for a given domain.
  2. Integrate Web Push for given pages in that domain.
  3. (Optional) Implement additional features.

Getting started

Web push accounts

To get started, reach out to your Taboola Account Manager for your Web Push accounts.

🚧

Which accounts?

Your Taboola Account Manager will provide new accounts (one account per domain).

You cannot re-use your existing Taboola accounts.

Daily reports

A daily report of your Web Push activity will be provided to the relevant email address(es).

Integration

🚧

Already have a service worker?

Make sure to look at the guidelines provided below.

Step 1: Integrate Web Push for a given domain

  1. Create a file called sw.js that contains a single line of code:
importScripts("https://cdn.taboola.com/webpush/tsw.js");
  1. Upload sw.js to the root of the domain.
  2. Verify that sw.js was uploaded successfully:
    1. Using a browser, enter your domain path, followed by "sw.js".

      E.g. https://mydomain.com/sw.js

    2. Check that the contents of sw.js display in your browser. You should see a single line of code:
      importScripts("https://cdn.taboola.com/webpush/tsw.js");

Already have a service worker?

If your website already has a service worker, follow these guidelines:

  1. Place your service worker code in a file called sw.js, located on the root of your domain.

  2. Add the following line at the end of sw.js:

    // Your service worker code here...

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

Exceptions to the default service worker implementation

Use the default sw.js file at the root of your domain whenever possible. The following options are exceptions and are not recommended for standard integrations:

  1. Different file name or path: If you cannot use /sw.js, contact your Taboola account manager and provide the expected service worker path relative to the root of your domain.
  2. Dynamic path: If your service worker path changes dynamically, contact your Taboola account manager. They can provide access to an external API that lets you update the path programmatically.

Step 2: 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 relevantpages under that domain.

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

    Make sure to include an asyncattribute.

<!-- Replace the {publisher_id} placeholder with your actual Publisher ID e.g. 123456: -->
<script async src="https://cdn.taboola.com/webpush/publishers/{publisher_id}/taboola-push-sdk.js"></script>
🚧

Publisher ID

Replace {publisher_id} with your domain-specific publisher_id.

For example, if your publisher_id is 123456:

src="https://cdn.taboola.com/webpush/publishers/123456/taboola-push-sdk.js"

The publisher_id is a unique, numeric identifier, provided by Taboola.

When editing the above URL, make sure to remove the curly braces.

Step 3: Update ads.txt for sponsored push notifications

If you are using sponsored push notifications, update ads.txt appropriately.

See: Update ads.txt for sponsored push notifications

Step 4: Additional features

You can optionally implement additional features - e.g. a backdrop effect.

See: additional features.

A sample page

For reference, a sample page is provided:

<!-- The push permission prompt will display on page load. -->
<html>

<head>
  <title>Test Page</title>
  <!-- Replace the {publisher_id} placeholder with your actual Publisher ID e.g. 123456: -->
  <!-- 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>
  <h1>Test Page</h1>
</body>
  
</html>
🚧

publisher_id

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

Browser guidelines

📘

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.

Testing guidelines & tips

📘

Recommended rollout plan

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

  1. Perform the integration on a test page under the desired domain.
  2. Contact Taboola to verify the integration.
  3. Once your integration has been verified by Taboola for a test page, repeat it for all relevant pages in that domain.
📘

Tip: How to test a page multiple times

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

  1. Open the test page.
  2. Click on the View site information icon, on the left side of the address bar:
  3. Click on Reset permissions (under Notifications).
  4. Reload the page.
  • The above instructions apply to Google Chrome. (For other browsers, refer to your browser documentation.)
  • When testing, make sure that you do not have an ad blocker enabled.

What's next?

👍

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

Updated 5 days ago