Content Settings for Piano Composer

Overview

Most tracking and segmentation is built directly into Piano's JavaScript library. However, because there are some segmentation and tracking capabilities within Composer that are unique to your site's configuration, you'll need to send this information to Piano using a few simple tp.push commands (note that the tp object must be initialized prior to tp.push commands).

Data Types

AAM Reporting Zones

If you are subject to Alliance for Audited Media reporting, Zones can be used to generate reports about how your print customers are engaging with online offerings. Here's how you'd set a Zone called "Web":

 tp.push(["setZone", "Web"]);

Zones are specified on a page-by-page basis according to the JavaScript on a given page. Zone names, which are case-sensitive, are freely defined by publishers. By nature, Zones are mutually exclusive and the same page cannot belong to multiple Zones. However, distinct versions of a page can each include separate Zones. Say a publisher had two Zones, “desktop web” and “mobile web.” In such a case, you could set two distinct Zones on the same page by adding Zone-related JavaScript to the HTML and/or CSS specific to the mobile and desktop versions of that page. Though desktop users and mobile users would be viewing the same content, the page code (and the associated Zone information) would be distinct to their device.

When a logged-in user with access to a resource visits a Zone page, that user's information will be captured in the part of the AAM report related to that Zone. You can also segment in Composer based off the pages associated with particular Zone names. For more information on using Zones, see the associated section in the Effective Pages documentation.

Custom Variables

Any variable recognized by your website can be passed to Piano as a Custom Variable. These Custom Variables are added as a key-value pair. The first parameter is the key; the second is the value. Clients using Composer without Management + Billing will want to use Custom Variables to target based upon a user's subscription, registration, or login status because that user segmentation information is not stored within Piano if you are not using Management + Billing.

Here's an example where we're setting a user state Custom Variable for subscribers:

tp.push(["setCustomVariable", "userState", "Subscriber"]);

Custom Variables are also often used to target based on newsletter status and based on data from third-party analytics tools.

In addition, clients may target users who are interested in a particular piece of content. Website pages that placehold such content will pass arrays as variables containing the subject, category, and/or subcategory of the article as respective values. Piano will process these values to target the right audience. To be identified by Piano, an array type of variable should be declared in the script.

IMPORTANT: Custom variables must be set on every page load before any Composer experience is triggered. This ensures that the Experience engine can correctly evaluate any conditions or segments based on these custom variables. Note that these cannot be used later in the user journey.

Here’s an example where we’re setting an array type Custom Variable for users who are interested in the history of the Second World War:

tp.push(["setCustomVariable", "userInterest", ["WorldWars", "SecondWorldWar", "HistoryWars"]]);

For other popular Custom Variable use cases, see the associated section in the User Segmentation documentation.

You can validate if any custom variables have been successfully set on a page by running the following command in the browser's console:

tp.customVariables

Custom Variable limitations

Each Custom Variable set that you submit must contain no more than 75 custom variables and 1 KB of data total (uncompressed). If you would like best practices on how to effectively leverage Custom Variables, please contact your Piano representative.
Custom Variables are case-sensitive
Each Custom Variable is added as a key-value pair
JSON objects aren't supported as Custom Variables, we support only primitives and arrays

Publish Date

The publish date should be an ISO 8601-formatted string that includes the published date and time of the content, local to your website's timezone. For instance, a piece of content that was published at 4am in New York on April 3rd, 2017 would be set like this:

tp.push(["setContentCreated", "2017-04-03T08:00:00"]);
OR 
tp.push(["setContentCreated", "2017-04-03T04:00:00-04:00"]);

Piano does currently support the following date formats:

2005-07-16T19:20:30+01:00
2005-07-16T19:20:30+0100
2005-07-16
2005-07-16T18:20:30
2005-07-16 18:20:30
2016-02-09T18:31:48Z
Sat, 16 Jul 2005 17:20:30 -0100
Sat, 16 Jul 2005 18:20:30 +0000
1455042708 (epoch sec)
1455042708000 (epoch mills)

The below 2 date formats are not supported:

2021-W31
2021-W31-6

Author

The author field should contain information on the author that published the content. For instance:

tp.push(["setContentAuthor", "Ernest Hemingway"]);

Authors can also be specified using meta tags like this:

XML

<head> 
<meta name="author" content="Ernest Hemingway">
</head>

Note that author tp.push commands will overrule author meta tags. Only one author can be passed for each page – arrays are not permitted.

Section

This field should contain the section that the content belongs to. For example:

tp.push(["setContentSection", "Literature"]);

Sections can also be specified using meta tags like this:

XML

<head>    
  <meta name="section" content="Literature">
</head>

Note that section tp.push commands will overrule section meta tags. Sections are freely-definable. They do not necessarily have to match the section names on your website. Only one section can be passed for each page – arrays are not permitted.

Content sections will be automatically added to content profiles (as pn-section) and can be used for segmentation and analytics in Piano Audience and Insight – showing up as Piano content section in the Content GUI.

Native Content

You can mark content on your site as native if it is sponsored by a third party. If the native content flag is set to false, it means that content is editorially created. If set to true, it means that this is sponsored or external content. For example:

tp.push(["setContentIsNative", false]);

Custom Parameters (not supported by Composer segmentation)

Custom parameters allow you to send name-value pairs along with a scope parameter that's used to categorize those name-value pairs as belonging to a parent category (such as the user profile, content type, or any other parent category you devise).

Each custom parameter set that you submit should contain no more than 75 custom parameters and 1 KB of data in total.

Custom parameters can't be used for segmentation in Composer. See the Custom variables section for more information on how you can use these for segmenting your website's audience.

The main purpose of custom parameters is to provide advanced data analysis via custom reports. For more information about custom reports please contact your Piano Account Manager.

Note, that we might add some params automatically to execute a request from our end. For example, if an end user has any adblocker enabled, we add 2 parameters to the customParams list: _abr and _absh. That means that even if you do not exceed the customParams limit from your end, it might be exceeded during the actual execution.

Here's the basic code structure for custom parameters:

tp.push(["setCustomParam", "name", "value", "scope"]);

Values can also be an array of strings. Like this:

tp.push(["setCustomParam", "name", ["value1","value2","value3"...], "scope"]);

Example Custom Segmentation and Tracking Code

To give you a clear idea how this segmentation and tracking information should be added to the Piano JavaScript already on your site, here's a block of the standard Composer JavaScript for a Production application with additional segmentation and tracking information included:

tp = window["tp"] || [];
// The content published date
tp.push(["setContentCreated", "2017-04-03T04:00:00"]);
// The content author
tp.push(["setContentAuthor", "Ernest Hemingway"]);
// The content section
tp.push(["setContentSection", "Literature"]);
// The content tags
tp.push(["setTags", ["sports", "breaking-news", "premium"]]);
// If the content is native advertising
tp.push(["setContentIsNative", false]);
// The AAM Zone
tp.push(["setZone", "Web"]);
// Add custom variables as any key-value pair. The first parameter is the key; second is the value
tp.push(["setCustomVariable", "userState", "Subscriber"]);

Note that parameters like published date, author, section, and others must be set prior to the init callback. You must also call the init function even if you are only tracking pageviews and have an empty init callback.

Last updated: July 02, 2026