Callback macros
  • 27 Jan 2023
  • 7 Minutes to read
  • Dark
    Light

Callback macros

  • Dark
    Light

Callback macros

Macros are placeholders for values that change dynamically in a URL's server request. These macros are pre-configured for Tenjin integrated networks, but learning how macros work can be useful for any custom channels that you want add.


Why do we need macros?

Show more

We need macros to pass dynamically changing data through unchanging tracking link parameters.

To unpack this, we will explain how URLs, parameters, values, and dynamically changing values work within attribution.


URLs and parameters

Let's take a look at a standard URL:
https://track.tenjin.io?param1=value1. In this URL you can see there is a server address track.tenjin.io and a single parameter param1 set to a value value1. When this URL hits the track.tenjin.io server, Tenjin's server reads this URL and parses the parameter and value. In this case param1 is set to value1.

In a more realistic example relating to attribution parameters and values, take this URL with two parameters (advertising_id and country) and two values: https://track.tenjin.io?advertising_id=xyz123&country=US. When this request hits the Tenjin server at track.tenjin.io, we know that the advertising_id that hit the server is the device xyz123 with a country of US.


Dynamic parameter values

Now that we know how values and parameters are passed to a server, let's look at how URLs are used in the context of attribution and tracking.

In order for Tenjin to attribute a user to a click or an impression, Tenjin collects device information and properties on each click or impression. These properties are used to match up with the properties collected when a device installs the app.

A Tenjin tracking URL is generated whenever you create a campaign for a non-SAN network or a custom channel. This tracking URL contains "macros" that dynamically adapt to changing values around the click or impression. Macros are used as placeholders for values that change in a specific URL.

Let's say that you wanted to run a campaign on a non SAN network. You create a tracking link through the Tenjin dashboard and give this to your ad network.

This is what a tracking link from Tenjin might look like:

https://track.tenjin.io?advertising_id={idfa}&country={country}

In this case {idfa} and {country} are macros. When a device uses this link, the ad network will fill in these macros with the actual values of the device. Using the previous example, {idfa} and {country} would fill in values with xyz123 and US respectively.

Once filled in, the ad network or channel will hit Tenjin's server using the following URL:

https://track.tenjin.io?advertising_id=xyz123&country=US

Alternatively, if the user's device changed and had an advertising_id of abc234 and a country of CA the URL would change to:

https://track.tenjin.io?advertising_id=abc234&country=CA

As you can see, these scenarios are using the same URL, but changing the values based on the device/user that is using the tracking link.

Macros allow ad networks to change the URL for each user's click/impression. These macros are simply placeholders for the values that are changing when different users interact with the tracking links.


Macros for ad-network callbacks

Show more

Each ad network has its own set of click and impression macros for the following device properties:

  • Advertising ID
  • IP address
  • Bundle ID
  • Country
  • Click ID
  • Site
  • OS Platform
  • Limit Ad Tracking
  • Creative

If the ad network is pre-configured and integrated with Tenjin, each of the ad network macros will automatically show up on each click URL or impression tracking link for each campaign.

As examples:

  • Applovin advertising_id macro looks like this: {IDFA}
  • Tapjoy advertising_id macro looks like this: TAPJOY_ADVERTISING_ID

As a result the Applovin and Tapjoy click urls might look something like this:

  • Applovin: https://track.tenjin.io/v0/id?advertising_id={IDFA}
  • Tapjoy: https://track.tenjin.io/v0/id?advertising_id=TAPJOY_ADVERTISING_ID

Again, each network will have their own macro format. If the network is already pre-integrated with Tenjin you don't need to worry about it. This is just so you know how click and impression URLs are constructed.


Macros for custom callbacks

Show more

When setting up a Tenjin callback to another service, you can use macros to represent dynamically changing data values to send to other servers/services. This is what we call "Routing".

Tenjin allows you to "route" live event data to other servers in real time.

This is a list of available callback macros that you are able to set up when sending data to other services.

  • App related macros
Macro Explanation
{{app_version}} Bundle ID of the app. (com.tenjin.wordfinder)
{{bundle_id}} Bundle ID of the app. (com.tenjin.wordfinder)
{{lowercase_bundle_id}} Lower case of bundle ID of the app. (com.tenjin.wordfinder)
{{platform}} Platform of the app (ios)
{{user_agent}} User's user agent
{{sdk_version}} User's Tenjin SDK version
{{store_id}} App Store ID of the app (887212194)
  • Attribution related macros
Macro Explanation
{{acquired_at_s}} Timestamp for install event in seconds
{{acquired_at_ms}} Timestamp for install event in milliseconds
{{engaged_at_s}} Timestamp for click or impression event in seconds
{{engaged_at_ms}} Timestamp for click or impression event in milliseconds
{{ad_network}} Channel name that a user is attributed to
{{campaign_id}} Same as {{remote_campaign_id}}
{{campaign_name}} Tenjin Campaign Name that the user is attributed to
{{campaign_name_encoded}} Encoded Tenjin Campaign Name that the user is attributed to
{{click_id}} Channel's click ID if the user is attributed to paid channels
{{creative_name}} Creative name
{{deeplink_url}} Deeplink URL
{{is_conversion_integer}} 1 for first app open, 0 for other events
{{is_impression}} 1 => view-through attribution, 0 => click attribution
{{is_install_or_landing}} For first open "install", for subsequent app opens "landing"
{{ip_address}} User's IP address
{{ip_address_click}} IP address for click or impression event
{{remote_campaign_id}} Channel's Campaign ID that the user is attributed to
{{site_id}} Channel's site ID that a user is attributed to
{{site_id_encoded}} Encoded channel's site ID that a user is attributed to
{{ad_network_short_id_match_type}} If the user came from device, probablistic or referrer attribution
{{tenjin_campaign_id}} Tenjin Campaign ID that the user is attributed to
{{tenjin_parameter_0}} Pass through macro you can pass through from click url
{{tenjin_parameter_1}} Pass through macro you can pass through from click url
{{tenjin_parameter_2}} Pass through macro you can pass through from click url
{{tenjin_parameter_3}} Pass through macro you can pass through from click url
{{tenjin_parameter_4}} Pass through macro you can pass through from click url
{{tenjin_parameter_5}} Pass through macro you can pass through from click url
  • Device identifier related macros
Macro Explanation
{{advertising_id}} Advertising identifier of the device
{{analytics_installation_id}} Application install-specific identifier for Android devices. Used for analytics when a user does not consent to sharing their Google advertising id. (Empty for iOS.) Lower case, without hyphen.
{{developer_device_id}} Identifier for Vendor (IDFV) or the developer device ID
{{formatted_advertising_id}} Formatte Advertising identifier of the device, 00000000-0000-0000-0000-000000000000 if it is empty
{{imei}} IMEI
{{md5_advertising_id}} MD5 of the advertising identifier
{{lowercase_advertising_id}} Lower case of advertising identifier of the device
{{md5_imei}} md5 of IMEI
{{md5_oaid}} md5 of OAID
{{oaid}} OAID
  • Device properties related macros
Macro Explanation
{{allow_ad_tracking}} Device allows ad tracking? (true, false)
{{allow_ad_tracking_integer}} Device allows ad tracking? (1, 0)
{{carrier}} Device carrier
{{connection_type}} Connection type
{{country}} Country code of the user's device
{{device}} User's device
{{device_brand}} Device brand
{{device_model}} Device model
{{language}} User's language setting
{{limit_ad_tracking}} Device limits ad tracking? (true, false)
{{limit_ad_tracking_integer}} Device limits ad tracking? (1, 0)
{{locale}} Device locale
{{os_version}} User's OS version
{{os_version_release}} User's OS version release
{{referrer}} Android referrer
{{timezone}} Device timezone
{{tracking_status}} Integer for the iOS device's ATT status. 0 => not determined, 1 => restricted, 2 => denied, 3 => authorized
  • Event related macros
Macro Explanation
{{currency}} 3 digit currency code of the purchase
{{event}} Event name
{{time_in_seconds}} Request time in seconds
{{time_in_ms}} Request time in milliseconds
{{time_iso8601}} Request time in ISO 8601 format
{{revenue}} Gross revenue earned for a purchase in original currency
{{revenue_usd_net}} Net revenue in USD for a purchase
{{revenue_usd_gross}} Gross revenue in USD for a purchase
{{value}} Custom event value
  • Ad impressions related macros

AppLovin

Macro Explanation
{{ad_unit_id}} Ad unit ID reported by the winning network
{{currency}} Currency ad revenue is reported in
{{ad_format}} Format of the ad unit
{{mediation_country}} Country from the mediation provider
{{network_name}} Network that displayed the ad
{{ad_revenue}} Revenue reported by the ad network
{{network_placement}} Network defined placement
{{placement}} Placement of the ad unit
{{creative_id}} Creative ID of the ad unit
{{precision}} Precision of the revenue

ironSource

Macro Explanation
{{ab_test}} A/B test value
{{ad_format}} Format of the ad unit
{{ad_revenue}} Revenue reported by the ad network
{{auction_id}} Auction ID from Ironsource mediation
{{ecpm}} eCPM from Ironsource mediation
{{instance_id}} Instance ID from Ironsource mediation
{{instance_name}} Instance Name from Ironsource mediation
{{mediation_country}} (not used, will use the Tenjin country macro)
{{mediation_ltv}} Lifetime Revenue from Ironsource mediation
{{network_name}} Network that displayed the ad
{{placement}} Placement of the ad unit
{{precision}} Precision of the revneue
{{segment}} Segment Name from Ironsource mediation

HyperBid

Macro Explanation
{{mediation_country}} Country from the mediation provider
{{ad_network_type}} Type of Network, Cross Promotion, or exchange
{{adsource_index}} Sorting of the current ad source in the Waterfall

AdMob

Macro Explanation
{{precision}} Precision type defined by AdMob
{{ad_unit_id}} Ad unit ID defined by AdMob
{{currency}} Currency code from AdMob
{{adapter_class}} Adapter class of ad network
{{response_id}} Response ID provided by AdMob
{{ad_revenue_micro}} Ad revenue in micro cents provided by AdMob

Topon

Macro Explanation
{{mediation_country}} Country from the mediation provider
{{ad_network_type}} Type of Network, Cross Promotion, or exchange
{{adsource_index}} Sorting of the current ad source in the Waterfall

You can read more about routing and using these macros in the callback setup.



Was this article helpful?

What's Next