We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

Subscription Linking: Implementation Checklist

1. Introduction

This implementation checklist guides you through integrating the Linked Term feature into your Piano application. By following these steps, you enable the use of third-party subscription management systems while leveraging Piano's core functionalities, such as Composer's user journey orchestration, advanced segmentation, and data analysis in Piano Analytics. For more general information on Linked Terms, see the Piano Linked Term Documentation.

2. Implementation Checklist

2.1 Create a "Zero" Linked Term

  1. Log in to your Piano Publisher Dashboard.

  2. Navigate to Manage > Terms.

  3. Click on New > Linked Term to create a new Linked Term.

  4. Fill in the term details:

    • Title of term: Provide a name for the Linked Term.

    • Description: Optionally, add a description.

    • External term ID: Enter the ID used in your external system to map this term.

    • External product IDs: Enter the IDs of the external products accessed by users. Separate multiple IDs with a comma.

    • Subscription management URL: Provide the URL where users can manage their subscriptions.

  5. Click Create to finalize the Linked Term.

Notes:

  • This "Zero" Linked Term is used for testing frontend and backend configurations before moving to production.

  • Ensure that the External term ID and External product IDs are correctly set. These IDs are crucial for mapping your external system's terms and products to Piano's resources. Incorrect settings can lead to configuration errors.

  • Piano will automatically create resources corresponding to the external product IDs. Do not manually edit these resources, as it may cause unpredictable behavior in segmentation and access-related features.

2.2 Set Up Piano Offer

  1. Configure your webpage to display the Piano offer using Composer's Show offer action.

  2. Ensure that the offer includes the Linked Term created in step 2.1.

  3. Implement default functions like startCheckout(term.termId) within the offer templates to ensure all necessary data is captured and processed correctly.

Avoid including the checkout URL directly in the template, as this can prevent the linkedTermSelected callback from firing correctly.

2.3 Implement Callback Function

  1. Define your callback function onLinkedTermSelected to handle the linkedTermSelected event when a user selects the Linked Term in the Piano offer. The function should accept the following parameters:

    • session_id: Identifies the user session and is valid for 3 days.

    • linkedTerm: Contains data required to initiate the external checkout.

  2. Add the callback function to the Piano integration script by pushing it to the tp object:

    tp.push(['setLinkedTermSelected', onLinkedTermSelected]);

  3. Use the information from the callback to initiate the external checkout process for the associated external term.

  4. Ensure that the session_id is preserved across any redirects during the checkout process. If users are redirected to a new page, maintain the session_id on the server side if necessary.

  5. Store the session_id securely, as it is required in backend API calls to link frontend interactions with backend events.

  6. Optional Step: To skip the user authentication check before starting the external checkout process (applicable for Identity Linking and Identity Management), add the following line before your Composer experiences are executed:

    tp.push(['setRequestUserAuthForLinkedTerm', false]);

    This will trigger the linkedTermSelected callback immediately without requiring the user to be logged in.

Example Callback Function:

function onLinkedTermSelected(sessionId, linkedTerm) {
    var data = linkedTerm.linkedTermData;
    var externalTermId = data.externalTermId;
    var amount = data.customData.price.amount;
    var currency = data.customData.price.currency;

    // Save the sessionId for backend API calls
    // Example: saveSessionID(sessionId);

    // Initiate external checkout process
    // Redirect the user to your external checkout page with necessary parameters
    window.location.href = 'https://your-checkout-page.com?session_id=' + sessionId + '&term_id=' + externalTermId + '&amount=' + amount + '&currency=' + currency;
}

// Add the callback function to the Piano integration script
tp.push(['setLinkedTermSelected', onLinkedTermSelected]);

Notes:

  • Ensure that the callback function is defined before the Composer experience is triggered.

  • The linkedTerm object provides necessary details about the selected term, including custom data you may have specified.

  • By preserving the session_id, you enable accurate tracking and reporting of user actions, including in Piano Analytics and Composer segmentation.

2.4 Configure Sync API Calls

  1. Set up your backend to send API calls to the following endpoint:

    https://api.piano.io/api/v3/publisher/linkedTerm/event

    Append your Application ID (aid) and API token (api_token) as query parameters. For example:

    https://api.piano.io/api/v3/publisher/linkedTerm/event?aid=YOUR_AID&api_token=YOUR_API_TOKEN

  2. Ensure that your backend communicates every action performed on the external subscription to Piano via these API calls. Actions include:

    • subscription_create: Sent when a user has purchased a subscription.

    • subscription_update: Sent when the state of a subscription changes, usually updating the state from 'Active' to 'Not Active' or vice versa.

    • subscription_renew: Sent when a user’s subscription renews (e.g., monthly, yearly).

    • subscription_upgrade: Sent when a user upgrades to a different term in the payment system, such as monthly to yearly, or basic to premium.

    • subscription_terminate: Sent when a user cancels their subscription.

    It is important to use the correct action to ensure accurate data tracking. Mislabeling actions can lead to data inaccuracies.

  3. Include necessary parameters in your API requests:

    • action: The action taken on the subscription (e.g., "subscription_create").

    • subscription: An object containing details of the subscription.

    • conversion: An object containing details of the conversion (for applicable actions).

    • session_id: The session ID obtained from the callback function.

  4. Ensure that all data types match the API requirements and that the JSON structure follows the specified schema. Refer to the Linked Term Schemas and Examples for detailed information.

  5. Include additional data points within the subscription object to enable specific capabilities:

    • Brand Relationship Segmentation: Include the purchase.trial field with values "Free", "Paid", or "No".

    • Subscription Length Segmentation: Include the period field with values like "1 week", "1 month", "annual", etc.

    • Expiring Subscribers Segmentation: Include the auto_renew field, updating it to false when auto-renew is disabled.

    • Subscription Tenure Segmentation: Ensure the conversion.create_date accurately reflects the subscription start date.

  6. Use valid JWT tokens for the user_token within the subscription object. Ensure users are created in Piano before sending API calls. For Identity Management, the user token can be generated using the /id/api/v1/publisher/token endpoint. For Identity Linking, use the usual JWT token. Please note that the user must already exist in the Piano application.

Example API Call:

POST https://api.piano.io/api/v3/publisher/linkedTerm/event?aid=YOUR_AID&api_token=YOUR_API_TOKEN
Content-Type: application/json

{
  "action": "subscription_create",
  "session_id": "session_abcdef123456",
  "subscription": {
    "subscription_id": "SUB123456789",
    "user_token": "YOUR_JWT_USER_TOKEN",
    "external_term_id": "ext_term_001",
    "state": "Active",
    "valid_to": 1672531199, // UNIX timestamp
    "auto_renew": true,
    "purchase": {
      "trial": "No"
    },
    "period": "monthly",
    "access_custom_data": "{\"additional_field\":\"value\"}",
    "user_custom_fields": {
      "membership_level": "gold",
      "region": "US"
    }
  },
  "conversion": {
    "conversion_id": "CONV123456789",
    "create_date": 1609459200, // UNIX timestamp
    "payment": {
      "amount": 9.99,
      "currency": "USD"
    }
  }
}

Notes:

  • Include the session_id from the callback to link the frontend and backend events, which is essential for accurate reporting and segmentation.

  • Ensure that all required fields are provided and that data types are correct. Refer to the Linked Term Schemas and Examples for detailed field definitions.

  • When sending custom fields in user_custom_fields, ensure all fields are correctly defined in Piano and values are valid. Invalid values can prevent updates to other fields.

  • Use the Linked Term Sync API for managing subscriptions instead of the Piano dashboard UI to prevent synchronization issues.

  • Accurate use of the action types mentioned above is crucial. Mislabeling actions can lead to data inaccuracies. Ensure that the action accurately reflects the event.

  • Note that the subscription_create action is required to train Piano propensity models, such as the Likelihood to Subscribe (LtS) model and the Content Likely to Convert model.

2.5 Test Integration

  1. Use the "Zero" Linked Term to test the entire flow.

  2. Simulate user interactions to verify that:

    • The frontend displays the Piano offer correctly.

    • The linkedTermSelected callback captures the required data.

    • Backend API calls to Piano are correctly formatted and data is accurately transmitted.

    • Subscriptions are correctly created and updated in Piano when users interact with your external system.

  3. Check the Piano Publisher Dashboard to confirm that data appears as expected.

  4. Verify that conversions and events appear correctly in reporting tools, including Composer Insights and standard Subscription Management + Billing reporting (such as the Subscription or Conversion reports).

  5. Test with different scenarios, such as free trials, paid trials, auto-renewal enabled/disabled, to ensure all segmentation capabilities are functioning.

Notes:

  • Identify and resolve any issues early in the integration process through thorough testing.

  • Ensure that the session_id is properly linked across the frontend and backend.

  • Verify that custom fields are correctly captured and available for segmentation in Piano Composer and Piano DMP (if you license DMP).

2.6 Create or Import Linked Terms

  1. After successful testing, proceed to create or import your actual Linked Terms.

  2. You can create Linked Terms:

    • In the Publisher Dashboard.

    • Via Piano API using the publisher/linkedTerm/configuration endpoint.

    • By migrating them within a term catalog using a CSV file.

  3. Ensure that each Linked Term is properly configured with the correct:

    • External term ID

    • External product IDs

    • Subscription management URL

    • Any necessary custom data

  4. If associating existing resources, ensure that the external_id field of the existing resource is correctly filled with the corresponding external_product_ids.

Notes:

  • Incorrect configuration of external IDs can lead to mapping errors between your external system and Piano.

  • Use consistent naming conventions for IDs to avoid confusion.

2.7 Migrate Existing Subscriptions (If Applicable)

  1. If you have existing subscribers that need to be imported into Piano’s Linked Terms, coordinate with your Project Manager (PM).

  2. Your PM can schedule a sandbox import of dummy users and subscriptions for testing purposes.

  3. After successful testing, plan the production import with your PM based on your Go Live timeline.

  4. A delta import can be planned if some records need fixing.

  5. If you prefer to handle the import using APIs, your PM can provide you with the necessary APIs and rate limits.

  6. Use the subscription_import action in your API calls to import subscriptions without affecting segmentation and reporting.

Example Scenario: Importing Existing Subscriptions

Without Using subscription_import:

  • You import 10,000 existing subscriptions using subscription_create.

  • Piano records 10,000 new conversions, falsely indicating a surge in new subscriptions.

  • Segmentation rules might target these users as new subscribers.

  • Your reports and metrics are inflated, leading to inaccurate performance assessments.

Using subscription_import:

  • You import the same 10,000 existing subscriptions using subscription_import.

  • The subscriptions are recognized for access control purposes, allowing users to access content seamlessly.

  • Piano excludes these imports from conversion reports, maintaining accurate tracking of new subscriptions post-integration.

  • Segmentation and personalization strategies remain effective and relevant, targeting only new user interactions.

  • Your reports reflect true performance metrics, enabling informed decision-making.

By using subscription_import, you maintain data integrity, avoid skewing analytics, and ensure that your segmentation strategies are based on accurate, current data.

Notes:

  • Ensure that all users are created in Piano before importing subscriptions, as the Sync API can only process existing users.

  1. Ensure that the Subscription management URL is provided within each Linked Term configuration.

  2. This URL allows end users to manage their subscriptions through your external system.

  3. The functionality is handled automatically; no modification to the My Account templates is required.

Notes:

  • Users will be redirected appropriately from the Piano MyAccount to your external subscription management page.

  • Ensure that your external system can handle the incoming requests and manage subscriptions accordingly.

2.9 Monitor and Update

  1. Continuously monitor the integration to ensure smooth operation.

  2. Implement logging to track events and identify issues promptly.

  3. Update configurations as necessary based on user feedback and system performance.

  4. Keep your internal documentation up to date with any changes made.

  5. Regularly review application settings in both sandbox and production environments to ensure consistency.

Notes:

  • Maintain secure handling of user data, especially JWT tokens and API credentials.

  • Stay informed about any updates to Piano APIs or features that may affect your integration.

3. Additional Guidelines

Follow these best practices to maintain a robust integration:

  • Testing and QA: Regularly test the entire flow after any updates. Use a "Zero" Linked Term or test terms to identify and resolve issues early.

  • Security: Protect user data by securely handling JWT tokens and API credentials. Ensure compliance with data protection regulations.

  • Session ID Handling: Preserve the session_id across redirects during the checkout process to maintain accurate tracking and reporting.

  • Frontend Integration: Implement the onLinkedTermSelected callback function correctly. Avoid including checkout URLs directly in templates, which can prevent callbacks from firing.

  • Backend Synchronization: Use the Linked Terms Sync API for managing subscriptions instead of manual changes in the Piano dashboard UI to prevent synchronization issues.

  • Custom Fields and Data: Ensure all required custom fields are correctly defined and that data structures follow the specified JSON schema. Valid values are crucial for updates.

  • Application Settings: Verify that all necessary application settings, such as the 'External ID Resource' field, are enabled in both sandbox and production environments.

  • User Import: Users must be created or imported into Piano before sending subscription events. Use the publisher/identity/register endpoint to create new users.

  • Support: Reach out to Piano support or your Project Manager for assistance when needed, especially for migration or advanced configurations.

By following this implementation checklist and integrating common issues and data requirements into each step, you will successfully integrate the Linked Term feature into your Piano application. This integration allows seamless use of third-party subscription management systems alongside Piano's powerful tools, enhancing your user experience and providing valuable insights through advanced analytics and segmentation.

Last updated: October 17th 2024

Last updated: