SPA (Single Page Application)

Overview

Introduction

This page explains how to integrate Taboola recommendations into an SPA (Single Page Application), using the param values provided by Taboola.

🚧

Prefilled scripts

If you received prefilled scripts from Taboola, you can copy and paste them 'as is', instead of editing param values.

🚧

New integration?

If this is a new integration, please provide Taboola with a timeframe for launch, so we can plan post-launch QA.

Terminology & flow

📘

Taboola loader

Loads your publisher-specific configurations and fetches your Taboola recommendations.

In order not to impact page load time, loader.js is loaded asynchronously.

📘

The _taboola command queue

A global array whose existence is ensured by the following code:

window._taboola = window._taboola || [];

You communicate with the Taboola loader by 'pushing' commands to this queue.

This allows you to pass commands 'safely', regardless of whether the Taboola loader has loaded yet.

📘

General flow

The initial page

1. Add the Taboola loader
2. Pass the page details to the _taboola command queue.
3. For each placement on the page:
   1. Create a <div> container with a unique ID.
   2. Pass the placement details to the _taboola command queue.
4. Pass a flush command.

Each new page

1. Pass a newPageLoad notification.*
2. Pass the page details to the _taboola command queue.
3. For each placement on the page:
   1. Create a <div> container with a unique ID.
   2. Pass the placement details to the _taboola command queue.
4. Pass a flush command.

---

(* The newPageLoad notification is the key difference between SPA and Infinite Scroll integrations.)

📘

Initial page vs subsequent pages

The integration steps are similar - but not identical - for both the initial page and subsequent pages.

Supported browsers

🚧

Taboola's SPA integration is supported for any browser that is fully compatible with ES5 (ECMAScript 5) or higher. This includes all modern web browsers.

Older browsers (such as IE 11) may encounter problems with video ads.

The initial page

Add the Taboola loader

Add the Taboola loader script to the page .

🚧

The Taboola loader should run once only, when the initial page is loaded.

Fill in your own Publisher ID, as provided by Taboola (or use the prefilled script that was sent to you).

<script>

    // *Global* command queue for the page
    window._taboola = window._taboola || [];

    !function (e, f, u, i) {
        if (!document.getElementById(i)) {
            e.async = 1;
            e.src = u;
            e.id = i;
            f.parentNode.insertBefore(e, f);
        }
    // Fill in your Publisher ID (an alphabetic string), as provided by Taboola:
    }(document.createElement('script'), document.getElementsByTagName('script')[0], '//cdn.taboola.com/libtrc/<publisher-id>/loader.js', 'tb_loader_script');

    if (window.performance && typeof window.performance.mark == 'function') {
        window.performance.mark('tbl_ic');
    }

</script>

📘

Publisher ID

Your Publisher ID is a unique, alphabetic String, provided by Taboola.

It might contain dashes - e.g. "<<publisherID>>" - but not spaces.

Pass the page details

Pass the page details to the Taboola command queue:

// *Global* command queue for the page
window._taboola = window._taboola || [];
  
// Pass the *page* details to the command queue:
_taboola.push({<page-type>:'auto', url:'<url>'});

🚧

Guidelines

1. Use your own param values, as provided by Taboola.
2. Pass the fully-qualified, canonical URL of the initial page.
3. If you copy the above code snippet to another page, make sure that page_typecorrectly reflects the new page type.

Pass the placement details

For each placement on the page:

1. Insert a <div> container, in the location that the placement should display:

<div id="<container>"></div>

📘

Assign the <div> a unique ID for that page - e.g. "<<containerId>>".

---

Tip: Consider using an ID that is similar to the placement name.

For example, if the placement is: '<<placementName>>'
Then you might use an ID of: '<<containerId>>'

2. Pass the placement details to the Taboola command queue:

// *Global* command queue for the page
window._taboola = window._taboola || [];

// For each placement, pass *your* param values, as provided by Taboola:
_taboola.push({mode: '<mode>', container: '<container>', placement: '<placement>', target_type: '<target_type>'});

📘

Params

The values shown below are sample values only. Make sure to fill in your own values, as provided by Taboola.

---

• mode - The UI Mode ID for this placement, as provided by Taboola:

  E.g. '<<mode>>'

• container - The ID of the <div> container for this placement's content:

  E.g. '<<containerId>>'
  Must be unique per page

• placement - The placement name, as provided by Taboola:

  E.g. '<<placementName>>'
  Must be unique per page

• target_type - The target type, as provided by Taboola:

  E.g. '<<targetType>>'

🚧

Guidelines

1. Use your own param values, as provided by Taboola.
2. Do not update target_type, unless your Taboola Account Manager instructs you to do so.

📘

Custom Segments

To target a custom segment - or simply track its performance - you can optionally pass a cseg param.

For more information, see Custom Segments - or reach out to your Taboola Account Manager.

Flush the queue

Immediately after passing details for the last placement, pass the flush command:

// *Global* command queue for the page
window._taboola = window._taboola || [];

// Pass the `flush` command:
_taboola.push({flush: true});

🚧

• The flush command instructs Taboola to fetch any placements in the command queue (and not wait any further).
• Pass the flush command once only - after passing all placements for that page.
• If you have unique requirements, reach out to Taboola to discuss alternative flows.

👍

Need a hand?

Feel free to reach out on our Community Discussion page!

A subsequent page

Pass a new page notification

When a subsequent page is loaded dynamically, pass a newPageLoad notification to the Taboola command queue. This notifies Taboola to reset the page state, allowing you to submit new page and placement details.

🚧

This step is required for subsequent pages only - not the initial page.

// *Global* command queue for the page
window._taboola = window._taboola || [];

// Submit a `newPageLoad` notification to the command queue:
// ONLY for subsequent pages (not the initial page)
_taboola.push({notify:'newPageLoad'});

🚧

Handling the Back button

When handling the Back button, note the following best practice:

1. Do not use the Back button to trigger a newPageLoad notification.

   Instead, submit it when the page renders, together with the Taboola placement scripts.

2. If the above approach is not feasible, then make sure to trigger the newPageLoad notification together with the Taboola placement scripts.

   SubmittingnewPageLoad on its own will cause Taboola Explore More to fail.

---

For more information, reach out to your Taboola Account Manager.

Pass the page details

Pass the page details to the Taboola command queue:

// *Global* command queue for the page
window._taboola = window._taboola || [];
  
// Pass the *page* details to the command queue:
_taboola.push({<page-type>:'auto', url:'<url>'});

🚧

Guidelines

1. Use your own param values, as provided by Taboola.
2. Pass the fully-qualified, canonical URL of the initial page.
3. If you copy the above code snippet to another page, make sure that page_typecorrectly reflects the new page type.

Pass the placement details

For each placement on the page:

1. Insert a <div> container, in the location that the placement should display:

<div id="<container>"></div>

📘

Assign the <div> a unique ID for that page - e.g. "<<containerId>>".

---

Tip: Consider using an ID that is similar to the placement name.

For example, if the placement is: '<<placementName>>'
Then you might use an ID of: '<<containerId>>'

2. Pass the placement details to the Taboola command queue:

// *Global* command queue for the page
window._taboola = window._taboola || [];

// For each placement, pass *your* param values, as provided by Taboola:
_taboola.push({mode: '<mode>', container: '<container>', placement: '<placement>', target_type: '<target_type>'});

📘

Params

The values shown below are sample values only. Make sure to fill in your own values, as provided by Taboola.

---

• mode - The UI Mode ID for this placement, as provided by Taboola:

  E.g. '<<mode>>'

• container - The ID of the <div> container for this placement's content:

  E.g. '<<containerId>>'
  Must be unique per page

• placement - The placement name, as provided by Taboola:

  E.g. '<<placementName>>'
  Must be unique per page

• target_type - The target type, as provided by Taboola:

  E.g. '<<targetType>>'

🚧

Guidelines

1. Use your own param values, as provided by Taboola.
2. Do not update target_type, unless your Taboola Account Manager instructs you to do so.

📘

Custom Segments

To target a custom segment - or simply track its performance - you can optionally pass a cseg param.

For more information, see Custom Segments - or reach out to your Taboola Account Manager.

Flush the queue

Immediately after passing details for the last placement, pass the flush command:

// *Global* command queue for the page
window._taboola = window._taboola || [];

// Pass the `flush` command:
_taboola.push({flush: true});

🚧

• The flush command instructs Taboola to fetch any placements in the command queue (and not wait any further).
• Pass the flush command once only - after passing all placements for that page.
• If you have unique requirements, reach out to Taboola to discuss alternative flows.

👍

Need a hand?

Feel free to reach out on our Community Discussion page!

What's Next?

1. In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR and CCPA respectively.
2. If you have not already done so, configure ads.txt.
3. Contact Taboola so that we can verify your implementation.