Macros in Postback URLs for Post-Install Events

When Attribution Analytics measures an event, all values are collected on conversion. To receive these values, you need to include the appropriate macros in your TUNE Partner Center postback URL templates, which are replaced by Attribution Analytics on conversion with the corresponding values.

For user acquisition campaigns (where new users install the mobile app), advertisers primarily use postback URLs to notify their partners of install events. In some cases, partners request notification of other events as well, for the purposes of using the data for campaign optimization.

For re-engagement campaigns (where existing users re-engage with the app), advertisers use postback URLs to notify their partners of important post-install events.

This article is part of our FAQs & Troubleshooting series.

Basic Event Macros

Advertisers can collect these basic macros:

  • {device_brand} – Brand or make of the device  (such as Apple or Motorola).
  • {device_model} – Model of the device (such as iPhone, iPad, or DroidX).
  • {device_carrier} – Wireless carrier of the device (if it supports cellular, such as AT&T).
  • {device_ip} – IP address of the user device (such as 123.123.123.123).

For a complete list of macros available to advertisers, see the Attribution Analytics documentation on macros in postback URLs.

Macros for Advertising Identifiers

The following table shows the advertising identifiers you can collect for each device platform:

Platform/OS Advertising Identifier
iOS
  • {ios_ifa} – The Apple Identifier for Advertisers, available with iOS versions 6.0+. Also referred to as IFA or IDFA.
  • {ios_ad_tracking_disabled} – If the ios_ifa parameter is used, then this parameter must be specified to indicate if the user has enabled Limit Ad Tracking (where 1 is enabled/limited).
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 used, then this parameter must be collected to indicate if the user has enabled Limit Ad Tracking (where 1 is enabled/limited).
Windows Phone
  • {windows_aid} – The Windows advertising identifier (AID) is a unique, user and device-specific, resettable ID 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.

Advertisers can also collect user identifiers with each event request. If advertisers specify a value, then you can use the following macro.

  • {user_id} – Unique user ID of the user (such as “tom12345”), defined by the advertiser.

Event Description Macros

You can use the following macros to get a basic description of an event:

  • {is_assist} – Partner assisted with, but is not responsible for conversion; 1 = Yes, 0 = No.
  • {is_attributed} – Event is attributed to the partner being sent the postback; 1 = Yes, 0 = No.
  • {is_first_event} – First log for a user of that specific post-install event; 1 = Yes, 0 = No.
  • {is_first_purchase} – First log for a user with revenue greater than 0 of that specific post-install event; 1 = Yes, 0 = No.
  • {is_install_attributed} – User’s install event was attributed to the partner being sent the postback; 1 = Yes, 0 = No.
  • {is_reengagement} – Post-install event occurred within a re-engagement window; 1 = Yes, 0 = No.
  • {is_view_through} – Event is a view-through conversion; 1 = Yes, 0 = No.

For more information about checking if an event is the first event for a user, or retrieving the number of times that the event was completed by the user, read our Attribution Analytics article on first event and first purchase postback parameters.

Post-Install Event Macros

The following table lists the available macros that can be included in your postback URLs for post-install events. Consider updating your postback URL templates to include these additional macros for increased granularity and insight.

Event Name Description Available Macros
Open Any time a user opens the app.
  • {event_type} = “open”
Login Any time a user logs into the app.
  • {event_type} = “login”
  • {user_id} (recommended)
  • {user_email} (recommended)
  • {user_name} (recommended)
  • {gender} (optional)
  • {age} (optional)
Registration Any time a user creates or registers an account.
  • {event_type} = “registration”
  • {user_id} (recommended)
  • {user_email} (recommended)
  • {user_name} (recommended)
  • {gender} (optional)
  • {age} (optional)
Add to Cart When a user adds a product to their shopping cart; this event can include an event item.
  • {event_type} = “add_to_cart”
  • {revenue_usd} – Potential revenue converted to USD based on current exchange rate.
  • {revenue} – Potential revenue in local currency. If used, should include {currency_code}.
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
  • {event_items_json}JSON array of event items added to cart, as defined by advertiser. Commonly includes:
    • Name – name of the item
    • Product ID – SKU
    • Unit Price – individual price of one unit
    • Quantity – number of items purchased
    • Revenue – total value of the purchase
Add to Wishlist Similar to the Add to Cart event, but instead of users intending to buy the product now, they’re saving the product to a list.
  • {event_type} = “add_to_wishlist”
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
  • {event_items_json}JSON array of event items added to wishlist, as defined by advertiser. Commonly includes:
    • Name – name of the item
    • Product ID – SKU
    • Unit Price – individual price of one unit
Added Payment Info Any time a user saves their payment information.
  • {event_type} = “added_payment_info”
Checkout Initiated Similar to the Purchase event (below), but Attribution Analytics measures this event immediately after the desired items (products) are defined and the user initiates the checkout process (prior to purchase). You can use this “checkout initiated” event to determine which products a user did not complete purchasing (the items that they abandoned).
  • {event_type} = “checkout_initiated”
  • {advertiser_ref_id} – Order or Receipt ID
  • {revenue_usd} – Potential revenue converted to USD based on the current exchange rate.
  • {revenue} – Potential revenue in local currency. If used, should include {currency_code}.
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
  • {event_items_json}JSON array of event items added to cart, as defined by advertiser. Commonly includes:
    • Name – name of the item
    • Product ID – SKU
    • Unit Price – individual price of one unit
    • Quantity – number of items purchased
    • Revenue – total value of the purchase
Purchase Any time a user completes the checkout process. If these purchase events are for in-app purchases, then clients can use our in-app purchase verification with this event as well. Each SKU or line item in the shopping cart should have its own event item.
  • {event_type} = “purchase”
  • {advertiser_ref_id} – Order or Receipt ID
  • {revenue_usd} – Potential revenue converted to USD based on the current exchange rate.
  • {revenue} – Potential revenue in local currency. If used, should include {currency_code}.
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
  • {is_first_purchase} – If the event measured (where the revenue is greater than 0) is the user’s first one for a specific event; 1 = Yes, 0 = No.
  • {event_items_json}JSON array of event items, as defined by advertiser. Commonly includes:
    • Name – name of the item
    • Product ID – SKU
    • Unit Price – individual price of one unit
    • Quantity – number of items purchased
    • Revenue – total value of the purchase
Reservation Events related to travel and entertainment apps. Date1 can be used for single-day reservation. If multi-day reservations, then use Date1 for check-in and Date2 for check-out.
  • {event_type} = “reservation”
  • {date1} – Time of Check In. (date time format of yyyy-mm-dd hh:mm:ss)
  • {date2} – Time of Check Out. (date time format of yyyy-mm-dd hh:mm:ss)
  • {quantity} – Count of Guests
  • {revenue_usd} – Potential revenue converted to USD based on current exchange rate.
  • {revenue} – Potential revenue in local currency. If used, should include {currency_code}.
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
  • {advertiser_ref_id} – Reservation number or order ID.
Spent Credits Any time a user spends credits within an app (typically for gaming apps).
  • {event_type} = “spent_credits”
  • {quantity} – Number of credits spent.
Achievement Unlocked When a user gets access to a new achievement (for example, finding a secret key in a gaming app).
  • {event_type} = “achievement_unlocked”
  • {content_id} – Name or ID of Achievement.
Level Achieved When a user completes one level and proceeds to the next level (typically in a gaming app).
  • {event_type} = “level_achieved”
  • {level} – Name or ID of Level.
Tutorial Complete Any time a user completes a tutorial.
  • {event_type} = “tutorial_complete”
Content View When a user views a specific piece of content or product, then the {content_id} macro is set and possibly {content_type}. If viewing a section or category, then only {content_type} may be set.
  • {event_type} = “content_view”
  • {content_id} – Name or ID of content or product.
  • {content_type} – Name or ID of type of product viewed.
  • {revenue_usd} – Unit price converted to USD based on the current exchange rate.
  • {revenue} – Unit price in local currency. If used, should include {currency_code}.
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
Invite Any time a user invites others to your app via a social network.
  • {event_type} = “invite”
Rated Any time a user submits a rating for page content.
  • {event_type} = “rated”
  • {rating} – Value of rating.
  • {content_id} – Content Name or ID.
Search When a user completes a search. Advertisers should collect the keywords used and pass the top five search results as event items (as well as options for setting the check-in, check-out, and guest count parameters for travel and entertainment-related apps).
  • {event_type} = “search”
  • {currency_code} – Currency code of revenue using ISO 4217 currency codes.
  • {search_string} – Search term or search keywords.
  • {date1} – Time of Check In. (date time format of yyyy-mm-dd hh:mm:ss)
  • {date2} – Time of Check Out. (date time format of yyyy-mm-dd hh:mm:ss)
  • {quantity} – Count of Guests
  • {event_items_json}JSON array of event items, as defined by advertiser. Searches for a product commonly include:
    • Name – name of the item
    • Product ID – SKU
    • Unit Price – individual price of one unit
Share Any time a user shares content via email or social network.
  • {event_type} = “share”
  • {content_id} – Content Name or ID.

No Comments

Leave a reply