Single Page Application
Overview
This page explains how to integrate Taboola recommendations into an SPA (Single Page Application), using the param values provided by Taboola.
Initial page vs subsequent pages
The integration steps are similar - but not identical - for both the initial page and subsequent pages.
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.
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 (to the <head>)
Add the Taboola loader script to the page <head>.
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>
Param | Instructions |
---|---|
| Fill in your Publisher ID (an alphabetic string), as provided by Taboola. For example, if your Publisher ID is
|
Publisher ID
Your Publisher ID is a unique, alphabetic String, provided by Taboola.
It might contain dashes - e.g.
"<<publisherID>>"
- but not spaces.
The Taboola loader
The Taboola loader is responsible for loading your publisher-specific configuration and fetching Taboola recommendations.
In order not to impact the load time of the page, this script is loaded asynchronously.
The
_taboola
command queueThe
_taboola
command queue is a JavaScript array, whose existence is ensured by the following code:
window._taboola = window._taboola || [];
Communication with the Taboola loader is performed by pushing commands into the
_taboola
command queue.This flow is "async safe" and allows pushing commands, regardless of whether the Taboola loader script has loaded yet.
Pass 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>'});
Param | Instructions | Notes |
---|---|---|
| Replace this with the relevant page type (as provided by Taboola) - e.g.
| Possible values: |
| To obtain an automated ID, leave this param as is: Else, insert your own, internal ID: | Specifies the ID of this page, for the given page type. |
| Insert the canonical URL of the new page. |
Use your own param values, as provided by Taboola.
Pass placement details
For each placement on the page:
- 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>>
'
- 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 IDUI Mode ID - The UI template (layout and properties) for this placement. 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 pageplacement
- The placement nameplacement name - A descriptive name for the placement - used for reporting., as provided by Taboola:E.g.
'<<placementName>>'
Must be unique per pagetarget_type
- The target type, as provided by Taboola:E.g.
'<<targetType>>'
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.
A subsequent page
Pass a new page notification (new pages only)
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.
// *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'});
This step is required for subsequent pages only - not the initial page.
Pass 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>'});
Param | Instructions | Notes |
---|---|---|
| Replace this with the relevant page type (as provided by Taboola) - e.g.
| Possible values: |
| To obtain an automated ID, leave this param as is: Else, insert your own, internal ID: | Specifies the ID of this page, for the given page type. |
| Insert the canonical URL of the new page. |
Use your own param values, as provided by Taboola.
Pass placement details
For each placement on the page:
- 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>>
'
- 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 IDUI Mode ID - The UI template (layout and properties) for this placement. 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 pageplacement
- The placement nameplacement name - A descriptive name for the placement - used for reporting., as provided by Taboola:E.g.
'<<placementName>>'
Must be unique per pagetarget_type
- The target type, as provided by Taboola:E.g.
'<<targetType>>'
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.
What's Next?
- In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR and CCPA respectively.
- If you have not already done so, configure ads.txt.
- Contact Taboola so that we can verify your implementation.
Updated 4 days ago