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?

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

To unpack this, the below describes 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 tracking links

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 Tenjin callbacks and routing events

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.

Macro Explanation
{{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)
{{store_id}} App Store ID of the app. (887212194)
{{time_in_ms}} Request time in milliseconds.
{{time_in_seconds}} Request time in seconds.
{{time_iso8601}} Request time in ISO 8601 format.
{{engaged_at_ms}} Timestamp for click or impression event in milliseconds
{{acquired_at_ms}} Timestamp for install event in milliseconds
{{advertising_id}} Advertising identifier of the device.
{{lowercase_advertising_id}} Lower case of advertising identifier of the device.
{{md5_advertising_id}} MD5 of the advertising identifier.
{{developer_device_id}} Identifier for Vendor (IDFV) or the developer device ID.
{{allow_ad_tracking}} Device allows ad tracking? (true, false)
{{limit_ad_tracking}} Device limits ad tracking? (true, false)
{{allow_ad_tracking_integer}} Device allows ad tracking? (1, 0)
{{limit_ad_tracking_integer}} Device limits ad tracking? (1, 0)
{{ip_address}} User's IP address.
{{country}} Country code of the user's device.
{{campaign_name}} Tenjin Campaign Name that the user is attributed to.
{{tenjin_campaign_id}} Tenjin Campaign ID that the user is attributed to.
{{remote_campaign_id}} Channel's Campaign ID that the user is attributed to.
{{click_id}} Channel's click ID if the user is attributed to paid channels.
{{referrer}} Android referrer
{{site_id}} Channel's Site ID that a user is attributed to.
{{ad_network}} Channel name that a user is attributed to.
{{revenue}} Gross revenue earned for a purchase in original currency
{{currency}} Currency code of the purchase.
{{revenue_usd_net}} Net revenue in USD for a purchase.
{{revenue_usd_gross}} Gross revenue in USD for a purchase.
{{device}} User's device.
{{os_version}} User's OS version.
{{app_version}} User's app version.
{{sdk_version}} User's Tenjin SDK version.
{{language}} User's language setting.
{{value}} Custom event value.
{{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.

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

results matching ""

    No results matching ""