Introduction to Composer

Composer lets publishers create and deliver Experiences for their customers based on a variety of scenarios, rules, triggers and conditions.

It is a tool that enables you to target specific groups within your audience, on specific pages of your site, with tailored Experiences — all without writing a single line of code.

With Piano Composer you can design, test, deploy and manage sophisticated business models by simply dragging cards onto a Canvas.

How it works

The Canvas has column headers under which you drop cards from the sidebar Palette. Each card is a graphic element with rules and logic attached to it. Only certain cards can be dropped in certain columns, eliminating room for error. Once dropped, the card properties will appear, allowing you to make your configuration settings: the who-what-where-when-how.

Composer Guide

In this guide you will find a summary of the sidebar, shifting into how the sidebar cards manifest under each Canvas heading, then we delve deeper into configuration settings of those cards. Lastly, integration directions are found at the bottom of the guide.

On this page we will be covering most aspects of Composer in detail. For a quick how-to example of Composer, go to the Quick Start Guide.


Pageview meter: control the number of free pageviews a user has before encountering an Action
Interaction: define user interaction such as a click, a mouse over, a video play or any other user behavior that engages with your site
Scroll depth: trigger Events for users based on their scroll depth – target the users most engaged with your content by triggering Events when they have reached the bottom of the page
Timer: measure engagement and serve offers based on time spent on your site
Page Key: lock select pages only and show certain Actions only to the users that hit those pages

Segment users: further segment users as they move down the Experience funnel
Split test: test up to 10 different variants to find which Experiences convert the greatest number of users

Show Offer: display a call to action to purchase a subscription, register to read more articles, view a video for more access, etc.
Show Template: present a template to a user. Show Template is different from Show Offer, because a user cannot make a purchase in a simple template.
Apply CSS: change the appearance of your site based on user location in the Experience. For example, place specific ads or remove ads altogether
Non-site Action: integrate with any third-party API so that you can, for example, trigger a Sailthru email
Run JS: input JavaScript to be run when the user hits this part of their site journey

Composer Canvas

The Canvas is the working area onto which cards are dragged and dropped to make connections that form Sequences: complete chains of action from Effective Pages that lead to eventual Actions in the Experience. Sequences manifest as Experiences: what your users see and encounter when they visit your site.

On the Canvas you can create split tests, segment your users, and present them with Actions such as a value exchange or a non-site action. You can configure innumerable Experiences and have any number of them live or inactive.

When creating a new Experience, the first card on your Canvas will always be Effective Pages, listed under the Experience Rules column on your Canvas. On the Effective Pages card, you assign what URLs and tags you want to include and exclude to your Experience, keep reading for more particulars.

Experience Rules


On the Pages card you enter the content you want to meter and include it in your Offer based on URLs and/or tags, in effect constructing your Resource.

For example, if is your base URL and you plan to gate access to the sections U.S., Politics, and World, treating each as an independent Resource, each will require an independent Composer Experience.

On the Pages card, you include all URLs and tags pertaining to each.

All URL entries run off the base URL you have listed on your Piano application, so there's no need to enter Rather, you can just enter /business.

As you likely have numerous pages on your site consisting of countless URLs, there is an easy way of categorizing these URLs within Piano by using prefixes and asterisks. Especially useful for grouping sections, a wildcard acts like this:

  • /business/*

This wildcard entry will catalog all variations of strings in the business section, so that, for example, and would both be grouped in the wildcard. Wildcards can operate in more complex cases too:

  • /*entertainment

Includes all URLs that contain the word entertainment. Example:

Recognized wildcards:
* - matches zero or more symbols
? - matches any symbol
\* - “*” symbol
\? - “?” symbol

Wildcard entries work for inclusions, exclusions and referral sources alike. For referral sources, be sure to include the protocol as well. (e.g.www., https://)

You can also select Pages where this Experience runs using tags, that allows you to describe pages in more detail and without need of URL matching.
You can learn about Page Tracking and Taging and how to setup the integration code properly on Page Tracking and Taging documentation.

Section fronts: Many business models will allow a section front open for audience viewing, but each article within that section will be metered and protected. Here is how to do that:

Enter in the edit settings for the Pages card:

  • Include URLs: /entertainment/*
  • Exclude URLs: /entertainment/

Initial User Segments

Creating your segments, you have the option to target all users, create a custom segment or target all users who are unmatched in your other segments.

The initial user segment runs off the same rules as your segment users card, detailed in a lower section.

Events and Triggers

Under Events and Triggers, you can drag any of the Events cards to the Canvas:


Under Actions, you can drag any of the Actions cards to the Canvas


Pageview Meter

Meter name: You have the option of naming your meter descriptively. You could name the meter by the Offer you plan to show, for example. You might meter unique pages and segment your audience in your Business Section. On another Experience, you may be segmenting for your Breaking News section. You can name them as such, and you can always change the name at a later date.

Track users across subdomain sites: this is only for publishers who have subdomains, i.e.; and

Expire at: this is the number of pageviews allowed until the pageview meter runs out and the user encounters an action. A user's existing pageview count would not reset to zero if the publisher were to change the “expire at” limit.

Reset after: if you have a dismissible action (such as a video ad view offer in a modal that a user can close) and you want the Offer to show again, once the meter resets the user starts from 0. You can choose between time or pageviews. Say you had the meter expire at 3 pageviews and the meter reset after one week. This would allow a user 3 free pageviews per week until encountering an action.

Meter unique pages only: don't want to count the same page twice against the meter? Flip the switch to green to count a specific page once when the user has already seen that page within the period.

Traffic coming from referral sources is not metered: By turning the dial green you are choosing to not meter the pageviews coming from referred sources. However, you can list exceptions for traffic originating from selected sites. This exception allows you to configure the experience on different levels, for example you can accept to meter traffic in the user meter card but not meter users from certain pages within Facebook such as a specific Facebook group page. Enter in the full URL of the referral source, or use wildcards (placeholders) to save time. For example, when segmenting users coming from Facebook you should use the following wildcards:


Except for traffic coming from these sites: list here the exceptions to your referral sources. If you have the dial on green, but you don't want to meter one of your referral sources, then input that URL in "Add a new URL..." field.

Please note: if a user clears their cookies or loads the page using a “private browsing” or “Incognito window” they will bypass the paywall. To reliably protect high-value pages, it is necessary to store the access data on our servers and check for access on the server side.


Segment Users

This is your user card – who is getting what Experience. This card is arguably the most powerful in your whole deck as it allows you to pull in custom segments and create your own segments.

If you are just starting out with your first Experience, the segment users card is pre-loaded onto your Canvas as the initial segment. Clicking into this card, the first option you have is who to target: All, Custom or Everybody Else. To create your first segment, go with Custom and start digging in.

Source: here, you have the option to reel in external user segments.

This step is optional, though encouraged, as it allows your Actions and Offers to be powered by behavior and statistics. If you are using our Audience Intelligence product and are tracking your traffic, then you can pull Direct and Dedicated segments in here and present them with a different offer than you would present to your one-offs or more casual viewers. Composer is also compatible with segments defined in BlueKai, Cxense, Omniture or Krux.

Account Properties: Login Status: choose the status of the user you want to target:

  1. Logged in
  2. Unregistered / logged out

If a user is logged in, you may want to show a custom JavaScript message, or convert against a low-level value exchange like an ad view. If the user is logged out, you may want to show a different action, such as a registration offer or a paid subscription offer.

Account Properties: has No Access to / Has Access to: in these two fields you can create a segment based on what a user has, or does not have, access to.

This comes in handy when you have multiple Resources on your site(s) and you want to target users with special offers. You could use this to upsell, or to target those who currently do not have access.

Account Properties: Promotions Redeemed: choose to have a custom Experience for those users who have previously redeemed a promotion.

You may want to offer users who have redeemed a promotion the opportunity to convert against another promotion, or you could just send them a thank-you message.

Browsing Properties: Device: target users by the device they are using: desktop, mobile, or tablet. If left unchecked, all devices will be targeted.

This is useful to show custom messaging to users, split testing to see what offers convert the greatest number of users based on behavior by device. Prompt users to download a mobile app, show different value exchanges for tablet users, etc.

Geographic Location: in this field you can select certain geographies to target or ignore. This card is immensely valuable to have localized checkouts (language and currency) and other customization that certain geographies require. Segment by region and country. (See also domain/IP exclusions)

Designated Market Area (DMA): in this field you can target marketing and advertisements to the geographic regions in the United States in which local television viewing is measured by The Nielsen Company. Each DMA is exposed inside the User Segment card with the area name and 3 digit code.

Referred from: this section allows you to segment users by where they are coming from so that you may create a custom experience for them. Is the user coming from a social network? From a search engine? From a sister-site?

Target or ignore referral sources. Enter in the full URL of the referral source, or use wildcards (placeholders) to save time. For example, when segmenting users coming from Facebook you should use the following wildcards:


Ad blockers: create a custom experience for users who have ad blocking software enabled on their browsers. Click the box to target those users; you can also create custom offers and offer templates for those users, such as watching an ad, turning off ad blocking or continuing ad free in exchange for a subscription.

Host IP / Domain: in this section you have the option to segment users by IP address or domain. Choose targeting specific IPs and domains or ignore them – all by flipping the switch () and entering the value. This allows you to target networks and organizations, for example creating site licenses for institutions or companies.

You can enter exact IP address, or CIDR notation of subnets ( e.g. ).

We do not support domain wildcards, so when entering domain name, it should be resolvable to one IP address.

Split Test

Test up to 10 different variants to determine the experiences that convert the greatest number of users.

Composer lets you divide your audience on a percentage basis. From there, you can show different groups of your audience entirely different experiences at different meter limits. Those experiences can manifest themselves as different CSS on pages, different elements on a page, popping up modal boxes or running custom JavaScript.

On each split test variable there is reporting on impressions per variable, reporting on conversion rates and reporting on net revenue. Drag the split test card onto your canvas to start testing.


Show Offer

Display a call to action to purchase a subscription, register to read more articles, view a video for more access, etc. The offer presents your Terms (value exchanges, subscription models) that protect your Resource.

After you have Terms connected to an Offer, you will be able to select what Offer you want to show at the end of each Experience and each segment model.

On the Show Offer card, you have the options to:

  • Select what template to show your Offer in
  • Select the display mode: modal or inline
    • If inline, enter in the container selector modal
  • When a modal offer is chosen, you then can choose whether to show the offer after a certain amount of time on the page, or show the offer after a certain scroll depth

Click this link for more on Offers.

Show Template

Present a template to the user. This is different from Show Offer in that you cannot make a purchase from a template. However, it can include links to offers and means of purchase not supported by Piano VX.

On the Show Template card, you have the options to:

  • Select what template you present
  • Select the display mode: modal or inline
  • When a modal template is chosen, you then can choose whether to show the offer after a certain amount of time on the page, or show the offer after a certain scroll depth

Apply CSS

Change the appearance of your site based on user location in the Experience.

With this option you can create custom on-site messaging and notifications to your users based on a number of features such as geographic location, content type, their interaction with the page, access status, device, purchase history and their behavior, if applicable.

Non-site Action

This is an “empty” action that can be executed in Composer to showcase an action served by a third-party API .

Run JS

Input JavaScript to run when a user hits a particular part of their site journey. Run a third-party checkout, display reminders, create calls to action such as downloading an app, sharing a story or completing a survey.


Tracking checkout events

Track the conversion


Parameter Description
api_token* Application’s API token
tracking_id* Conversion tracking id
term_id* Term ID
term_name* Term name
step_number Checkout step number
amount Conversion amount
currency Conversion currency by ISO 4217 standard
custom_params Custom parameters (any key-value pairs) to save (this value should be a valid JSON object)

Please note: term_id and term_name parameters are your internal product name and product ID for the subscription offer being purchased. When you make this call, we are logging what was purchased — and we’re doing so using the naming convention / IDs that you use internally.

This is the final step of the purchase process, confirming that it was successful. Due to requirement of using api_token in this method, it should only be executed on the server side.

Track other checkout events


Parameter Description
tracking_id* Conversion tracking id
step_number* Checkout step number
step_name* Checkout step name
custom_params Custom parameters (any key-value pairs) to save (this value should be a valid JSON object)

Tracking id

Tracking id for API requests can be obtained with 3 methods:

Within templates, tracking id is available by accessing params.trackingId. As an example, this value can be passed as a parameter to a subscription page:

<a ng-href="{{params.trackingId}}" target="_parent">Subscribe today!</a>

Or it can be used as a hidden value for your form:

<input type="hidden" name="trackingId" ng-value="params.trackingId"/>

Within Run JS card. The code which is executed inside of Run JS card, has access to context.trackingId variable. The value of this variable can be used, for example to pass the tracking id value to the checkout page by generating a link with this trackingId parameter:

location.href = ""+encodeURIComponent(context.trackingId)+'&return='+encodeURIComponent(location.href);

Example of implementation

1. Create a paywall template with a link to your subscription page, using params.trackingId value.

<p> Dear viewer. Your monthly limit of free articles have been expired </p>
<a class="button" ng-href="{{params.trackingId}}&return={{params.url}}" target="_parent"> Subscribe </a>

2. Using composer, create an experience for your paywall, which will result in “Show template” card.

3. On your subscription page, make sure that it’s capturing the tracking_id parameter.

4. Use the tracking_id parameter to execute the conversion tracking on your server after the successful purchase You will also need to add the term_id and term_name to execute the tracking functionality. Please note, that the term_id and term_name used in this instance is sourced from your third-party subscription service provider. In addition, the term_id and term_name used, does not have to match the same term_id and term_name that was created in the Piano Dashboard:

// Login to piano dashboard to obtain the API token
$api_token = "YOUR API TOKEN";
// Is application in sandbox?
$sandbox = true;
$query = http_build_query( array(
  'api_token'     => $api_token,
  // tracking_id obtained from the URL parameter
  'tracking_id'   => $_GET['tracking_id'],
  'term_id'       => 'TM01',
  'term_name'     => 'Premium subscription',
  'amount'        => 3.99,
  'custom_params' => json_encode( array(
     'cstom_param_1' => 300,
     'cstom_param_2' => 'test'
  ) )
) );
$url = ( $sandbox ?
  "" :
$url = $url . "/api/v3/publisher/conversion/log?" . $query;
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
// Execute conversion
$result = curl_exec( $ch );

Composer Integration

How does it work? Products → Composer → Integrate

Clicking Integrate will expose a JavaScript code snippet, take that snippet and place it within the head tags on all the pages of your site. Most of the popular content management systems (CMSs) will have a simple interface that allows you to enter code in one place to have it applied to your entire site.

After you have placed the code in your head tags, you can build Experiences without writing or copying code.

Detailed documentation on Javascript integration steps needed and various advanced topics can be found in Composer JavaScript Integration documentation.

WordPress Integration

In your WordPress admin dashboard, follow these steps to access your site's head tags: Appearance→ Editor→ Header Only use this method for integrating Composer if you do not already have the WordPress VX plugin installed.

Additional Customization

For additional customization and utilization of the Piano platform, such as using tags to specify content, you may need to write additional code. For more on our JavaScript, please see the Composer JavaScript Integration page.