1. Introduction
Implementing Piano Composer involves integrating Piano's JavaScript into your website, configuring necessary settings, and ensuring that data collection and user experiences function as intended. This guide will walk you through the essential steps, including preparing your environments, installing and configuring the Piano JavaScript, implementing Subscription Insights (formerly known as Composer Insights), and considering additional factors like custom variables and single-page applications.
2. Prepare Your Environments
2.1 Use the Standard Piano JavaScript
Piano recommends using the standard Piano load script for integrating Composer into your website. You can find the Composer load script in the Piano Dashboard under Products → Composer by clicking on the Integrate button in the upper right corner and then clicking Copy to Clipboard. This script simplifies the implementation process and ensures compatibility with Piano's features.
If customization is needed, this should be done in partnership with your Piano implementation team to meet your specific requirements. If you need to edit the script, after clicking the Integrate button click Edit source. For more details on how to edit the load script, see here.
2.2 Add Scripts to Both Staging and Production Websites
Consistency Across Environments:
Add the Piano JavaScript to both your staging (sandbox) and production environments. This ensures that your testing environment closely mirrors production, reducing potential issues during deployment. Both production and staging environments will be created by your Piano implementation team.
Note that certain functionality is intentionally limited in Piano's Sandbox environment. For instance, consumer emails are generated but not sent, webhooks are not automatically fired, and recurring payments do not process. Such limitations are intentional to prevent mistakes, such as real users from receiving confusing or unintended communications during testing. For a full list of differences between Production and Sandbox environments, see here.
If the Sandbox safeguards are undesirable, Piano can create a second production application instead of a sandbox application for a client's staging site to ensure testing closely mirrors the live environment, including all production features and functionalities. Please inform your Piano implementation team if you do not want standard production and sandbox environments.
2.3 Optimize Script Loading (Optional)
Alternative Implementation for Performance:
If you have concerns about script loading performance, you can optimize the way Piano scripts are loaded and executed.
Instead of using the standard Piano load script, you can:
-
Load the
tinypass.min.jslibrary directly in the<head>tag to start loading it as soon as possible. -
Initialize settings and execute Composer in the
<body>tag.
This approach can improve performance by reducing network requests during page load. For detailed instructions and code examples, refer to the How to Optimize Loading and Executions of Piano Scripts documentation.
Note: Ensure you coordinate with your Piano implementation team if you choose to use this optimized approach.
3. Install and Configure the Piano JavaScript
3.1 Place the Piano JavaScript in Your Site
Insert the Script in the Appropriate Location:
Place the Piano JavaScript into the header code of your main document on both your staging and production websites.
3.2 Initialize the tp Object
Initializing tp:
Before any tp.push commands, ensure that the tp object is initialized. Add the following line to your script:
tp = window.tp || [];
Explanation:
This ensures that tp is defined and that tp.push(['command', arguments]); will function correctly.
You'll notice this tp initialization code in many of the code samples used in this guide.
3.3 Use init Callback Functions
Executing Code After Piano Library Loads:
Any Piano-specific functionality you need to execute should be placed inside a Piano init callback function. This ensures that the functionality runs only after the Piano JavaScript library is fully loaded.
Adding an init Callback Function:
tp.push(["init", function() {
// Your Piano-specific code here
}]);
By using the init callback, you can control the sequence in which your code runs. This is particularly useful if you have multiple pieces of code that depend on the Piano library. For example, you might need to check user access before showing an offer.
Multiple Callbacks:
You can create multiple init callbacks and place them in different parts of your page as needed.
Each callback will execute after the tp object is initialized and the Piano library is loaded.
Important Note: Ensure that tp.experience.init() or tp.experience.execute() is called only once per pageview to avoid over-counting pageviews, which can lead to overages and inaccurate analytics data.
3.4 Set Sandbox Mode for Testing
Working in Sandbox Environment:
If you are operating within a Piano Sandbox application (on your staging site), set the Sandbox flag to true:
tp.push(["setSandbox", true]);
This ensures that testing does not interfere with your production data.
No Action Needed in Production:
You do not need to set the Sandbox flag in production. If present, either remove it or set it to false.
3.5 Add External Libraries (If Necessary)
Including External Libraries Before Piano Functionality:
If your Piano functionality depends on external JavaScript libraries, you can add them using the addExternalLibrary command:
tp.push(["addExternalLibrary", "http://your-domain.com/external.js", function() {
// At this point, both Piano and your external library are loaded
// Your functionality here
}]);
This injects the script into the <head> of your website. After the script is loaded, the callback function is executed.
3.6 Enable Debugging
Increasing Verbosity of Debug Messages:
Enabling debug mode can help with troubleshooting during development:
tp.push(["setDebug", true]);
For more tips on debugging, see here.
Remember to Disable Debugging in Production:
Turn off debug mode in your production environment to optimize performance.
3.7 Load the Piano JavaScript Asynchronously
Ensure Non-Blocking Script Loading:
The Piano JavaScript should already be set to load asynchronously in the script examples provided earlier.
The async attribute in the script tag ensures that the script does not block page rendering.
3.8 Set Content Variables
Importance of Content Variables:
Content variables are crucial for both targeting users within Composer experiences and for reporting in Subscription Insights. Setting content variables like section, author, publish time, and tags allows you to target your experiences to the correct content and improves the relevance of content recommendations.
Implementing Content Variables:
Commonly used content variables include the following:
Set Content Section:
tp.push(["setContentSection", "section_name"]);
Use Case: To target or analyze users visiting a specific section of your site. Content section is also required for use of Piano's dynamic paywall solution (part of Ad Revenue Insights), which is described in more detail here.
Set Content Author:
tp.push(["setContentAuthor", "author_name"]);
Use Case: To target or analyze content based on the author.
Set Publish Time:
tp.push(["setContentCreated", "publish_time"]); // Use ISO 8601 format
Example:
tp.push(["setContentCreated", "2023-10-15T08:00:00Z"]);
Use Case: To target or analyze content based on its publication date. This is also important for content recommendations to set minimums and maximums on content that is recommended within a content widget (e.g., for a news widget where content must be no older than 24 hours old).
Set Tags:
tp.push(["setTags", ["tag1", "tag2", "tag3"]]);
Use Case: To target or analyze users based on specific tags (for example, setting paywall rules in relation to a "premium" tag).
Notes on Content Variables:
-
Format for Publish Time: Use ISO 8601 date format.
-
Piano supports various date formats, but ISO 8601 is recommended.
-
Ensure consistency in how you name sections, authors, and tags for accurate targeting and reporting.
For more information on Composer content settings, see here.
3.9 API Interaction On Edge Implementation (Optional)
Most Piano clients choose a traditional client-side Composer setup due to ease of implementation. But Edge Experiences are an additional paid option for Piano clients needing high levels of content security. Edge experiences are processed on the Edge CDN server, providing enhanced security and performance by handling data before it reaches the user's browser.
Edge offers better security as unauthorized users cannot bypass the paywall since the decision-making happens on the server-side. It also provides faster response times due to CDN-based processing. However, there is less data available for segmentation within the Edge experience itself due to the high distribution of data and the focus on latency. However, Edge experiences are intended to be used in concert with client-side experiences, which retain Piano's full suite of segmentation and targeting functionality.
For more detailed information on Edge implementation, see here.
3.10 API Interaction on Server Implementation (Optional)
Like Edge Experiences, API Interaction on Server is an advanced option for clients who require greater control over content access and deeper integration with their server infrastructure. This feature allows you to process Composer experiences directly on your own servers, performing access checks and decision-making before the content reaches the user's browser.
Benefits of API Interaction on Server:
-
Enhanced Security: Since access decisions are made on your servers, unauthorized users cannot bypass paywalls or access restricted content through client-side manipulation.
-
Advanced Segmentation: API Interaction on Server supports full segmentation capabilities, including Propensity and A/B testing, by utilizing comprehensive server-side data.
-
Integration Flexibility: It allows seamless integration with your existing server infrastructure, enabling you to use internal data and business logic for personalization and targeting.
-
No Dependence on Edge Infrastructure: Operates within your server environment without requiring Edge CDN services.
-
Seamless Integration with Client-side experiences: Like Edge Experiences, API Interaction on Server connects server-side decisioning back to Piano client-side experiences, providing the bulletproof content security of server-side with the flexibility of client-side.
Differences from Edge Experiences:
-
Implementation Complexity: API Interaction on Server requires server-side development, whereas Edge Experiences are implemented at the CDN level with less need for server adjustments.
-
Data Availability: API Interaction on Server has access to full segmentation data, including Contextual Segmentation and A/B testing, while Edge Experiences have limitations due to latency considerations.
-
Latency Differences: Edge Experiences benefit from lower latency by leveraging global CDN infrastructure, while API Interaction on Server may introduce latency depending on your server location relative to users.
-
Security Control: Both options enhance security by making access decisions before content delivery, but API Interaction on Server gives you direct control over the process.
While both API Interaction on Server and Edge Experiences offer enhanced security by making server-side decisions, API Interaction on Server provides greater flexibility and segmentation capabilities at the cost of requiring more development resources and potentially increased latency.
For more detailed information on API Interaction on Server implementation, see here.
4. Composer 1x Implementation
4.1 Modify Existing Composer Script (If Necessary)
Using the Standard Piano JavaScript:
If you are using the standard Piano JavaScript as recommended, you typically do not need to modify the Composer script during Composer 1x (C1x) implementation, which enables advanced segmentation in Composer's user segment card, propensity modeling, and content recommendations.
Custom Load Script:
If you have customized the Piano JavaScript with the assistance of your Piano implementation team, your project manager will provide your "Site ID."
Add the following line after the setAid call in your script:
tp.push(["setAid", "YOUR_ACCESS_ID"]);
tp.push(["setCxenseSiteId", "YOUR_SITE_ID"]);
Ensure Asynchronous Script Loading:
Make sure the script is loaded asynchronously to avoid impacting page load times.
4.2 Whitelist the Piano Crawler
Enabling Piano Crawler Access to Your Production Site:
To allow Piano to analyze your content and serve content recommendations, you need to whitelist the Piano crawler.
Note that whitelisting is important even if you do not intend to use Piano's content recommendations because the content crawler's semantic data is also leveraged in other Piano functionality, such as Piano propensity models and interest segments.
Methods to Whitelist:
-
User-Agent Header: Allow access for the
cXensebotuser agent. -
Reverse DNS Lookup: Whitelist domains matching
*.cxensebot.com. -
IP Addresses: Whitelist the following IP addresses:
-
5.9.190.101 -
5.9.190.106 -
5.9.190.107 -
5.9.190.127
-
4.3 Wait for Data Collection
Piano Crawler Parsing:
After whitelisting, and your Piano implementation team enables crawling in the settings of your application, the Piano crawler will start parsing your website.
This process collects data necessary for advanced features like content recommendations and enhanced segmentation.
Health Checks:
Your project manager will schedule health checks to identify any crawling errors or issues.
Addressing Errors:
If errors are found, your project manager will provide steps to resolve them.
5. Implement Subscription Insights
Subscription Insights, built on top of Piano Analytics, provides in-depth analysis of your content performance and user behavior. Proper implementation ensures you can fully leverage these insights for data-driven decision-making.
Note that while Subscription Insights leverages Piano Analytics, it's designed to provide insights specific to Composer experiences. For clients interested in a full Piano Analytics license, which offers more comprehensive analytics capabilities including custom event tracking and a full data model, please contact your Piano account manager. For more information on Subscription Insights, refer to this general Subscription Insights documentation and the Subscription Insights FAQs.
5.1 Gather Required Information
Organization Details (to be discussed with your Piano implementation team):
-
Decide on the name of the new organization.
-
Identify the associated URLs of the sites.
-
Specify the timezone for your site(s).
-
Provide the email and name of the first admin for the organization.
5.2 Currency Configuration
Automatic Currency Conversion:
Decide if you want to enable automatic currency conversion.
Recommendation:
Convert transactions into a single default currency (e.g., USD) for overall revenue monitoring in Subscription Insights. Management + Billing reports, such as Transaction Log and Revenue Recognition, always keep revenue in the original currency since this is required for financial reporting. But nearly all Composer clients choose to have auto-conversion in Subscription Insights reporting because it is useful for overall performance monitoring and analysis.
5.3 Confirm Content Variables Are Set
Importance of Content Variables:
As previously discussed in section 3.8, content variables are crucial for Subscription Insights reporting and for targeting users within Composer. This data is also used in the Subscription Insights data model for reporting, can be leveraged in Composer's pages card for targeting, and can be used as criteria in content recommendation collections, which are described in more detail here.
If all relevant content variables were set when implementing the Composer script, there shouldn't be further action needed when completing the Subscription Insights implementation.
5.4 Verify Content Metadata
Ensuring Accurate Article Attribution
Subscription Insights assigns conversions and revenue to the last article viewed before a conversion based on the content type metadata. To ensure accurate attribution and reliable analytics, it's crucial that the content type metadata (page_content_type) is correctly populated. This metadata is essential for the proper functioning of Piano's Dynamic Paywall solution, which analyzes subscription and ad revenue on articles to optimize targeting and maximize total revenue across both subscriptions and ads.
Incorrect tagging of non-article pages (e.g., subscription pages, homepages) as articles can lead to misattribution of conversions and revenue, adversely affecting functionality like conversion attribution and the dynamic paywall.
On the other hand, while the article name metadata (content_article_name) is important for reporting purposes, it is not critical for core functionality. Accurate article names enhance your analytics by providing clear and identifiable data in reports.
This guide is for Composer clients not using the Piano Analytics SDK to populate page.display events. For clients using the Piano Analytics SDK for page.display, see here for details on capturing content metadata. Your Piano Analytics implementation team will assist you in properly capturing this content data based on your Piano Analytics implementation.
Key Content Metadata Properties and How to Populate Them
Below are the content metadata properties that need to be accurately populated, along with instructions on how to do so. Note the distinction in their importance for functionality versus reporting.
page_content_type
(Displayed as "Page content type" in Piano Analytics properties)
Purpose: Critical for functionality. Identifies the type of content on a page (e.g., article, video, website). Correctly setting this metadata is essential for accurate conversion attribution and the effective operation of the Dynamic Paywall.
How to Populate page_content_type:
Use the Open Graph meta tag to specify the content type.
<meta property="og:type" content="article" />
Guidelines:
-
Set
content="article"for article pages. -
For non-article pages (e.g., homepages, subscription pages), use the appropriate type such as
content="website".
Ensure Accuracy: Do not tag non-article pages as article. Double-check that all pages are correctly tagged to avoid misattribution and functionality issues.
content_article_name
(Displayed as "Article" in Piano Analytics properties)
Purpose: Useful for reporting. Provides the title of the article or content piece. While not critical for functionality, accurate article names improve the clarity and usefulness of your analytics reports.
How to Populate content_article_name:
Subscription Insights parses parameters from the page according to the following priorities:
-
Piano's cXenseParse Title Tag:
<meta name="cXenseParse:title" content="Your Article Title Here" /> -
Open Graph Title Tag:
<meta property="og:title" content="Your Article Title Here" /> -
cXenseParse Description with
og:titleProperty:<meta name="cXenseParse:description" property="og:title" content="Your Article Title Here" /> -
Fallback: HTML Title Tag: If none of the above meta tags are present, the Data Layer will use the
<title>tag:<title>Your Article Title Here</title>
Guidelines:
-
Include at least one of the above meta tags on your article pages.
-
The first valid title found will be used as the
content_article_name. -
Ensure that the title accurately reflects the article's content to enhance reporting accuracy.
5.5 Check Piano Tracking ID (PTID) Tracking (If Necessary)
Role of PTID:
PTID enables accurate tracking of user interactions across your website by connecting conversions and revenue to the original experience and template, thereby enhancing the accuracy of Composer reporting and insights.
Implementing PTID:
The PTID is natively populated and automatically appended to URLs when users interact with links within Piano templates or Composer experiences. However, if you are using external pages or custom buttons outside of these templates, you need to manually add the PTID parameter to the URLs to ensure accurate tracking and conversion attribution.
See here for more details on how to implement PTID in this instance.
5.6 Ensure Correct JavaScript Execution Order
Order of SDK Execution:
If you have a full Piano Analytics license and are integrating the Piano Analytics SDK (piano-analytics.js) along with the tinypass.js SDK and Subscription Insights, it is mandatory to execute tinypass.js before piano-analytics.js on your page. This ensures that all tp.push parameters are properly captured in a Piano Analytics page.display event.
Proper Execution Order:
Load tinypass.js first, then load and initialize piano-analytics.js.
Proper execution order is essential to capture all necessary data for accurate tracking and analytics.
5.7 Implement UTM and Campaign Tracking (Optional)
Track External Campaigns:
To measure the effectiveness of external marketing campaigns, ensure that UTM parameters are properly implemented in your URLs.
Supported UTM Parameters:
Subscription Insights supports the following UTM parameters (leveraging Piano Analytics):
-
utm_source- This parameter indicates the source of the traffic, such as a search engine (e.g., Google), a newsletter, or another website. -
utm_medium- This parameter specifies the medium of the traffic, such as email, CPC (cost per click), or banner. -
utm_campaign- This parameter is used to identify a specific campaign, such as a product launch or a seasonal promotion. -
utm_term- This parameter is used for paid search campaigns to track the specific keyword that led to the visit. -
utm_content- This parameter is used to differentiate similar content or links within the same ad, such as different call-to-action buttons or banners.
Example URL:
https://www.yoursite.com/article?utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale
Proper campaign tracking allows Subscription Insights to break down user visits and conversions by campaign sources. Without UTM or equivalent tracking, campaign attribution will not be available in Subscription Insights.
For Piano Analytics to classify sources as a marketing campaign, it is crucial to include both utm_campaign and utm_medium parameters. Without either of these, the sources will not be recognized as a marketing campaign in Piano Analytics.
5.8 Implement Link Tracking (Optional)
Trigger Custom Events:
When you use the external-event attribute within Piano templates, it tracks custom events such as button clicks. These events are captured and displayed in Subscription Insights, allowing you to monitor and analyze user interactions effectively.
For example, using external-event="offer-button-1" on a button will log clicks on that button, and this data will be viewable in Subscription Insights using the "interaction type" property. This allows for detailed tracking of user clicks within Piano templates. For more details on the external event directive, see here.
5.9 For Clients Using Linked Terms
Ensure Accurate Revenue and Conversion Data:
If you are using Linked Terms, you must send accurate revenue numbers, conversion events, renewal events, and churn events for the data to appear properly in Subscription Insights. Note that, for Linked Terms clients, sending accurate conversion and revenue information is also essential to the successful training of propensity models and the enablement of Piano's dynamic paywall.
For more information on Linked Terms implementation, see here.
5.10 For Composer Clients Using Custom Terms or No Terms
For clients using Custom terms and for Composer clients forgoing terms entirely, for Subscription Insights to have conversion data, this method for sending conversion data back to Composer is required for conversion data to appear in Subscription Insights (it is also needed for conversion data to appear in reports such as the Composer A/B test report).
Note the additional parameters necessary for Subscription Insights and Dynamic Paywall, including browser_id, amount, currency, and conversion_category. The custom_params SendToCI parameter is also required for streaming conversion events to Subscription Insights. If browser_id is not present, Subscription Insights will be unable to combine conversion and revenue data to other valuable data natively ingested into Piano analytics, such as propensity scores and referrer information.
While the necessary data can be sent to Subscription Insights using this method, Linked Terms is the recommended method for sending third-party conversions because the Linked Terms integration consolidates the sending of conversion data. If you instead use custom terms or forgo terms, you will need to send conversion data for reporting using the method listed above as well as sending conversion data for the training of propensity models using a different method, described in more depth here.
Linked Terms avoids this duplicated effort and provides additional functionality as well, such as an expanded set of user segments and richer data within Subscription Insights.
6. Integrating Third-Party Data for Segmentation
Integrating third-party data is a broad topic with multiple options available, including using custom variables, custom fields, Piano DMP bespoke segments, and more. Custom variables are passed to Piano on page execution and allow you to segment in Composer based on any key-value pair. More details on custom variables are provided below since custom variables are most commonly part of a Composer implementation.
Custom fields are part of Identity Management / Identity Linking and allow you to attach information to the user record of specific known users. Depending on the nature of your data and your use case, either custom variables or custom fields may be preferable. For more on custom fields, see this documentation on custom fields within Identity Management. Custom fields are also available to Identity Linking clients.
6.1 Using Custom Variables for Advanced Targeting
Custom Variables allow you to pass additional data to Piano for more granular targeting and segmentation. This data is passed using the same tp.push method as content variables but custom variables, by nature of being custom, can include either content or user data.
Note that custom variables are intended exclusively for targeting and are not sent through to Subscription Insights because custom variables can be anything, making them difficult to include in a standard Subscription Insights data model.
You can still use properties in Subscription Insights such as Experience Name, Template Name, Card Name, and Segment Path to understand the performance of experiences that leverage custom variables.
Set a Custom Variable:
tp.push(["setCustomVariable", "key", "value"]);
Example:
Targeting users based on newsletter subscriptions.
tp.push(["setCustomVariable", "newsletter", "Yes"]);
Arrays of Values:
Example: User Interests
tp.push(["setCustomVariable", "interests", ["sports", "technology", "travel"]]);
Limitations:
-
Maximum of 75 custom variables.
-
Total data size must not exceed 1 KB (uncompressed).
-
Custom Variables are case-sensitive.
-
JSON objects are not supported; only primitives and arrays.
Validating Custom Variables:
Use your browser's console to check if Custom Variables are set correctly by entering:
tp.customVariables
This should display the Custom Variables you've set on the page.
Best Practices:
-
Use consistent naming conventions for keys.
-
Avoid sensitive or personal data that may violate privacy regulations.
-
Keep the number of Custom Variables within the allowed limits.
7. Additional Considerations
7.1 Single-Page Applications (SPAs)
Special Implementation Steps:
SPAs dynamically load content without full page refreshes.
You need to manually initiate Piano functionality each time new content is loaded.
Example Implementation:
Initialize Piano on Page Load:
tp = window.tp || [];
tp.push(["setAid", "YOUR_APPLICATION_ID"]);
tp.push(["setSandbox", true]); // Set to true if in Sandbox
tp.push(["init", function() {
tp.experience.init();
}]);
Execute Piano Experience on Content Change:
// Call this function whenever new content is loaded
tp.experience.execute();
Reset Scroll Depth Tracking (If Needed):
tp.scrollDepth.clearMaxScrolledPosition();
Additional Notes:
Ensure that all necessary Piano variables and content metadata are updated before calling tp.experience.execute().
Important Note: Ensure that tp.experience.init() or tp.experience.execute() is called only once per pageview to avoid over-counting pageviews, which can lead to overages and inaccurate analytics data.
7.2 Ad Blocker Detection
Optionally Implement Ad Blocker Detection:
Piano provides an ad blocker detection script that allows you to target users who have ad blockers enabled.
If you are using the ad blocker detection script, instead of placing the Composer script in the header, as described here, you should instead insert the Piano JavaScript at the end of your </body> tag. This is because advertising.js needs to be loaded prior to the Composer execution (i.e. any other Piano scripts), so that the adblocker cookie is created before any Experience is executed. For details on Piano's ad block detection script, see here.
Implementation Example:
<script>
document.cookie = "__adblocker=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/";
var setNptTechAdblockerCookie = function(adblocker) {
var d = new Date();
d.setTime(d.getTime() + 60 * 5 * 1000);
document.cookie = "__adblocker=" + (adblocker ? "true" : "false") + "; expires=" + d.toUTCString() + "; path=/";
};
var script = document.createElement("script");
script.setAttribute("async", true);
script.setAttribute("src", "//www.npttech.com/advertising.js");
script.setAttribute("onerror", "setNptTechAdblockerCookie(true);");
document.getElementsByTagName("head")[0].appendChild(script);
</script>
Placement:
Add this script as the first element in your <head> tag for maximum effectiveness.
Notes:
-
If you prefer, you can use third-party ad blocker detection scripts and set the
__adblockercookie based on detection.
7.3 Piano ESP Composer Integration
To integrate Piano ESP with Composer, start by creating a new integration in ESP via Setup → Integrations and click Add integration. Name the integration, select the relevant opt-in widgets, and toggle the status to On. Composer clients can then copy the relevant part of the integration code and paste it into the Composer integration code, then click Publish. For detailed instructions with code examples, refer to the full documentation here.
7.4 Piano Consent Management
Implementing Consent Management:
Consider implementing Piano's Consent Management solution to handle client storage and cookies in compliance with privacy regulations. This is particularly important for clients operating in regions with strict privacy laws, such as the EU.
For detailed implementation instructions, refer to Piano's documentation on Consent Management for Client Storage (Cookies).
Last updated: December 5th, 2024