FrontPage / HP4U integration
Introduction
Taboola's FrontPage for Newsroom
provides real-time engagement data, and allows you to A/B test headlines and images on your homepage.
Taboola's HP4U
(Home Page For You
) generates personalized recommendations on your homepage, boosting user engagement.
Both solutions rely on a detailed mapping of your homepage, and share a common integration. These steps are outlined below.
A/B Testing
To ensure a smooth HP4U integration, Taboola implements a gradual rollout, via A/B Testing.
In a typical rollout plan, the following test groups are used: 1%
, 10%
, and 90%
.
(A control group of 10%
is maintained post-rollout.)
A/B testing is carried out by Taboola - without any action on your side.
Using a special event exposed by HP4U, you can track if the current user is in the control or test group, and report this to your analytics tool.
For more information, contact your Taboola Newsroom Engagement Manager.
Integration overview
The following summary provides a bird's-eye view of the integration:
Homepage
- Add the relevant
<script>
tags to your homepage.- Add
data-tb
attributes to all relevant HTML tags on your homepage.- Notify Taboola so that they can complete your server-side configuration.
Article pages
- Add the relevant
<script>
tags to your article pages.Verification
- Verify your implementation.
Add scripts to the homepage
loader.js
Already using Taboola units?
If you implemented standard Taboola units on your homepage,
loader.js
should already be present.In that case, you can skip to the next section: newsroom.js
- Add the Taboola loader script to your homepage, inside the
<head>
section (see below). - Replace
<publisher-id>
with your own Publisher ID (or Network ID), as provided by Taboola - or use the prefilled script provided by your Taboola Newsroom Engagement Manager.
<script>
window._taboola = window._taboola || [];
_taboola.push({homepage: 'auto'});
!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 _or_ Network 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>
Placeholder text | Instructions |
---|---|
<publisher-id> | Fill in an alphabetic Publisher ID or Network ID, as provided by Taboola. If your Publisher ID is '<<publisherID>>' , then the URL should read:'//cdn.taboola.com/libtrc/<<publisherID>>/loader.js' -- Note: If you are using network-level integration at Taboola, fill in your Network ID. For more detail, reach out to your Taboola Newsroom Engagement Manager. |
newsroom.js
Already using FrontPage?
If you are currently using FrontPage for Newsroom,
newsroom.js
should already be present.In that case, you can skip to the next section: Tag the homepage
- Immediately below the above script, add the Taboola newsroom script (see below).
- Replace
<publisher-id>
with your own Publisher ID, as provided by Taboola - or use the prefilled script provided by your Taboola Newsroom Engagement Manager.
<script>
window._newsroom = window._newsroom || [];
window._newsroom.push({pageTemplate: 'home'});
window._newsroom.push({pageDashboard: 'home'});
window._newsroom.push('auditClicks');
window._newsroom.push('trackPage');
!function (e, f, u) {
e.async = 1;
e.src = u;
f.parentNode.insertBefore(e, f);
// Fill in your Publisher ID (an alphabetic string, as provided by Taboola):
}(document.createElement('script'),
document.getElementsByTagName('script')[0], '//c2.taboola.com/nr/<publisher-id>/newsroom.js');
</script>
Placeholder text | Instructions |
---|---|
<publisher-id> | Fill in your alphabetic Publisher ID, as provided by Taboola. If your Publisher ID is '<<publisherID>>' , then the URL should read:'//c2.taboola.com/nr/<<publisherID>>/newsroom.js' -- Note: newsroom.js does not support network-level integration - you must provide a specific account.For more detail, reach out to your Taboola Newsroom Engagement Manager. |
Guidelines
- Load the scripts as soon as possible - without any lazy loading.
- Do not split a given script into multiple parts. This can cause a race condition and may result in a loss of data.
Tag the homepage
Regions, items & properties
First steps
Prior to the implementation, your editorial team will work with Taboola to document all regions and items on your homepage.
Make sure you received the above scoping sheet from your Taboola Newsroom Engagement Manager. Using that sheet as a guide, follow the steps below to tag all regions and items on your homepage.
You must tag all regions and items - including those that will not be personalized by Taboola.
This allows Taboola to track performance and prevent duplicate items.
Terminology
Refer to the sample screenshot, below.
- Region - a group of related items on the homepage - e.g. a group of items that belong to
Sports
.- In the screenshot below, the region is marked in orange (the outer recatangle).
- Item - a content slot on the homepage. Each item contains properties that must also be tagged.
- In the screenshot below, the region contains 4 items, each marked in blue.
- Properties - The properties of a given item - e.g. category, thumbnail, links, title, date etc.
- In the screenshot below, each visible property is marked in a different color:
- Title - in green
- Date - in yellow
- Thumbnail - in pink (first item only)
- Category - in light blue (first item only)
- Premium icon - in brown (first 2 items only)
- In the screenshot below, each visible property is marked in a different color:
A sample screenshot
Sample walkthrough
For a guided walkthrough of how to tag the region depicted above, see the sample walkthrough.
Tagging the homepage
Tag all regions
For each region on the homepage:
- Add a
data-tb-region
attribute to the<div>
or HTML block element that wraps that region. - Set the attribute value to the region name.
<div class="section-sports" data-tb-region="sports">
Refer to the scoping sheet provided by your Taboola Newsroom Engagement Manager.
Region guidelines
- All regions must be tagged - including regions that will not be personalized by Taboola.
- Do not nest a region within another region.
- Make sure that every item is enclosed within a region.
- Assign a region name to each
data-tb-region
attribute:
- The name must be unique.
- Choose a descriptive name - e.g.
sport
. Avoid using names likeregion-1
,region-2
, etc.
Tag all items
For each item (content slot) in a given region:
- Add a
data-tb-region-item
attribute to the HTML element for that item. - Set the attribute value to an empty string - or leave out the value altogether.
<article class="card" data-tb-region-item>
<article class="card" data-tb-region-item="">
Item guidelines
- All items must be tagged - including items that will not be personalized by Taboola.
There is one exception to this rule: if a given content slot is dedicated to sponsored content or other ad units, then it should not be tagged.
- Do not assign a value to the
data-tb-region-item
attribute.- Make sure to tag all relevant item properties - see next section.
Tag all item properties
- For each property in a given item, add the relevant
data-tb
attribute.See below: Available data attributes
- Set the attribute value to an empty string - or do not provide an assignment at all.
An example - tagging the item's thumbnail:
<img src="https://www.example.com/latest-news/gbiv68/picture272621373/alternates/LANDSCAPE_768/Heat76ersBasketball%20(1).JPG"
alt="Takeaways and details from Heat’s much-needed win over 76ers to snap losing skid"
loading="lazy" data-tb-thumbnail>
<img src="https://www.example.com/latest-news/gbiv68/picture272621373/alternates/LANDSCAPE_768/Heat76ersBasketball%20(1).JPG"
alt="Takeaways and details from Heat’s much-needed win over 76ers to snap losing skid"
loading="lazy" data-tb-thumbnail="">
Property guidelines
- Tag all relevant properties in the item.
Any property that needs to change when providing personalized content must be tagged.
- Note: different items within the same region might have different properties.
E.g. some items might display an
thumbnail
, and others not.- Note: not all properties are visible.
E.g. the link property is not visible.
- Do not assign a value to the
data-tb
attribute.
IMPORTANT
If any needed properties are not tagged, then Taboola will not be able to update them.
In that case, when Taboola provides personalized content, those properties will be incorrect.
Data attributes
All supported data attributes are listed in the tables below.
For a guided walkthrough, see the sample walkthrough, below.
Region
Each region has a single, required attribute.
Name | Data Attribute | Usage | Instructions |
---|---|---|---|
Region | data-tb-region | Required | Apply to the HTML container (e.g. <div> ) that wraps the items in that region.-- Make sure to follow the guidelines. |
Item
Each item has a single, required attribute.
Name | Data Attribute | Usage | Instructions |
---|---|---|---|
Item | data-tb-region-item | Required | Apply to the HTML element (e.g. <div> , <article> , etc.) that represents that item. |
Item properties
The commonly used attributes for item properties are listed below.
Tagging guidelines
- Occasionally, you may need to tag a given HTML element twice. For example, a link that wraps a title needs to be tagged as both a link and a title.
- Look carefully at the data attributes below:
- Some attributes are applied to the HTML element itself (e.g. the
<img>
tag).- Some attributes are applied to the element that directly wraps that value (e.g. for
Title
,Date
, etc.)Make sure to tag the element that directly wraps that value (not a parent of that element).
Name | Data Attribute | Usage | Instructions |
---|---|---|---|
Title | data-tb-title | Required | Apply to the HTML element that directly wraps the title (main headline) in that item. |
Link | data-tb-link | Required | Apply to the <a> tag in the item that links to the target article.-- Apply to the <a> tag itself - not a container that wraps <a> .If a given item contains 2 links - e.g. for the thumbnail and the title - then tag both of them. -- For an actual example, see the sample walkthrough. |
Thumbnail | data-tb-thumbnail | Common | Apply to the <img> tag in that item.-- Apply to the <img> tag itself - not a container that wraps <img> .If the item uses a background image (applied via CSS), contact your Taboola Newsroom Engagement Manager |
Date | data-tb-date | Common | Apply to the HTML element that directly wraps the published/updated date in that item. |
Category | data-tb-category | Common | Apply to the HTML element that directly wraps the category text in that item. |
Author | data-tb-author | Common | Apply to the HTML element that directly wraps the author text in that item. |
Description | data-tb-description | Common | Apply to the HTML element that directly wraps the description (heading subtext) in that item. |
Alternative headline | data-tb-alternative-headline | Not common | If relevant, apply to the HTML element that directly wraps the alternative headline |
Item properties for special use cases
Data attributes for special use cases are listed below.
In each case, the approach taken can vary, depending on specific needs and preferences.
To work out your own strategy, consult with your Taboola Newsroom Engagement Manager.
Name | Data Attribute | Usage | Instructions |
---|---|---|---|
Video icon | data-tb-video | Special Use Case | Indicates that the <img> tag is a video icon. |
Premium | data-tb-premium | Special Use Case | Indicates premium content - e.g. premium icons or text. |
Extension | data-tb-extension | Special Use Case | For special use cases only. For more detail, reach out to your Taboola Newsroom Engagement Manager |
Hide | data-tb-hide | Special Use Case | Indicates that Taboola should hide this content, when displaying a personalized recommendation. |
Custom | data-tb-[custom_name] | Special Use Case | If your item includes a property that is not listed on this page, then a custom property is needed for your account. For more detail, reach out to your Taboola Newsroom Engagement Manager |
A sample walkthrough
Refer to the sample screenshot, above.
- The code snippet below shows a sample region with 4 items before, tagging:
To expand the *untagged* code snippet, select the second tab (above)...
<div class="digest">
<div class="paper">
<article class="card">
<figure>
<a href="https://www.example.com/sports/nba/heat/article272609902.html#storylink=hpdigest_sports"
class="image-link-macro kfocusable"
title="Takeaways and details from Heat’s much-needed win over 76ers to snap losing skid"
>
<img src="https://www.example.com/latest-news/gbiv68/picture272621373/alternates/LANDSCAPE_768/Heat76ersBasketball%20(1).JPG"
alt="Takeaways and details from Heat’s much-needed win over 76ers to snap losing skid"
loading="lazy" >
</a>
</figure>
<div class="label sticky">
<h2 class="impact caps h5" >
Sports
</h2>
</div>
<div class="package">
<h3>
<a href="https://www.example.com/sports/nba/heat/article272609902.html#storylink=hpdigest_sports"
>
<svg xmlns="http://www.w3.org/2000/svg" width="12" height="14" viewBox="0 0 12 14">
<path fill="#a1a1a1" fill-rule="evenodd"
d="m22 556c2.1421954 0 3.8910789 1.683968 3.9951047 3.80036l.0048953.19964v2h1c.5522847 0 1 .447715 1 1v6c0 .552285-.4477153 1-1 1h-10c-.5522847 0-1-.447715-1-1v-6c0-.552285.4477153-1 1-1h1v-2l.0048953-.19964c.1040258-2.116392 1.8529093-3.80036 3.9951047-3.80036zm0 7-.7053423 2.02918-2.1478272.043769 1.7119017 1.297871-.622088 2.056231 1.7633558-1.227051 1.7633558 1.227051-.622088-2.056231 1.7119017-1.297871-2.1478272-.043769zm0-5c-1.0543618 0-1.9181651.815878-1.9945143 1.850738l-.0054857.149262v2h4v-2c0-1.104569-.8954305-2-2-2z"
transform="translate(-16 -556)" />
</svg>
Takeaways and details from Heat’s much-needed win over 76ers to snap
losing skid
</a>
</h3>
<div class="update-date time" data-originalDate="1677562907" >
Updated February 28, 2023 12:41 AM
</div>
</div>
</article>
<div class="package">
<h3>
<a href="https://www.example.com/sports/high-school/article272611517.html#storylink=hpdigest_sports"
>
<svg xmlns="http://www.w3.org/2000/svg" width="12" height="14" viewBox="0 0 12 14">
<path fill="#a1a1a1" fill-rule="evenodd"
d="m22 556c2.1421954 0 3.8910789 1.683968 3.9951047 3.80036l.0048953.19964v2h1c.5522847 0 1 .447715 1 1v6c0 .552285-.4477153 1-1 1h-10c-.5522847 0-1-.447715-1-1v-6c0-.552285.4477153-1 1-1h1v-2l.0048953-.19964c.1040258-2.116392 1.8529093-3.80036 3.9951047-3.80036zm0 7-.7053423 2.02918-2.1478272.043769 1.7119017 1.297871-.622088 2.056231 1.7633558-1.227051 1.7633558 1.227051-.622088-2.056231 1.7119017-1.297871-2.1478272-.043769zm0-5c-1.0543618 0-1.9181651.815878-1.9945143 1.850738l-.0054857.149262v2h4v-2c0-1.104569-.8954305-2-2-2z"
transform="translate(-16 -556)" />
</svg>
Westminster Christian’s beach volleyball squad motivated to recapture top
spot in state
</a>
</h3>
<div class="time" >
February 27, 2023 7:08 PM
</div>
</div>
<div class="package">
<h3>
<a href="https://www.example.com/sports/mlb/marlins/article272610917.html#storylink=hpdigest_sports"
>
Hampson making early impression on Marlins. Plus notes on Burdick, Luzardo,
Sixto
</a>
</h3>
<div class="time" >
February 27, 2023 4:18 PM
</div>
</div>
<div class="package">
<h3>
<a href="https://www.example.com/sports/nhl/florida-panthers/article272611760.html#storylink=hpdigest_sports"
>
Barkov and Bennett are out for another huge game. Here’s how the Panthers
must adjust
</a>
</h3>
<div class="time" >
February 27, 2023 3:05 PM
</div>
</div>
</div>
<a href="https://www.example.com/sports/" class="more-link">
More in Sports
</a>
</div>
- Click below to start. Once the walkthrough opens, click on each step:
- After tagging, the code snippet will look like this:
To expand the *tagged* code snippet, select the second tab (above)...
<div class="digest">
<div class="paper" data-tb-region='sports'>
<article class="card" data-tb-region-item>
<figure>
<a href="https://www.example.com/sports/nba/heat/article272609902.html#storylink=hpdigest_sports"
class="image-link-macro kfocusable"
title="Takeaways and details from Heat’s much-needed win over 76ers to snap losing skid"
data-tb-link>
<img src="https://www.example.com/latest-news/gbiv68/picture272621373/alternates/LANDSCAPE_768/Heat76ersBasketball%20(1).JPG"
alt="Takeaways and details from Heat’s much-needed win over 76ers to snap losing skid"
loading="lazy" data-tb-thumbnail>
</a>
</figure>
<div class="label sticky">
<h2 class="impact caps h5" data-tb-category>
Sports
</h2>
</div>
<div class="package">
<h3>
<a href="https://www.example.com/sports/nba/heat/article272609902.html#storylink=hpdigest_sports"
data-tb-link data-tb-title>
<svg xmlns="http://www.w3.org/2000/svg" data-tb-premium width="12" height="14" viewBox="0 0 12 14">
<path fill="#a1a1a1" fill-rule="evenodd"
d="m22 556c2.1421954 0 3.8910789 1.683968 3.9951047 3.80036l.0048953.19964v2h1c.5522847 0 1 .447715 1 1v6c0 .552285-.4477153 1-1 1h-10c-.5522847 0-1-.447715-1-1v-6c0-.552285.4477153-1 1-1h1v-2l.0048953-.19964c.1040258-2.116392 1.8529093-3.80036 3.9951047-3.80036zm0 7-.7053423 2.02918-2.1478272.043769 1.7119017 1.297871-.622088 2.056231 1.7633558-1.227051 1.7633558 1.227051-.622088-2.056231 1.7119017-1.297871-2.1478272-.043769zm0-5c-1.0543618 0-1.9181651.815878-1.9945143 1.850738l-.0054857.149262v2h4v-2c0-1.104569-.8954305-2-2-2z"
transform="translate(-16 -556)" />
</svg>
Takeaways and details from Heat’s much-needed win over 76ers to snap
losing skid
</a>
</h3>
<div class="update-date time" data-originalDate="1677562907" data-tb-date>
Updated February 28, 2023 12:41 AM
</div>
</div>
</article>
<div class="package" data-tb-region-item>
<h3>
<a href="https://www.example.com/sports/high-school/article272611517.html#storylink=hpdigest_sports"
data-tb-link data-tb-title>
<svg xmlns="http://www.w3.org/2000/svg" data-tb-premium width="12" height="14" viewBox="0 0 12 14">
<path fill="#a1a1a1" fill-rule="evenodd"
d="m22 556c2.1421954 0 3.8910789 1.683968 3.9951047 3.80036l.0048953.19964v2h1c.5522847 0 1 .447715 1 1v6c0 .552285-.4477153 1-1 1h-10c-.5522847 0-1-.447715-1-1v-6c0-.552285.4477153-1 1-1h1v-2l.0048953-.19964c.1040258-2.116392 1.8529093-3.80036 3.9951047-3.80036zm0 7-.7053423 2.02918-2.1478272.043769 1.7119017 1.297871-.622088 2.056231 1.7633558-1.227051 1.7633558 1.227051-.622088-2.056231 1.7119017-1.297871-2.1478272-.043769zm0-5c-1.0543618 0-1.9181651.815878-1.9945143 1.850738l-.0054857.149262v2h4v-2c0-1.104569-.8954305-2-2-2z"
transform="translate(-16 -556)" />
</svg>
Westminster Christian’s beach volleyball squad motivated to recapture top
spot in state
</a>
</h3>
<div class="time" data-tb-date>
February 27, 2023 7:08 PM
</div>
</div>
<div class="package" data-tb-region-item>
<h3>
<a href="https://www.example.com/sports/mlb/marlins/article272610917.html#storylink=hpdigest_sports"
data-tb-link data-tb-title>
Hampson making early impression on Marlins. Plus notes on Burdick, Luzardo,
Sixto
</a>
</h3>
<div class="time" data-tb-date>
February 27, 2023 4:18 PM
</div>
</div>
<div class="package" data-tb-region-item>
<h3>
<a href="https://www.example.com/sports/nhl/florida-panthers/article272611760.html#storylink=hpdigest_sports"
data-tb-link data-tb-title>
Barkov and Bennett are out for another huge game. Here’s how the Panthers
must adjust
</a>
</h3>
<div class="time" data-tb-date>
February 27, 2023 3:05 PM
</div>
</div>
</div>
<a href="https://www.example.com/sports/" class="more-link" data-tb-category data-tb-link>
More in Sports
</a>
</div>
Making changes to the homepage
Before publishing a new homepage layout, make sure to update your Taboola integration:
- Tag all affected regions and articles with
data-tb
attributes.- Sync with your Taboola Newsroom Engagement Manager to update your server-side configuration.
Add scripts to the article pages
Already using FrontPage?
If you are currently using FrontPage for Newsroom,
newsroom.js
should already be present.In that case, you can skip to the next section: Cater for special use cases
- Add the following script to each article, inside the
<head>
section:
<script>
window._newsroom = window._newsroom || [];
!function (e, f, u) {
e.async = 1;
e.src = u;
f.parentNode.insertBefore(e, f);
// Fill in your Publisher ID (an alphabetic string, as provided by Taboola):
}(document.createElement('script'),
document.getElementsByTagName('script')[0], '//c2.taboola.com/nr/<publisher-id>/newsroom.js');
</script>
- Replace
<publisher-id>
with your own Publisher ID, as provided by Taboola - or use the prefilled script provided by your Taboola Newsroom Engagement Manager.
Placeholder text | Description | Notes |
---|---|---|
<publisher-id> | Your Taboola Publisher ID | An alphanumeric String, as provided by Taboola. If your Publisher ID is '<<publisherID>>' , then the URL should read:'//c2.taboola.com/nr/<<publisherID>>/newsroom.js' -- Note: newsroom.js does not support network-level integration - you must provide a specific account.For more detail, reach out to your Taboola Newsroom Engagement Manager. |
Which pages?
Place the script on each article or post - e.g. article posts, video posts, gallery pages, etc.
Guidelines
- Load the above scripts as soon as possible - without any lazy loading.
- Do not split a given script into multiple parts. This can cause a race condition and may result in a loss of data.
Cater for special use cases
During the initial scoping, you may decide to cater for special use cases - e.g. to implement a flow for premium content, or a flow for custom business logic.
This might include either of the following steps:
- Add metadata to your article pages - e.g. to tag certain pages as premium content.
- Provide Taboola with relevant hooks to your existing solution - e.g. so Taboola can insert icons or text, according to your own business logic.
The exact approach taken will vary, depending on your specific needs and preferences.
Consult with your Taboola Newsroom Engagement Manager to iron out a strategy that works best for you.
Verify your integration
Once the integration is complete, reach out to your Taboola Newsroom Engagement Manager. Taboola will assist your team to verify that the integration is working smoothly.
Need a hand?
For specific guidance, at any stage of the integration, reach out to your Taboola Newsroom Engagement Manager.
Updated 8 days ago