Measuring Other Custom Events

TUNE has 17 pre-defined app events. These pre-defined events make the process more streamlined to share data with your advertising partners. If you want to measure a custom event that doesn’t align with a pre-defined event you can specifically set an event to use either by its ID created by Attribution Analytics (site_event_id) or a reference string provided by you (site_event_name).

measuring_custom_events

For example, to define a custom event (not a standard, predefined event in Attribution Analytics), use the following format:

action=conversion&site_event_name=

or

action=conversion&site_event_id=

To use an Event ID, you need to first create the event in the platform and then use the corresponding ID that MAT creates for the event. The event type for these events will be “event” but can be set in Attribution Analytics by editing the event to a type of one of the pre-defined event types.

As an alternative and more streamlined manner, the Measurement API allows you to specify the event name dynamically. This eliminates the need to create the event in the Attribution Analytics platform first. You can dynamically insert a value for the event name. If the site_event_name does not exist, a new event is automatically created in the platform.

The site_event_name value sent to the Measurement API is lower-cased and non-alphanumeric characters removed. The value is then stored with the event as both the “reference” (ref) value and the "name" value with the URL encoding removed.

The name can then be edited in the Attribution Analytics platform and will display in reports accordingly without causing measurement to break.

measure_custom_events_events_name

Base URL

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve

YOUR_ADVERTISER_ID should be replaced with your advertiser ID defined by Attribution Analytics.

Required Parameters

  • action=conversion
  • advertiser_id – ID of your advertiser defined by Attribution Analytics.
  • one of the following application identifiers:
    • site_id – ID of the mobile app defined by Attribution Analytics.
    • package_name – Package name for Android or Bundle ID for iOS.
  • sdk=server
  • response_format=json – Notifies the Attribution Analytics platform that server-side attribution is being used and returns a server-friendly json response.

You will then need to include the site_event_name or site_event_id value:

  • site_event_name – Name or string that you reference the event by.

OR

  • site_event_id – ID of the event defined by Attribution Analytics.

Required Identifier(s)

First it’s required to include your own user ID value that you use to identify the user in your system. This value should not be a device or advertising identifier, including any listed for Android, iOS or Windows. This value needs to be the value you’ve given the user in your own system and is used for de-duplication. If the user_id is 1234 and then you set user_id to 5678 for the same user, a new install and user will be created.

  • user_id – Unique user ID of user defined by advertiser. Example value: 10000000001

Second, after specifying your user_id, then you’ll need to specify as many advertising identifiers for attribution. Based on the identifiers you’ve implemented for measure sessions, you’ll want to include the same identifiers for any event especially if your marketing team is planning on doing re-marketing / re-targeting campaigns.

Android:

  • google_aid – The Google AID formatted as uppercase with hyphens. AAAAAA-BBBB-CCCC-11111-2222222222222
  • google_ad_tracking_disabled – If the google_aid parameter is going to be used, then google_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.

iOS:

  • ios_ifa – Apple’s new Advertiser Identifier with iOS 6.0+. Also, referred to as IFA or IDFA.
  • ios_ad_tracking_disabled – If the ios_ifa parameter is going to be used, then ios_ad_tracking_disabled parameter must be specified to indicate whether the user has limited ad with 1 being limited.
  • ios_ifv – Apple’s new Vendor Identifier with iOS 6.0+. Also, referred to as IFV or IDFV.

Windows:

  • windows_aid – The Windows advertising identifier (AID) is a unique, user and device-specific, and resettable ID for advertising represented as an alphanumeric string formatted as upper case without colons (for example, “AAAAAABBBBCCCC111122222222222”). When the advertising ID feature is disabled, this value is an empty string.

It’s also recommended to set your own user id value or user value. These values can also be used for cross-device attribution:

  • user_id – * already a required identifier parameter
  • user_email – The email of the user defined by the advertiser. Example value: tom@hotmail.com
  • user_name – The username of the user defined by the advertiser. Example value: tom12345

For information about handling personally identifiable information (PII) and other sensitive data, please visit Handling User Information.

These recommended parameters allow us to provide more granular insight on the user’s and their devices. This data can then be used to segment and filter on in your reporting.

  • device_ip – IP address of the user device recorded on conversion. You can find the device IP in the header of the request that you receive from the user device.
  • device_brand – Brand or maker of the user device (such as “Apple” or “Samsung”). Learn how to collect Device Brand in-app.
  • device_model – Model of the user device recorded on conversion (such as “iPhone5,2″ or “GT-i9300″). Learn how to collect Device Model in-app.
  • os_version – Version of the operating system (such as iOS or Android) on the user device . Learn how to collect OS Version in-app.
  • device_carrier – Carrier of the device if supports cellular like AT&T.
  • language – Language of the device from local settings.
  • country_code – The ISO ALPHA-2 or ISO ALPHA-3 value of the country. For a complete list of ISO-compliant country codes, please visit Country Codes.

Optional Reconciliation Parameters

  • created – Value as UNIX timestamp. If created is not set, current date time will be used. The created timestamp must be within 30 days prior and no more than 1 day in the future else we will use current timestamp.
  • advertiser_ref_id – Reference ID specified by advertiser to reconcile with their own or third-party system.
  • attribute_sub1 – String custom event attribute for your optional use.
  • attribute_sub2 – String custom event attribute for your optional use.
  • attribute_sub3 – String custom event attribute for your optional use.
  • attribute_sub4 – String custom event attribute for your optional use.
  • attribute_sub5 – String custom event attribute for your optional use.
  • currency_code – 3 letter code for revenue using ISO 4217 currency codes.
  • content_id – ID (SKU) of the content or product.
  • content_type – Category that the content is in.
  • site_event_items – Array of items the event. Fields for each item defined below.

The items in the json array for site_event_items field can include the fields below. Only the “name” field is required and all others are optional but recommended when applicable.

  • name – Name or ID of the content or product. SKU. Required.
  • unit price – Value (revenue) of a single item.
  • quantity – Number of the units per item.
  • value – Total value of items. Unit price x quantity
  • attribute_sub1 – String custom item attribute for your optional use.
  • attribute_sub2 – String custom item attribute for your optional use.
  • attribute_sub3 – String custom item attribute for your optional use.
  • attribute_sub4 – String custom item attribute for your optional use.
  • attribute_sub5 – String custom item attribute for your optional use.

To build a payload for the site_event_items parameter, you would need to create a json array with the above format. You can have multiple items by defining a new sub array.

Here’s an example where the items of an event include apples and oranges. The apples has name, quantity, unit_price and value defined. The oranges only has name, quantity and revenue.

[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

If quantity and value are only defined, then unit_price will be determined with value divided by quantity. If unit price and quantity are only defined, then value will be determined by multiple unit price by quantity.

Then you would append the above on to the site_event_items parameter.

&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]

Required HTTP Headers for Authentication

All requests for measure session must include Authentication Method for SDK-less use of Measurement API in order to validate the authenticity of the request as your own.

The authentication method requires a public key (Consumer Key) and signature seeded with a private key. These two keys are associated to a single user.

  • Private Key – This is the Private key that will be used to generate the signature on both the client and server but will not be included in the request.
  • Consumer Key – This is the public key that will be included with each request so the Private Key used to create the signature can be identified.

A Signature is then be generated by hashing the Private Key with URL parameters.

The Consumer Key, Signature and timestamp values need to included need to be included as HTTP headers in the request. With Curl in PHP they would be set with curl_setopt.

Accordingly, these three values need to be set in the HTTP header of each request.

  • mat-consumer-key: ‘consumer key’
  • mat-signature: ‘signature’
  • mat-timestamp: ‘timestamp’

Example Measure Custom Event URL for iOS App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=conversion&site_event_name=eventx&advertiser_id=877&sdk=server&site_id=1234&ios_ifa=AAAAAA-BBBB-CCCC-11111-2222222222222&ios_ad_tracking_disabled=0&ios_ifv=ZZZZZZ-BBBB-CCCC-11111-2222222222222&user_id=10000000001&device_ip=123.123.123.123&device_brand=Apple&device_model=iPhone5,2&device_carrier=Verizon&country_code=US&currency_code=USD&content_id=abc123&content_type=shoes&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json

Example Measure Custom Event URL for Android App

https://YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=conversion&site_event_name=eventx&advertiser_id=877&sdk=server&site_id=1357&google_aid=aaaaaa-bbbb-cccc-11111-2222222222222&google_ad_tracking=1&user_id=10000000001&device_ip=123.123.123.123&device_brand=Samsung&device_model=Galaxy&device_carrier=Verizon&country_code=US&currency_code=USD&content_id=abc123&content_type=shoes&site_event_items=[{"name":"apples","quantity":"3","unit_price":".5"},{"name":"oranges","quantity":"4","value":"8"}]&response_format=json
Have a Question? Please contact support@tune.com for technical support.