Documentation/Measurement/Measurement URLs

Best Practices for Measurement URLs

Lucas Brown
posted this on December 04, 2012 22:25

A user interacting with a measurement URL, either by viewing or clicking, is the primary mechanism for initiating a measurement session in MobileAppTracking™ (MAT). The interaction is then associated with a subsequent install (or in-app event) and is attributed to the advertising partner responsible for influencing the user to install the mobile app (or perform an in-app event).

The MAT measurement URL is an elegant solution for pulling a large amount of data into MAT. The measurement URL includes several required parameters and a wide variety of optional ones that can be used to add additional color and depth to your reporting. By using the right parameters and adhering to our Best Practices you can build URLs tailored to your needs and customize your reporting.

 

The Base MAT Measurement URL

The base MAT measurement URL is made up of three main components all of which are required:

1. Base Domain URL (Required)

There are a range of base domain names (such as api-02 and api-03) and we periodically rotate in new ones. The base URL always includes the MAT Partner ID for whom the URL is being created.

http://MAT_PARTNER_ID.api-02.com/serve

 

2. Action Parameter (Required)

Required; Used to differentiate a click-through URL vs an impression URL. Valid values are:

3. App and Campaign Parameters (Required)

  • &publisher_id=MAT_PUBLISHER_ID - identifies the network partner
  • &site_id=MAT_APP_ID - identifies the App that the link is for
  • &offer_id=MAT_CAMPAIGN_ID - identifies the campaign that the link is associated with

4. Unique Device Identifiers (Not required but recommended)

While not required, we highly recommend including Unique Device Identifiers in the Base MAT Measurement URL as it ensures 1:1 attribution with 100% accuracy. Keep in mind that 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
  • &device_id=Value - EMEI, only available for Android devices.
  • &device_id_md5=Value
  • &device_id_sha1=Value
  • &device_id_sha256=Value
  • &android_id/&os_id=Value - Raw Android ID or Windows Hardware ID
  • &android_id_md5/&os_id_md5=Value - Android ID or Windows Hardware ID MD5 hash
  • &android_id_sha1&os_id_sha1=Value - Android ID or Windows Hardware ID SHA1 hash
  • &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.
  • &mac_address=Value - Deprecated
  • &mac_address_md5=Value - Deprecated
  • &mac_address_sha1=Value - Deprecated
  • &odin=Value - Deprecated
Partner_Guide_-_Measurement_URLs_-_New_Page.png

Campaign Optimization Parameters

Campaigns are a management layer in MAT between your mobile app and your advertising partners. A campaign in MAT helps you manage multiple advertising relationships. You do not set up campaigns for specific partners, or specific traffic sources for a partner within MAT. While it may seem like a good idea to create a unique campaign for each partner in MAT, 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 MAT itself. So instead of creating a new campaign, use the "my_campaign" parameter in the measurement URL. The same is true when you want to segment your reporting by ads ("my-ads"), adgroups ("my_adgroups"), sites ("my_site"), etc. The following sections explain the sub_parameters available to you for organizing your mobile app marketing reports.

As advertisers and their partners have different data and reporting needs, MAT provides similar sub parameters for both advertisers and partners (as seen in the graphic below) to be included in measurement URLs. Advertisers have access to both their sub 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, making it easy to analyze and compare performance.

Best_Practices_for_Tracking_Links_2_URL_Params.png

 

Partner Campaign Optimization Sub Parameters

Partners can use the following six campaign sub parameters.

  • sub_publisher - Value of "sub_publisher" passed into the measurement URL on click. This value is the name or ID of the partner’s publisher.
  • sub_site - Value of "sub_site" passed into the measurement URL on click. This value is the name or ID of the partner site or mobile app.
  • sub_campaign - Value of "sub_campaign" passed into the measurement URL on click. This value is the name or ID of the campaign that you're advertising with the partner.
  • sub_adgroup - Value of "sub_adgroup" passed into the measurement URL on click. This value is the name or ID of the adgroup that you're advertising with the partner.
  • sub_ad - Value of "sub_ad" passed into the measurement URL on click. This value is the name or ID of an ad that you're advertising with the partner.
  • sub_keyword - Value of "publisher_sub_keyword" passed into the measurement URL on click. Name or ID of the keyword which is specifically relevant for Google AdWords integration (and other search campaigns).

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

 

Advertiser Campaign Optimization Sub Parameters

Advertisers can use the following six sub parameters separately and independently from the partner sub parameters. These new advertiser parameters resolve the issue of clients setting a different value than what the partner sets. Now the clients (advertisers) have their own second set of parameters to define.

  • my_partner - Value of "my_publisher" passed into the measurement URL on click. Name or ID of the advertiser's partner.
  • advertiser_sub_site - Value of "my_site" passed into the measurement URL on click. Name or ID of the advertiser site or mobile app.
  • advertiser_sub_campaign - Value of "my_campaign" passed into the measurement URL on click. Name or ID of the campaign.
  • advertiser_sub_adgroup - Value of "my_adgroup" passed into the measurement  URL on click. Name or ID of the adgroup.
  • advertiser_sub_ad - Value of "my_ad" passed into the measurement URL on click. Name or ID of the ad.
  • advertiser_sub_keyword - Value of "my_keyword" passed into the measurement URL on click. Name or ID of the keyword which is specifically relevant for Google AdWords integration (and other search campaigns).

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

 

sub_publisher / my_partner

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 MAT. Therefore, the "sub_publisher" parameter in this example equals Pandora, as shown in the following measurement URL examples.

 

sub_site / my_site

If you’re advertising on the mobile web, then the "sub_site" parameter identifies the web site or property that displays the ad (mobile apps are also classified as “sites”). If you work with a large video game partner and you advertise in several of their mobile apps, then set the "sub_site" parameter to the name or ID of each mobile app. For a specific ad buy in a mobile 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 measurement URL examples:

 

sub_campaign / my_campaign

A campaign defines the advertising plan for your mobile app and generally includes a name, destination URL (landing page), cost / bids, adgroups, and ads for the campaign. By default, 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 measurement URL (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, as shown in the following measurement URL examples:

 

sub_adgroup / my_adgroup

Partners who use adgroups can dynamically specify an adgroup value in their measurement URL. 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 728x90 banner ads, then your measurement URL appears similar to the following measurement URL examples:

 

sub_ad / my_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 hardcode 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 728x90 banner adgroup, if you have a blue banner named "AdwithBlue", then your measurement URL appears similar to the following measurement URL examples:

 

sub_keyword / my_keyword

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

 

Additional Parameters for Reconciliation

MAT also supports five additional sub parameters that are available in the Log 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 measurement URL that includes the "sub1" parameter.

http://hastrk2.com/serve?action=click&publisher_id=200&site_id=1000&sub1=12345678900001

 

The following URL example shows a measurement URL that includes both "sub1" and "sub2" parameters.

http://hastrk2.com/serve?action=click&publisher_id=200&site_id=1000&sub1=12345678900001&sub2=98765

 

You can set one or all five additional parameters as needed. While the optimization sub parameters support string values of up to 100 characters long, these additional sub parameters support up to 500-character values.

 

Reference ID Parameter

The reference ID is an additional parameter (similar to "sub1" through "sub5") reserved for the specific reference ID from the partner system (also known as a publisher transaction ID, click ID, ad ID, or tracking ID). To learn more about using the reference ID, please read What is Reference ID Used For?

 

Using Country Code/Device IP

If a partner has a unique integration with MAT 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 MAT either the 2-character ISO country code or the device IP on click so that MAT 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 now pass in Cost data dynamically through your measurement URLs.  This functionality is based on the cost and cost_model parameters and is explained in detail on our doc about providing cost data.