Working with Tracking ID

Overview

Tracking ID associates users in Piano's system with actions those users take in third-party applications. It allows Piano to calculate conversion rates for users who view one of Piano's offer templates and then convert on a term in an outside system. When a user is redirected to a third-party application, you can use the params.trackingId variable to obtain a Tracking ID that Piano generates and passes to you. You're then able to send that Tracking ID back to Piano later in the checkout process using the /publisher/conversion/log endpoint.

By default, we are adding a _ptid tracking parameter into all links in a template. If a user follows the link and gets redirected to another page with a Composer experience running, we use this parameter to link to the previous pageview/execution where the user came from.

The _ptid parameter contains our trackingId which may include the following fields:

• aid

• experienceId

• experienceVersion

• executionId

• moduleId

• operationType

• pageViewId

• visitId

• clientIp

• userAgent

• campaigns

• templateId

• templateVariantId

• offerId

We used these fields when logging checkout conversions. So if you use, for example, a template within an experience, where the user clicks on a link inside this template (with a _ptid parameter) and is redirected to a landing page with another experience, we log conversions on the landing page using the fields from _ptid parameter from the initial Composer execution. So these conversions will be shown under the initial Composer experience (where the user clicked on the link) - i.e. where the conversion originated from.

In case a user goes directly to the page landing page without viewing any other templates/experiences before, he/she will not have the _ptid parameter included in the URL, and the conversion will be linked to the landing page experience. Note, that this behavior only applies to the Composer Conversion reports.

The Subscription log report shows the actual URL where the user finally converted - regardless of any previously executed Experiences or templates.

Using Tracking ID

Three common ways Tracking ID is used by Piano clients:

1. Within templates Tracking ID is available by accessing params.trackingId.

For example, the value can be passed as a parameter to a subscription page:

<a ng-href="http://example.com/checkout?trackingId={{params.trackingId | encodeURIComponent}}" target="_parent">
  Subscribe today!
</a>

When a user clicks that link, the {{params.trackingId}} variable will become a unique string value that you can capture and return to us by executing an API call.

The encodeURIComponent is a custom Angular pipe that uses the native browser encodeURIComponent() function. This function encodes the URL parameters by replacing any character that is considered deprecated with its UTF-8 representation. For example, the trackingId value always contains curly braces {} that are listed in RFC 1738 as unsafe.

Please note, that the ​{{params.trackingId}} variable works only if you run the template from Composer.

If you run the template via JS, the variable will evaluate to an empty string.

You can also prevent the tracking ID from being populated for clicked links as described here.

2. Using tracking ID as a hidden value for your form.

For example:

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

3. Tracking ID can be used within the Run JS card.

The Run JS card has access to the context.trackingId variable (note that this is a different variable than the params.trackingId one used in templates). This variable can be used to pass the Tracking ID value to a checkout page by generating a link with the Tracking ID parameter.

Example Tracking ID implementation

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

<a class="button" ng-href="http://example.com/checkout?tracking_id={{params.trackingId | encodeURIComponent}}&return={{params.url}}" target="_parent"> Please subscribe! </a>

This example includes {{params.url}},, an optional parameter that allows you to capture the URL a user navigated from. This can be useful if you want to return a new subscriber back to the article they were reading just before going through the check-out process.

2. Using Composer, create an experience that will trigger the template you've just created.

3. Make sure that your subscription page is capturing the tracking_id parameter.

This is done by extracting the tracking_id parameter from the link using your preferred method. One way to do this would be to extract the parameter from window.location.href using native JavaScript functions or jQuery. Another way to do this, as in the example at the end of this article, would be on the server side using a function like $_GET['tracking_id'].

4. After a successful purchase you can then use the tracking_id parameter to execute conversion tracking by sending an API request from your server.

You will also need to add the term_id and term_name to execute the tracking functionality. In this instance term_id and term_name are sourced from your third-party subscription service provider. The term_id and term_name used do not have to match a term_id and term_name created within Piano.

Here's an example of what a server-side request with Tracking ID sent to /publisher/conversion/log might look like:

<?php
// 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 ?
  "https://sandbox.tinypass.com" :
  "https://api.piano.io"
);

$url = $url . "/api/v3/publisher/conversion/log?" . $query;

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
// Execute conversion
$result = curl_exec( $ch );

Last updated: June 24, 2026