Policy Builder user guide

OVERVIEW

In Homepage For You, Taboola’s recommendation engine matches users with their optimal experiences based on their interest, location, time of day, what’s trending etc. But editorial teams set the rules of engagement for those matches, determining explicitly which articles, videos and galleries are available in the recommendable inventory at any given moment. Policy Builder is the tool to create these guidelines, called “policies.”

A page in HP4U is comprised of distinct regions, such as “breaking news” or “local sports”, which are defined by the publisher in the initial implementation phase. These regions can contain any number of slots for content. A business region might contain 4 content positions, as in the image below.

An editorial team will use Policy Builder in Taboola Newsroom to create policies for regions, determining the content that is available to be recommended for personalization in that area. The Policy Builder tool is accessed in the left rail navigation under Homepage For You.

In short, a “policy” is a series of filters and parameters based on structured data properties like URL or meta tags — fields which are mostly unique to each publisher. They will include settings like category, age of content, content type, content source, paywall status etc. These parameters are available as both inclusions and exclusions.

Example: A publisher has a four-item homepage module and wants it to feature personalized recommendations that are only staff-created entertainment and lifestyle content from the last three days, excluding branded content, and limited to only articles and video.

SETUP AND CONFIGURATION

The following general steps must be completed before a user can begin to create and assign policies to regions of a page:

Content mappings must be completed to determine what custom filters are available
Homepage For You must be enabled
All regions must be tagged, mapped and validated
All slots must be properly tagged and validated
Newsroom must be implemented

For full instructions, consult the documentation in Taboola’s Developers’ Center.

Note: All critical fields of content-level pages must be properly mapped, including fields like category, timestamp, paywall status, content type, etc. before policies are created in Policy Builder. This step is completed by Taboola’s Professional Services team, although many of the mappings are done as part of initial onboarding with Taboola.

Example: An article might contain structured data such as:

These could be used to, for example, to create rules that include or exclude wire service content or opinion content or restrict recommendations to articles only.

Please contact your account manager if some properties are not mapped and available in Policy Builder.

POLICY TYPES

There are currently two types of policies in Homepage For You: Page Policies and Region Policies. They exist in a hierarchy where the properties of Page Policies cascade down to Region Policies. Both are created and edited within Policy Builder.

Note: The action of creating a policy is separate from attaching it to a region on a homepage. Policies can exist without being associated with a region and regions can exist without policies (although without policies those regions won’t contain personalized recommendations).

A. Page Policy

A Page Policy contains properties that are inherited by all Region Policies on a single page. For example, if you exclude all sports betting content by URL — /sports/betting/ — in a Page Policy on the homepage, all Region Policies attached to regions on that site’s homepage will inherit that exclusion, regardless of the number of regions. Each page can only have a single Page Policy, however.

Note: You cannot manually attach a Page Policy to a region on a page. Page Policies exist as an efficiency to set page-wide rules via inheritance to Region Policies.

B. Region Policy

A Region Policy is the primary bundle of rules which govern recommendation on an area of a page.

A Region Policy can be applied to a single region or multiple regions on a page.
A region can only have one region-level policy attached.
Region Policies will inherit inclusions and exclusions from Page Policies, as detailed above.

POLICY BUILDER NAVIGATION

The primary Policy Builder UI consists of two pages: a lobby page displaying the existing policies and a detail page where policies are created or edited.

A. Policy Builder lobby page

The Policy Builder lobby page provides an overview of all existing content policies, showing: name, inventory, policy type, regions in use, last modified date and the user taking that last action. It also has a search function that filters on policy name.

From this lobby page, a user has the option to create a new policy or they can select a policy to edit, delete or duplicate. To access these three functions, hover on the far right side of a policy row until the three dots appear, click, and then select the desired action.

Edit Policy: This action allows an editor to make changes to existing policies. Note that any edits to an existing policy will affect the projected inventory, so be sure to “preview policy” after any changes are made and verify the projected inventory count.
Delete Policy: This action can only be applied to policies not attached to a region. An error will be shown if the user attempts this action to a policy actively in use.

Duplicate Policy: This action creates and launches a copy of that policy in the main Policy Builder editing page, pre-populated with that policy’s settings. The policy’s new name is [source name] + “copy” by default, but it can be edited.

Low inventory warning

To ensure optimal recommendations, the inventory should have a minimum available item count. If a policy’s settings restrict available inventory below the desired threshold, a warning will be shown. In the earlier example, a warning icon is shown in the inventory count column and a red screen is rendered over the policy row because it has only two items in recommendable inventory.

To address this issue, a user could add more categories, lengthen the lookback setting, add a backfill setting or remove a custom filter.

Create new policy

Initially, when a user creates the first policy, they will be prompted to choose either a Page Policy or a Region Policy. But once the Page Policy is created, that step, shown below, will be bypassed.

B. Policy Builder editor

The Policy Builder editor page is the primary policy creation and editing interface. Any edit or create action taken from either the Heads-up Display or lobby page will take you to this page.

This page consists of tools for saving, closing, duplicating and deleting, a series of settings and filters, and a preview panel on the right.

General Settings

This area consists of a policy name and rules for how old recommendable content should be.

Policy Name: Alphanumeric field, limited to 56 characters. It is searchable so it’s recommended to use critical keywords. Policy names must be unique. This is a required field.
Max Item Age: Indicates the look-back window for recommendable content. Content must be published and/or updated during this time period to be eligible. There are preset supported values, including: 12 hours, 24 Hours, 36 hours, 48 hours, 3 days, 5 days, 7 days, 14 days, 30 days, 90 days and 1 year. There also is an option to add a custom value in daily increments, including decimals. This is a required field.
Backfill Max Item Age: A fallback setting in the event that there is insufficient inventory that meets the Max Item Age setting. Not required but recommended.

Inherited Page Policy Settings

In a Region Policy, this area details what inclusion and exclusion rules are inherited from Page Policies. It has a show more/show less toggle. These cannot be edited from a Region Policy page. You must edit that Page Policy.

Custom Settings

Custom settings allow a user to more granularly tailor the recommendable content. As detailed earlier, all category values are contingent upon proper structured data mapping performed in earlier stages of the HP4U integration.

Applying a Custom Setting is done in two steps:

Define your filtering rule, either include or exclude.
Select the property or properties which will be included or excluded. These properties also can be later edited or deleted.

What custom settings are available is dependent on your site’s metadata and mapping. However, there are some global parameters which exist in all configurations.

1. Category

Categories are drawn from mapped categories or site sections.
The default empty represents “all”.
It’s a searchable field.
A user can include/exclude categories or sub-categories. When a user selects a top-level category, the subcategories automatically are included but can be excluded individually.
A user can include a parent category (Business) but exclude a subcategory (Business/Stocks) with an “exclude category” filter. Example below is of including category sports and excluding category national sports.

The list will only show categories that had at least one article published in them in the last 30 days.
Items that do not have a valid category will only be recommendable if a policy allows “all” categories.
If you later add categories to a policy which already includes or excludes a category, it will add them to that previously established Custom Setting rule upon save rather than keep it as a new separate rule.

2. Page type

Represents article, video, photo gallery etc content types.
Default is “all”.

3. Thumbnail pattern

Available for exclusion only.
A user might want to block articles with a site logo as the thumbnail image in content position that show an image.
Open text field that supports partial match, ie /image/sitelogo.png.

4. URL pattern

Available for exclusion only.
Open text field that supports partial match, ie -letter-to-the-editor-.

5. Canonical-domain

Available for inclusion or exclusion.
Open text field that supports partial match, i.e., mysite.com and www.mysite.com both work.

Policy Preview panel

The area of Policy Builder allows you to validate the accuracy of your policy by showing you a sample of the recommendable inventory. This is based on the combined rules of the Region Policy and inheritance from a Page Policy.

The preview panel will display the number of regions in use, the primary projected inventory and the projected backfill inventory. Note: There’s some caching here so while the numbers will be fresh they are not real time.

Most importantly, this panel displays the category, headline and thumbnail image of as many of 20 of the most recent items which match this policy.

In essence, this preview panel allows users to proof their work, including identifying accidental conflicts. For example, if an editor includes a category “shopping” but excludes /shopping/ by URL, there’s no true error message. However, you will see shopping content has been excluded in the preview panel and the inventory would be 0 if that were the only category.

Full-flow policy creation example

In this flow below, a user names a policy, selects a max item age and backfill age, selects two categories to include, excludes wire service content and then previews the policy to ensure the content is as desired.