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 toSports.
- 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)

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 like region-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. forTitle, 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:

Walkthrough - tagging a region with 4 items

Open Recipe

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.