Effective TUNE Links

When a user interacts with a TUNE link (previously measurement URL), they initiate a measurement session and pass on data for attribution in Attribution Analytics. The interaction can then be associated with a subsequent install or in-app event and attributed to the responsible advertising partner.

TUNE links include a few required parameters and a wide variety of optional ones that can be used to add depth to your reporting. By using the right parameters, you can build URLs tailored to your needs that also improve your reporting efficiency.

This article is part of our Product Basics series.

Structure of a TUNE Link

TUNE links are made up of a base domain URL, an action parameter, and other parameters that either contribute to attribution or capture additional information. In all cases, the structure of a TUNE link begins with the same pattern:

These five required components of a TUNE link are automatically generated when you create a TUNE link in Attribution Analytics:

  1. Base Domain URL: This is the measurement domain for the request. Always includes a short, randomly generated alphanumeric string that’s unique to each app as the subdomain. This random string is followed by the tlnk.io/serve top-level domain and path. For example:
    https://1a2b3c.tlnk.io/serve
  2. Action Parameter: The action parameter is used to differentiate between a click-through URL and an impression URL. Valid values for this parameter are:
  3. Partner ID Parameter: To determine which partner is attributed with installs, the initial measurement session needs to identify a partner. In a TUNE link, that’s done by providing your partner’s ID in Attribution Analytics into the publisher_id parameter.
  4. Site and Campaign ID Parameters: TUNE links can be used to capture information about multiple platforms and apps at once. To ensure proper routing and measurement, Attribution Analytics uses site_id and campaign_id parameters to identify the appropriate platform.
  5. Destination ID Parameter: Routing is a key feature of using TUNE links. To redirect users on click, a destination must be provided. Attribution Analytics uses a destination_id parameter to describe the destination URL. Note that although TUNE links often use deep link URLs, they are not required.

Important: The exact parameters used and number of parameters often depend on the app’s operating system. For example, TUNE links which measure multiple platforms contain multiple campaign ID and destination ID parameters.

Unique Identifier Parameters (Highly Recommended)

While technically not required, we highly recommend including unique identifiers in your TUNE links to ensure 1:1 attribution with 100% accuracy. When providing the value for the parameters below, you’ll need to either provide a hard-coded value or a macro { } supported by your advertising network of choice:

  • &ios_ifa=Value – Raw iOS IFA
  • &ios_ifa_md5=Value – MD5 Hash of the IFA
  • &ios_ifa_sha1=Value – SHA1 Hash of the IFA
  • &google_aid=Value – Google Advertising ID
  • &google_aid_md5=Value – Google Advertising ID MD5 hash
  • &google_aid_sha1=Value – Google Advertising ID SHA1 hash
  • &platform_aid=Value – Generic advertising ID, like Amazon’s Fire Advertising ID
  • &windows_aid=Value – Windows Advertising ID
  • &windows_aid_md5=Value – Windows Advertising ID MD5 hash
  • &windows_aid_sha1=Value – Windows Advertising ID SHA1 hash
  • &user_id=Value – Custom ID assigned to user by the app. Useful primarily for re-engagement campaigns
  • &tpid=Value – Persistent cross-application unique device identifier that TRUSTe has created as a privacy-safe alternative to the deprecated UDID. Not in common usage.
  • &unid=Value – UNID/Unknown Identifier can be used when the type of identifier is unknown, and we will attempt to match to all identifiers and hashes. It is not recommended to use this if you are able to specify the type of identifier.

Like the required parameters, TUNE links which measure multiple platforms often contain multiple unique identifier parameters. Here’s an example of a TUNE link that contains both the ios_ifa parameter and the google_aid parameter:

https://1a2b3c.tlnk.io/serve?action=click&campaign_id_android=14341&campaign_id_ios=13431&destination_id_android=12321&destination_id_ios=15151&publisher_id=1001&site_id_android=13131&site_id_ios=17671&ios_ifa={IOS_IFA}&google_aid={GOOGLE_AID}

Other Optional Parameters

Campaign Optimization Parameters

“Campaigns” are a management layer in Attribution Analytics between your app and your advertising partners that helps you manage multiple advertising relationships. You do NOT set up campaigns for specific partners, or specific traffic sources for a partner in Attribution Analytics. While it may seem like a good idea to create a unique campaign for each partner, this method becomes unmanageable when you reach a scale of hundreds or thousands of campaigns.

Instead, we encourage you to think of your individual campaigns with your partners as sub-campaigns within Attribution Analytics. So instead of creating a new campaign, use the my_campaign parameter in the TUNE link. The same is true when you want to segment your reporting by ad (my_ad), adgroup (my_adgroup), or site (my_site).

As advertisers and their partners have different data and reporting needs, Attribution Analytics provides similar sub parameters for both advertisers and partners (as seen in the graphic below) to be included in TUNE link. Advertisers have access to both their own optimization parameters and their partners’ sub parameters, while Partners only have access to their own sub parameters. Sub parameters are available in the Actuals, Cohort, and Log reports to analyze and compare performance:

Advertiser Campaign Optimization Sub Parameters

Advertisers can use the following sub parameters separately and independently from the partner sub parameters:

  • my_publisher – Name or ID of the advertiser’s partner.
  • my_site – Name or ID of the advertiser site or app.
  • my_campaign – Name or ID of the campaign.
  • my_adgroup – Name or ID of the adgroup.
  • my_ad – Name or ID of the ad.
  • my_keyword – Name or ID of the keyword which is specifically relevant to search campaigns (like the Google AdWords integration).

Use these parameters based on how the specific advertiser system is organized. Not all advertisers provide data for all of the above optimization parameters.

 

Partner Campaign Optimization Sub Parameters

Partners can use the following sub parameters:

  • sub_publisher – This value is the name or ID of the partner’s publisher.
  • sub_site – This value is the name or ID of the partner site or app.
  • sub_campaign – This value is the name or ID of the campaign that you’re advertising with the partner.
  • sub_adgroup – This value is the name or ID of the adgroup that you’re advertising with the partner.
  • sub_ad – This value is the name or ID of an ad that you’re advertising with the partner.
  • sub_keyword – Name or ID of the keyword which is specifically relevant to search campaigns (like the Google AdWords integration).

Use these parameters based on how the specific partner system is organized. Not all partners provide data for all of the above optimization parameters.

Note: These parameters are intended for campaign optimization purposes only. If you send a new/unique value with every request (NOT advised), then Attribution Analytics will ignore such parameters.

my_publisher / sub_publisher
Generally, only ad networks provide sub_publisher information because they are a mediation agency connecting multiple partners (publishers) to advertisers. Some ad networks pass the names or IDs of the partners on their network, allowing you to analyze and optimize the performance per partner. In most cases, an ad network must pass the name or ID of their partner dynamically, so you need to ask specifically about this capability. If you advertise with a partner who has a blind network, then they cannot pass partner information (sub_publisher). Typically, a direct partner relationship (non-ad network partner) does not have sub publishers.

For example, an ad network monetizes traffic from the Internet radio service Pandora. So the publisher_id sub parameter is associated with the publisher_id parameter created in Attribution Analytics. Therefore, the sub_publisher parameter in this example equals Pandora, as shown in the following TUNE link examples:

  • Advertiser Example:
    https://12345.tlnk.io/serve?action=click&publisher_id=100&site_id=1000&my_publisher=Pandora
  • Partner Example:
    https://12345.tlnk.io/serve?action=click&publisher_id=100&site_id=1000&sub_publisher=Pandora

my_site / sub_site
If you’re advertising on the mobile web, then the sub_site parameter identifies the web site or property that displays the ad (apps are also classified as “sites”). If you work with a large video game partner and you advertise in several of their apps, then set the sub_site parameter to the name or ID of each app. For a specific ad buy in a app for a partner, you can optionally hardcode the sub_site value instead of generating it dynamically. Ad networks may also pass sub_site information, but they must pass it dynamically because it is not typical for ad networks to do site-specific buys.

For example, when advertising your app for a game studio with multiple apps, the sub_site value is set dynamically with the app name, as shown in the following TUNE link examples:

  • Advertiser example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&my_site={sub_site}
  • Partner example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub_site={sub_site}

my_campaign / sub_campaign
A campaign defines the advertising plan for your app and generally includes a name, destination URL (landing page), cost/bids, adgroups, and ads for the campaign. Most ad networks and partners do not pass the campaign name or IDs dynamically, so you should manually hardcode the name of your campaign in your TUNE link (and the name or IDs of your adgroups, depending on the partner).

For example, if you run two campaigns with the same partner (one incentivized and one not), then set the sub_campaign value input name of “Incentivized” to differentiate the campaigns:

  • Advertiser example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&my_campaign=Incentivized-US
  • Partner example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub_campaign=Incentivized-US

my_adgroup / sub_adgroup

Partners who use adgroups can dynamically specify an adgroup value in their TUNE link. Partners who do not use adgroups typically provide two-layer management with campaigns and ads in each campaign. When there is no adgroup, the sub_adgroup parameter is not a valid sub parameter for measurement.

For example, if you create an adgroup for your 728×90 banner ads, then your TUNE link appears similar to the following examples:

  • Advertiser example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&my_adgroup=Banner728x90
  • Partner example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub_adgroup=Banner728x90

my_ad / sub_ad

By using the sub_ad parameter, you can pass in the name or ID of the specific ad that you configured with the partner. Typically, you hard-code this value with the name or ID of each ad. If you’re running five different ads, then you use a different hard-coded value for each ad.

For example, in the 728×90 banner adgroup, if you have a blue banner named “AdwithBlue“, then your TUNE link appears similar to the following examples:

  • Advertiser example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&my_adgroup=Banner728x90&my_ad=AdwithBlue
  • “my_ad” as a numerical ID:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&my_adgroup=Banner728x90&my_ad=101
  • Partner example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub_adgroup=Banner728x90&sub_ad=AdwithBlue
  • sub_ad” as a numerical ID:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub_adgroup=Banner728x90&sub_ad=10

my_keyword / sub_keyword

When using the sub_keyword parameter, you can pass in the keyword name or ID relevant for search campaigns (like the Google AdWords integration). For example:

  • Advertiser example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&my_keyword=MyKeyword
  • Partner example:
    https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub_keyword=PartnerKeyword

Additional Parameters for Reconciliation

Attribution Analytics also supports five additional sub parameters that are available in the Logs and Postback URL reports, and typically store unique information for partners, but are not available in the performance reports for aggregate reporting because they are not standardized for cross-channel analysis.

These additional parameters are:

  • sub1 – String of additional information specified by partner
  • sub2 – String of additional information specified by partner
  • sub3 – String of additional information specified by partner
  • sub4 – String of additional information specified by partner
  • sub5 – String of additional information specified by partner

The following URL example shows a TUNE link that includes the “sub1” parameter.

https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub1=12345678900001

The following URL example shows a TUNE link that includes both sub1 and sub2 parameters.

https://12345.tlnk.io/serve?action=click&publisher_id=200&site_id=1000&sub1=12345678900001&sub2=98765

You can set one to all five additional sub parameters as needed. While the optimization sub parameters above (like my_campaign and sub_campaign) can accept values up to 255 characters, these parameters support values up to 500 characters.

 

Reference ID Parameter

The ref_id parameter is reserved for the specific reference ID from the partner system (500 characters max). It’s similar to the “sub1” through “sub5” parameters, and is sometimes used for a publisher transaction ID, click ID, ad ID, or tracking ID.

  • ref_id – Reference ID specified by the partner to reconcile with their own third-party system

To learn more about using the reference ID, read our article that answers What’s Reference ID Used For?.

 

Bridge Page Routing

TUNE links can optionally always route users to a bridge page using the parameters below. This solves the issue of iOS Universal Links or Android App Links sometimes failing to redirect properly due to being wrapped or shortened. In most cases, we recommend using the parameter that captures all mobile users:

  • fbp=1 – Force bridge page routing for all mobile users

If you want to only force the bridge page for certain platforms, then you can include the bridge page parameter for the individual platforms instead:

  • fbp_ios=1 – Force bridge page routing for iOS device users
  • fbp_fire=1 – Force bridge page routing for Amazon Fire device users
  • fbp_android=1 – Force bridge page routing for Android device users

 

Using Country Code/Device IP

If a partner has a unique integration with Attribution Analytics and is measuring clicks server-side, then all clicks from these partners (and by extension, all installs attributed to those clicks) appear to come from the geographic location of their servers. To resolve this issue, pass into Attribution Analytics either the 2-character ISO country code or the device IP on click so that Attribution Analytics can attribute installs to their proper geo-location of origin.

  • country_code – Two-character & three-character ISO country code where the click originated.
  • device_ip – IP address of the device collected on click.

 

Passing Cost Data

You can pass in cost data dynamically through your TUNE links. This functionality is explained in detail in our Partner Center documentation about Providing Cost Data, and is based on the following parameters:

  • cost – Amount of cost formatted as float. Must be in USD.
  • cost_model – One of the following cost models:
    • cpv – Cost per View (Impression)
    • cpm – Cost per 1000 Impressions
    • cpc – Cost per Click
    • cpi – Cost per Install
    • cpa – Cost per Action
      • If “cpa” is used as the cost model, one of the following additional parameters must be included to ensure the cost is applied to the correct in-app event.
        • cost_target_event_type – The predefined event type (e.g. “registration”) or the exact name of the site_event.
        • cost_target_event_id – The ID of a site event.
    • cpo – Cost per Open

 

Cross-Device Identifiers

  • user_email – User email parameter is the email address of the user specified by you.
  • user_id – User ID generated by app developers (advertisers) is the same ID of the user in their system. The user_id only works with cross-promo internal campaigns because third-party advertising partners cannot access or replicate this value (as they can with the other Android or iOS identifiers mentioned previously).
  • username – Username parameter is the username value of the user specified by you.
  • fb_user_id – User ID assigned by Facebook. This ID is unique to each app and cannot be used across different apps.
  • twitter_user_id – User ID assigned by Twitter. Typically, this ID can be replaced by the screen_name for the Twitter user, and vice versa.
  • google_user_id – A unique, persistent, and non-personally identifiable ID string representing a Google user.

 

Offer ID Parameter (Legacy)

The outdated offer_id parameter was previously used to identify the Attribution Analytics campaign associated with a link. When this parameter was omitted from the TUNE link, Attribution Analytics assumed the value of the default campaign.

Note: This legacy parameter has been replaced by the campaign_id parameter.

1 Comment

Leave a reply