Ad Revenue Insights & Dynamic Paywall: Implementation Checklist

1. Introduction

Ad Revenue Insights (ARI) is a powerful analytics product built on top of Piano Analytics that helps media brands understand and optimize their ad revenue streams by providing granular insights into ad performance across their content. It aggregates data from various ad sources and offers actionable insights to increase ad revenue.

Ad Revenue Insight's primary integration is with Google Ad Manager (GAM) due to its popularity with Piano clients, but Ad Revenue Insights can also integrate additional third-party ad data such as Outbrain and Taboola.

Piano's Dynamic Paywall is an advanced feature that leverages ad data from Ad Revenue Insights and combines it with data from Piano's suite of propensity models, including the Likelihood to Subscribe, Likelihood to Return, and Content Likely to Convert models. The resulting user segmentation allows you to intelligently determine when to present paywalls to visitors, balancing the goals of maximizing subscription and ad revenue.

This guide will walk you through the necessary steps to implement ARI and the Dynamic Paywall, including configuring required scripts, setting up data tracking for ads and subscriptions, and ensuring data quality for accurate insights and optimal paywall performance.

2. ARI Implementation Details

Implementing ARI involves two primary components:

1. Providing Piano with Google Ad Manager (GAM) details and access.

2. Implementing ARI-related tracking scripts on your website.

2.1 Google Ad Manager Access

To collect impression metadata such as line items, ad units, revenue, and other critical ad performance data, Piano requires access to your GAM account via the API.

Steps to Grant Access:

1. Add Piano's Service Account to GAM:
   Add the following service account email to your GAM account to enable Piano to retrieve data via the API:
   cxense-dfp-api@cxense-dmp-252818.iam.gserviceaccount.com
   Instructions on how to add a service account user to Google Ad Manager can be found here: Configuring Google Ad Manager

2. Provide GAM Network Codes:
   Share your GAM network code with Piano. The network code is a unique identifier for your GAM account and is essential for data synchronization. You can find the network code in the URL when logged into GAM:
   https://admanager.google.com/NETWORK_CODE#home

Granting access allows Piano to collect and analyze your ad performance data comprehensively, which is crucial for ARI's analytics and the Dynamic Paywall's optimization processes.

2.2 ARI Script Implementation

For ARI to collect detailed ad impression events, you need to implement Piano's dedicated scripts on your website. As a first step, you will need to implement Composer, as documented here. After doing so, ARI-specific implementation steps are outlined below.

Implementation Steps:

1. Include the Main ARI Script on All Pages:
   Add the ARI script to every page of your website. This lightweight script designed to avoid latency captures ad impression events:
   <script src="https://cdn.cxense.com/ari.js" async=""></script>

2. Script Placement:
   Place the ARI script in the header section of your pages. Importantly, the script should be loaded before the Google Publisher Tag script (gpt.js) to ensure it captures all ad events effectively.
   The ARI script interacts with the googletag object provided by Google Publisher Tags to listen for ad events. Loading it before gpt.js minimizes the risk of missing any ad impressions or other crucial events.

3. Script Functionality:
   Once implemented, the ARI script begins listening to Google Ad Manager events and sends the data to ARI servers for analysis. This process is essential for collecting real-time ad performance data.

4. Optional Prebid Adapter for Header Bidding (If Applicable):
   If you utilize Prebid.js for header bidding and wish to measure this activity within ARI, you can include the Piano DMP adapter when compiling your Prebid.js script. This adapter enables ARI to capture impression prices and other data from header bidding activities. Implementation details can be found in the Prebid Analytics documentation: Prebid Analytics: Piano DMP. Note that implementing the prebid adapter does not impact the performance of the Dynamic Paywall.

Implementing the ARI scripts correctly is critical for accurate data collection, the overall success of ARI's analytics capabilities, and the functioning of the Dynamic Paywall.

2.3 Outbrain Implementation (Optional)

For clients using Outbrain, you need to grant access to the integration@piano.io email to the Outbrain API. This allows Piano to collect widget impression events and daily revenue figures.

Note that Outbrain's API returns daily revenue totals in the timezone set by the client in the Outbrain interface. If the timezone configured in Outbrain is different from the timezone set in Piano, Piano will not be dividing revenue and impressions from the same period.

3. Subscription & Propensity Implementation

3.1 Conversion Tracking

Accurate tracking of subscription conversions and subscription revenue is vital for training Piano's propensity models and the Dynamic Paywall. If you are using Management + Billing's direct integration with your payment processor, then conversion and revenue data will be tracked automatically as part of that integration.

If you prefer to use a third-party system for subscription management, you can choose one of the following methods to send conversions in order to train Piano propensity models (including Likelihood to Subscribe and Content Likely to Convert models):

1. Use Linked Terms: This is the recommended option, consolidating the sending of conversion data for targeting, machine learning, and reporting. Linked Terms enables the widest set of Composer functionality for clients not using Management + Billing to directly manage payments. For more information on Linked Terms implementation, see here.

2. Use Custom Terms: Implement custom terms to send conversion events. By default, Piano considers all custom term conversions as subscription conversions. If you need Piano to include only specific custom terms, contact your account manager or Piano support team for customization. For detailed instructions, refer to Section 7.1.

3. Send Conversion Events via JavaScript: Create products using the /conversion/product/create API and deploy the conversion event script tag on the final "transaction complete" step of your product funnel. For detailed instructions, see Section 7.2.

For clients using Custom Terms or the JavaScript method, additional steps are required to ensure accurate reporting and to power the Dynamic Paywall model. Please refer to the detailed instructions in Section 7.

3.2 Propensity Implementation

Piano's Dynamic Paywall utilizes scores from several propensity models to determine expected ad value and subscription value for each user. To enable the Dynamic Paywall to personalize user experiences effectively, it's essential to implement these associated propensity models and ensure active scoring for them.

The required models include:

• Likelihood to Subscribe (LtS)

• Content Likely to Convert

• Likelihood to Return

To effectively leverage Piano's propensity models, the following implementation prerequisites must be met:

Common Requirements for All Models

• Composer 1X Implementation: All propensity models require the integration of Composer 1X to function properly within your environment. This implementation is part of general Composer implementation, documented here.

• At Least 31 Days of Page View Events: A minimum of 31 days of page view events must be sent to Piano post-implementation to ensure sufficient data for accurate modeling.

Model-Specific Requirements

1. Likelihood to Subscribe (LtS) Model

   • Subscription Conversion Events: At least 100 subscription payment events tracked within the last 31 days are required for the LtS model to produce reliable scores. This threshold is a minimum requirement, and higher conversion volumes will result in higher-quality models.

2. Content Likely to Convert Model

   • Subscription Conversion Events on Articles: The Content Likely to Convert model requires at least 100 subscription conversion events on articles tracked within the last 31 days. This is a minimum requirement, and more conversions will enhance the model's accuracy.

   • Publish Date Data: The publish date of each article must be sent using tp.push. This information is crucial for the model to assess the effectiveness of content in driving conversions.

   • Number of Articles Published: The number of articles published on your site can impact the training time and quality of the model. Sites with a larger volume of content may see faster and more accurate model development, whereas sites with fewer articles are likely to require longer for Piano to train a model.

   • Training Time: Due to the dependencies on both the number of conversion events and the volume of published articles, for sites close to the conversion threshold, it will take longer for Piano to produce a high-quality model due to automated quality controls that prevent low-quality models from reaching production. In some cases, for sites with low number of conversions and low editorial output, it may not be possible to produce a high-quality content model.

3. Likelihood to Return Model

   • No Conversion Data Needed: The Likelihood to Return model does not require subscription or conversion event data. It relies solely on visitation data, which is automatically collected once the Composer 1X implementation is complete.

These models are enabled by default for Piano customers who meet the requirements mentioned above and for whom Piano is able to train a model that meets Piano's performance thresholds.

3.3 Propensity Scoring

After these models are trained, they need to be used in a Composer experience for the models to start scoring in real time. That scoring data is then automatically fed into Piano Analytics through the Subscription Insights integration and used in the Dynamic Paywall solution.

To activate scoring, these models need to be used in a Composer experience. Piano clients will often use these propensity models independently prior to launching the Dynamic Paywall. Piano's Likelihood to Subscribe model, for instance, is heavily used on its own. But if you do not want to use the independent models prior to using the Dynamic Paywall, you can also set up a Composer experience with non-site actions targeting these segments to trigger scoring. Such an experience has no impact on end user experience.

4. Additional Implementation Steps

4.1 Set Section Content Variable

Importance of Content Variables

As described in the Composer implementation guide, content variables are crucial for both targeting users within Composer experiences and for reporting in Subscription Insights.

For Dynamic Paywall, the key content variable is section, which is used when determining expected subscription and ad revenue. This variable tends to be particularly important for ad revenue since ads are often sold based on content verticals.

As mentioned in the general Composer implementation guides, this method can be used to set the content section:

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

4.2 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.

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.

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 with the Dynamic Paywall.

4.3 Confirm Default Currency

Ensure that you have confirmed your default currency (e.g., USD) with Piano. This ensures that all revenue data is accurately represented and currency conversions are correctly handled.

5. Data Checks

Following the activation of ARI, it's imperative to perform thorough checks on the data being collected to ensure accuracy and reliability. This includes ad data, subscription-related data points (conversions and revenue), and content metadata (section and article metadata). Your Piano implementation team will assist with these data checks, verifying that key data points are correctly collected and reported.

Key Considerations:

• Ad Data Consistency:
  While ARI is designed to provide detailed insights into your ad performance, it's important to note that ad data does not need to be perfect for the Dynamic Paywall to function effectively. Piano does not expect an exact match between the ad metrics reported in ARI and those in your Google Ad Manager (GAM) account.

• Ad Data Limitations:
  There are certain ad data formats that ARI does not currently support, including AMP pages, fully native apps, Cost-Per-Click (CPC) ads, and video ads. However, ARI does support hybrid apps using webviews, as they operate similarly to web pages. Piano is always evaluating other data sources to add to ARI based on client needs.

• Purpose of ARI Data:
  ARI is intended primarily for performance monitoring and generating actionable insights, rather than serving as a financial accounting tool for ad data. This performance monitoring is highly useful for applications such as the Dynamic Paywall, as it helps optimize revenue strategies by understanding trends and performance metrics without requiring perfect data alignment with financial records.

• Subscription Data Verification:
  Ensure that subscription conversions and revenue data are accurately captured and recorded. This data is crucial for training Piano's propensity models and for the effective operation of the Dynamic Paywall. Verify that the conversion tracking methods implemented are functioning correctly and that revenue amounts and currencies are properly configured and streaming into Subscription Insights.

• Content Metadata Accuracy:
  Accurate content metadata, including the section and article metadata, is essential for both ad revenue insights and the Dynamic Paywall. Ensure that the content variables, such as section and page_content_type, are correctly set on all pages. Incorrect tagging can lead to misattribution of conversions and revenue, adversely affecting analytics and paywall performance.

Your Piano implementation team is available to assist with these data checks, providing guidance and support to ensure that all necessary data points are accurately captured and any discrepancies are identified and addressed promptly.

6. Timing

Achieving optimal functionality with ARI and the Dynamic Paywall involves several steps and a minimum data collection period.

• Data Collection Period:
  After ARI is fully set up, and both ad and conversion data have passed quality assurance checks, and propensity scores are flowing into Subscription Insights, a minimum of 30 days of data is required in Piano Analytics to train the Dynamic Paywall model effectively. This period allows the model to learn user behaviors, ad performance patterns, and conversion trends.

• Monitoring and Adjustment Phase:
  Once the Dynamic Paywall model is live, it's advisable to monitor its performance closely for one to two weeks. This monitoring period helps you understand revenue distribution, user engagement, and the initial impact of the paywall on your audience in order to set an optimal threshold for paywall targeting. Use this time to evaluate key metrics and gather insights that may inform further adjustments or optimizations to the paywall configuration.

• Ongoing Optimization:
  Beyond the initial monitoring phase, ongoing analysis and adjustments may be warranted to refine the paywall's performance and ensure it continues to meet your revenue and engagement goals.

7. Additional Instructions

7.1 Custom Terms Implementation

For clients using custom terms to send conversion events, Piano considers all custom term conversions as subscription conversions by default. If you need Piano to include only specific custom terms, contact your account manager or Piano support team for customization.

To ensure accurate reporting and to power the Dynamic Paywall model, additional steps are required. You need to log third-party conversions to Piano's API using the /publisher/conversion/log endpoint.

Preferred API Endpoint: /publisher/conversion/log

While only the first four parameters are required to generally use this endpoint, additional parameters are necessary if you are using Subscription Insights and Piano's Dynamic Paywall feature.

An example of a /publisher/conversion/log request:

Request: {
    api_token: "YOUR_API_TOKEN",
    tracking_id: "{jcx}H4sIAAAAAA...",
    term_id: "JKLE673UD",
    term_name: "Standard offer",
    amount: 9.99, 
    currency: "USD",
    custom_params: { "customParam": "value", "sendToCI": true },
    conversion_category: "subscription",
    browser_id: "BROWSER_ID_FROM__pcid_COOKIE"
}

If the request is successful, we respond with a 200 OK status. If there is any issue with the request, we respond with a specific error code, for example in case of an expired TTL. For more information on this endpoint, refer to the dedicated documentation.

7.2 JavaScript Conversion Tracking

For clients opting to send conversion events via JavaScript, you need to create products using the /conversion/product/create API and deploy the conversion event script tag on the final "transaction complete" step of your product funnel.

Implementation Steps:

1. Create Conversion Products: Use the /conversion/product/create API to create products that represent your subscription offerings.

2. Deploy Conversion Event Script: On the final "transaction complete" page of your purchase funnel, implement the conversion event using the following sample code:

   HTML

   <!-- Product Conversion Start -->
   <script>
   cX.CCE.callQueue.push(['sendConversionEvent', {
       'productId': 'cce-conv-test',
       'funnelStep': 'convertProduct'
   }, {
       'callback': function(result) {
           console.log(result.httpStatus); // 200
           console.log(result.response); // {}
       }
   }]);
   </script>
   <!-- Product Conversion End -->
   

For clients using the JavaScript method, additional steps are required to ensure accurate reporting and to power the Dynamic Paywall model. As with Custom Terms, you will also need to log third-party conversions to Piano's API using the /publisher/conversion/log endpoint as described in Section 7.1.

Last updated: July 02, 2026