---
updatedAt: 2025-08-27T07:16:58.000Z
---
# 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*.
### A bird's-eye view
The following summary provides a *bird's-eye view* of the integration:
> ๐ง
>
> **Homepage**
>
> 1. Add the relevant `
```
{`
Param
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:
'//c2.taboola.com/nr/<<publisherID>>/newsroom.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
1. Immediately below the above script, add the **Taboola** *newsroom* script (see below).
2. Fill in your **param** values - or use the *prefilled* script provided by your **Taboola** *Newsroom Engagement Manager*.
```html Newsroom script for homepage
```
{`
Placeholder/Param
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.
pageTemplate
Fill in your template name, as provided by Taboola. E.g. 'home'
pageDashboard
Fill in your dashboard name, as provided by Taboola. E.g. 'home'
`}
> ๐ง Guidelines
>
> 1. Load the scripts **as soon as possible** - *without* any lazy loading.
> 2. 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 <>s and <>s on your homepage.
Make sure you received the above *<>* from your **Taboola** *Newsroom Engagement Manager*. Using that sheet as a guide, follow the steps below to tag all <>s and <>s 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** <>s.
#### Terminology
> ๐
>
> Refer to the [sample screenshot](https://developers.taboola.com/newsroom/docs/hp4u#a-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)
#### A sample screenshot
> ๐ Sample walkthrough
>
> For a guided *walkthrough* of how to tag the region depicted above, see the [sample walkthrough](https://developers.taboola.com/newsroom/docs/hp4u#a-sample-walkthrough).
### Tagging steps
#### Tag *all* regions
For **each** region on the homepage:
1. Add a `data-tb-region` attribute to the `
` or HTML block element that *wraps* that region.
2. Set the attribute *value* to the **region name**.
```html Example
```
> ๐
>
> Refer to the *<>* provided by your **Taboola** *Newsroom Engagement Manager*.
> ๐ง Region guidelines
>
> 1. **All** regions must be tagged - *including* regions that will *not* be personalized by **Taboola**.
> 2. Do **not** nest a region *within* another region.
> 3. Make sure that **every** item is enclosed within a region.
> 4. Assign a *region name* to each `data-tb-region` attribute:
> 1. The *name* **must** be **unique**.
> 2. 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:
1. Add a `data-tb-region-item` attribute to the HTML element for that item.
2. Set the attribute *value* to an **empty** string - or leave out the value altogether.
```html Example 1
```
```html Example 2
```
> ๐ง 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
1. For **each** property in a given item, add the **relevant** `data-tb` attribute.
> See *below*: [Available data attributes](https://developers.taboola.com/newsroom/docs/hp4u#available-data-attributes)
2. Set the attribute *value* to an **empty** string - or do not provide an assignment at all.
An example - tagging the item's thumbnail:
```html Example 1
```
```html Example 2
```
> ๐ง 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](https://developers.taboola.com/newsroom/docs/hp4u#a-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. `
`) that *wraps* the items in that **<>**.Make sure to follow the [guidelines](https://developers.taboola.com/newsroom/docs/hp4u#tag-all-regions). |
#### 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. `
`, ``, etc.) that represents that **<>**. |
#### Item properties
> ๐
>
> The *commonly used* attributes for **item <>** 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 `` 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 TaboolaNewsroom 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.
This attribute is required in certain cases only, and works together with data-tb-category (see above row).
Guidelines:
Always tag the immediate parent with data-tb-category (see above row).
If that parent is not an <a> element, then tag the wrapping <a> element with data-tb-category-link. Example: <a data-tb-category-link href="http://domain.com/sports">
Sports
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.
>
> Working with these attributes typically requires some *customization*.
>
> To iron out a 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 TaboolaNewsroom 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 TaboolaNewsroom Engagement Manager
`}
### A sample walkthrough
> ๐
>
> Refer to the [sample screenshot](https://developers.taboola.com/newsroom/docs/hp4u#a-sample-screenshot), above.
1. The code snippet below shows a sample *region* with **4** *items* **before**, tagging:
```text Instructions
To expand the *untagged* code snippet, select the second tab (above)...
```
```html Sample - Before tagging
```
2. **Click** below to *start*. Once the walkthrough opens, **click** on each *step*:
3. **After** tagging, the code snippet will look like this:
```Text Instructions
To expand the *tagged* code snippet, select the second tab (above)...
```
```html Sample - After tagging
```
### Changing 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*
1. Add the following script to each **article**, inside the `` section:
```html Newsroom (Article post)
```
2. Replace `` with your own Publisher ID (*or* Network ID), **as provided by Taboola** - or use the *prefilled* scripts that were provided.
{`
Placeholder
Description
Notes
<publisher-id>
Your Taboola Publisher ID (or Network 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'
`}
> ๐ 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.
## Validate your tagging
in order for **`HP4U`** and **`Newsroom`** to run smoothly, it's **critical** that all <>s, <>s and <> are tagged correctly.
> ๐ง
>
> If tagging was **not** implemented *fully* and *correctly*:
>
> 1. *Personalized* content may display **incorrectly** (or not at all).
> 2. *Curated* content might be **duplicated** by *personalized* content.
To help with validation, **Taboola** provides a **Chrome extension**.
> ๐ Which validations does it run?
>
> A list of validation rules run by the extension can be found in the [appendix](https://developers.taboola.com/newsroom/docs/hp4u#validation-rules).
>
> ***
>
> **Tip**: These rules can also provide a valuable **guideline** for **tagging** your homepage.
### The Chrome extension
The **Taboola Chrome extension** provides a **Head-Up Display (HUD)** of your **HP4U** configuration, allowing you to **validate your markup** and **fine-tune your settings**.
> ๐ง Setup requirements
>
> Before your team can use the **Chrome extension**:
>
> 1. **Taboola** must enable **HP4U** for *the chosen domain*.
> 2. You must [embed `newsroom.js`](https://developers.taboola.com/newsroom/docs/hp4u#add-newsroom-js) in your homepage, *under that domain*.
> 3. **Each user** that accesses the **extension** will need a **`Taboola Newsroom`** **user account** *for that domain*.
>
> ***
>
> To confirm that your setup is complete, reach out to your **Taboola** *Newsroom Engagement Manager*.
> ๐ Additional resources
>
> This page describes how to **validate your markup**.
>
> For additional information about the **Chrome extension**, see the **Taboola Newsroom Help Center**.
### Installing the extension
1. Install the **Taboola Chrome extension** from the **Chrome Web Store**.
> **Tip**: Once installed, click on **Extensions** and pin the extension icon .
### The extension slide-out
1. Open **Google Chrome** and browse to **your homepage**. Wait for the homepage to load **fully**.
> **Tip**: Once you have [enabled](doc:https://developers.taboola.com/web-indoc:hp4u#running-general-validations) the extension, the icon turns blue once the page has loaded.
2. Click on the extension icon to *slide-out* the extension window.
> **Tip**: You may need to click on **Extensions** to see the icon.
3. If you are not logged into **Taboola Newsroom**, the extension will prompt you to log in.
> In order to use the **Chrome extension**, you need a **Taboola Newsroom** account with the relevant permissions.
### Two validation types
The **Chrome extension** supports **2 validation types**:
1. [**General** (*aka* **automatic**) validations](https://developers.taboola.com/newsroom/docs/hp4u-chrome-extension#running-general-validations) - these run **automatically**, as soon as **`Display page markup`** is enabled (as explained below).
2. [**Property-specific** (*aka* **manual**) validations](doc:doc:hp4u-chrome-extension#running-property-specific-validations) - these can be enabled on a per-<> basis.
### Running *general* validations
1. Open the extension **slide-out**.
2. **Enable** the extension, using the **toggle switch** provided (*top, right*).
> * **Tip**: *At any time*, use this toggle to quickly view a 'clean' homepage (without annotations).
3. In the extension **slide-out**, select the **`Validation`** **tab**, and click on the **`Display page markup`** **toggle switch** (*middle, right*).
4. *On your homepage*, **note** how **each** <> displays a validation **icon** (*top, left*):
5. Review each item of interest, and check for a **failure** or **warning** status:
| Icon | Status | Description |
| :------------------------------------------------------------------------------- | :---------- | :----------------------------------------------------- |
| | **Failure** | 1 or more validations **failed** for this item. |
| | **Warning** | 1 or more properties in this item *might* need fixing. |
| | **Success** | All validations **passed** for this item. |
6. To see more information, **mouse over** the status icon:
> ๐
>
> In the above example, the `data-tb-category` attribute was **not** applied to an **anchor** tag.
> Since the *direct* parent of the category text might be a different tag, this is a warning only.
> ๐
>
> Mousing over the status icon will show **all** warnings (and errors) that apply to that item.
### Running *property-specific* validations
> ๐ง Before you start
>
> In order to run ***property-specific* validations**, you must turn on [***general* validations**](https://developers.taboola.com/newsroom/docs/hp4u-chrome-extension#running-general-validations).
1. In the extension **slide-out**, select the **`Validation`** tab.
2. Locate the **color-coded list** of item properties (shown *below*).
3. For *each* item property, use the checkbox provided to turn validations on/off.
4. The following example illustrates, using the `Title` property:
1. Select **`Title`**:
2. *On your homepage*, each\*\*`Title`\*\* is annotated, using the *same* color as the **property list**:
3. Deselect **`Title`** (by clearing the checkbox):
4. *On your homepage*, annotations for **`Title`** are removed:
5. Continue to enable validations for **each** <> of interest. *On your homepage*, each property is marked with a matching color - e.g. titles in \yellow, links in \green, etc.
6. Once you have enabled 1 or more *property-specific* validations, review each <> of interest, and check for a **failure** or **warning** status:
| Icon | Status | Description |
| :------------------------------------------------------------------------------- | :---------- | :----------------------------------------------------- |
| | **Failure** | 1 or more validations **failed** for this item. |
| | **Warning** | 1 or more properties in this item *might* need fixing. |
| | **Success** | All validations **passed** for this item. |
7. To see more information for each error, **mouse over** the status icon.
> Mousing over the status icon will show **all** warnings (and errors) for that item.
### An important caveat
**Note** that a given <> might not contain the selected <> **at all**. If that is intentional, then simply **ignore** the error shown. The following **example** illustrates:
1. In the **property list**, the user selects\*\*`Author`\*\* (to run validations for items that *do* contain an author).
2. A given item (*shown below*) does not contain author text *at all*.
3. The extension detects that there is **no `data-tb-author`** attribute within that item, and flags an error: **`Missing tag(s): Author`**.
4. However, since this item is not *supposed* to contain an author *at all*, you can simply ignore the error and move on.
### Validation rules
When validating your homepage, the **Chrome extension** applies the following rules:
> ๐ Tip
>
> The rules below provide a valuable **guideline** for **tagging** your homepage.
{`
data-tb-link is present - but is not in an <a> tag.
Warning
data-tb-link is missing in the additional<a> tags.
Warning
data-tb-category is not in an <a> tag.
Warning
Data attribute is assigned to an indirect parent (instead of the direct parent).Applies to: data-tb-title, data-tb-description, data-tb-category
Error
More than 1 data-tb-title is present in the item.
Error
More than 1 data-tb-thumbnail is present in the item.
Error
More than 1 data-tb-description is present in the item.
Error
More than 1 data-tb-category is present in the item.
Error
property-specific validation failed.Either the HTML element is present and was not tagged - i.e. an error.Or the HTML element itself is not present - e.g. an <glossary:item> without an image - which may be intentional.
`}
## Verify your integration
Once your 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*.
.JPG)
```
```html Example 2
and pin 
the extension icon 
.
### The extension slide-out
1. Open **Google Chrome** and browse to **your homepage**. Wait for the homepage to load **fully**.
> **Tip**: Once you have [enabled](doc:https://developers.taboola.com/web-indoc:hp4u#running-general-validations) the extension, the icon turns blue 
once the page has loaded.
2. Click on the extension icon 
(*top, right*).
> * **Tip**: *At any time*, use this toggle to quickly view a 'clean' homepage (without annotations).
3. In the extension **slide-out**, select the **`Validation`** **tab**, and click on the **`Display page markup`** **toggle switch** 
(*top, left*):
5. Review each item of interest, and check for a **failure** or **warning** status:
| Icon | Status | Description |
| :------------------------------------------------------------------------------- | :---------- | :----------------------------------------------------- |
| 
| **Failure** | 1 or more validations **failed** for this item. |
| 
| **Success** | All validations **passed** for this item. |
6. To see more information, **mouse over** the status icon:
> ๐
>
> In the above example, the `data-tb-category` attribute was **not** applied to an **anchor** tag.
> Since the *direct* parent of the category text might be a different tag, this is a warning only.
> ๐
>
> Mousing over the status icon will show **all** warnings (and errors) that apply to that item.
### Running *property-specific* validations
> ๐ง Before you start
>
> In order to run ***property-specific* validations**, you must turn on [***general* validations**](https://developers.taboola.com/newsroom/docs/hp4u-chrome-extension#running-general-validations).
1. In the extension **slide-out**, select the **`Validation`** tab.
2. Locate the **color-coded list** of item properties (shown *below*).
3. For *each* item property, use the checkbox provided to turn validations on/off.
4. The following example illustrates, using the `Title` property:
1. Select **`Title`**:
2. *On your homepage*, each\*\*`Title`\*\* is annotated, using the *same* color as the **property list**:
3. Deselect **`Title`** (by clearing the checkbox):
4. *On your homepage*, annotations for **`Title`** are removed:
5. Continue to enable validations for **each** <