Passthrough Parameters & Postback Macros

Passthrough Parameters

During the Ad Network integration process, Ad Networks can provide passthrough parameters to Singular that they wish to receive in their attribution postback. These values can be passed through as any parameter that is not already used or included in the Singular tracking link. A common passthrough parameter is often an Ad Network's internal advertiser ID, e.g. aid=115873. These parameters must be stated when setting up the integration in order to be available for the attribution postback.

Passthrough parameters can also be used by the advertiser to supply custom information in the attribution tracking link that they wish to receive in postbacks to their own servers. Please contact your account manager or Singular support with any questions.
 


Postbacks and Postback Macros

A Postback is a URL which a user or Ad Network designates as an endpoint for notification. For example, upon a successful installation resulting from a campaign, Singular will call a designated install postback to alert the Ad Network of the conversion. Singular supports the following macros in Postbacks:

Application Macros

Macro

Value Description

{APP_NAME}

Display Name of application

{LONGNAME}

Long name (bundle ID) of application


Campaign Macros

Macro

Value Description

{CID}

Campaign Name as specified in Attribution Tracking Tags

{CLID}

Singular assigned click ID (string)

{CREATIVE}

Creative ID - Available only if provided in click.

{GID}

Group Name as specified in Attribution Tracking Tags

{SITE}

Source site or application for click(string). Available if passed in click.

{NETWORK}

Name of network to which install is attributed, when available

{NETWORK=Network Name}

Will return '1' if the network is equal to specified Network Name, '0' if not. Please note, network name must be exactly the same as the Campaign Source specified in the Attribution Tracking Tag. For example, an install attributed to Tapjoy would return a '1' for {NETWORK=Tapjoy}, but a '0' {NETWORK=tapjoy}.

{IS_RE_ENG}

Will return '1' if attributed to a re-engagement campaign, '0' if not.


Device Related Macros

Macro

Value Description

{IP}

IP of the device at the time of the clicked ad

{OS_VERSION}

OS version of the device at the time of the clicked ad

{APP_VERSION}

App version of the device at the time of the install/event

{IDFA}

Unhashed iOS advertising identifier of device

{IFA1}

SHA-1 of iOS advertising identifier of device

{IFA5}

MD5 of iOS advertising identifier of device

{IDFV}

Unhashed iOS identifier for vendor

{ANDI}

Unhashed Android ID - this identifier is available if the advertising identifier (AIFA) is not available on the device.  As this identifier is not always available, we recommend using {AIFA}, or {COALESCE|{AIFA},{ANDI}} to ensure a value is always passed.

{AND1}

SHA1 of Android ID

{AIFA}

unhashed Android advertising identifier of device

{AIF1}

SHA-1 of Android advertising identifier of device

{AIF5}

MD5 of Android advertising identifier of device

{COALESCE}

Pass one ID or the other. Example: {COALESCE|{AIFA},{ANDI}} will let you pass AIFA or ANDI (if AIFA is not available)

{PLATFORM}

iOS or Android

{COUNTRY}

Country from which user installed

{CITY}

City from which user installed

{APID}

Singular internal ID (string).

{USERID|user.key}

Custom user ID. Replace key with the key of the custom user ID key-value pair. For example, where the key-value is balloonjumpID=username, the macro should be {USERID|user.balloonjumpID}. This will be replaced with 'username'.

{DNT}

Do not track flag is set active a 1 will be returned, all other conditions will return 0

{NODNT}

Do not track flag is set active a 0 will be returned, all other conditions will return 1

{DEVICE_MODEL}

Device model

{DEVICE_BRAND}

Device Brand

{MATCH_TYPE}

Indicates whether and attribution is Organic (null value), deterministic (device id matching) or with fingerprinting methodology


Event Macros

Macro

Value Description

{AMOUNT}

Revenue event postbacks only - The transaction amount in dollars and cents

{CURRENCY}

Revenue event postbacks only - The three-letter ISO 4217 currency code for the transaction

{EVTNAME}

Name of the event

{EVTATTR:Attribute_Name}

Value from the specified attribute. For example, if you have an event named 'Checkout' with an attribute 'Number of Items', then {EVTATTR:Number of Items} would return the number of items from the 'Checkout' event.

{IS_FIRST_EVENT}

Returns '1' for the first occurrence of an event (revenue or custom), '0' for every subsequent event from the same device ID.


Facebook Macros

Macro

Value Description

{FB_C_ID}

Numeric Facebook Campaign ID. Subject to restrictions based on Facebook's terms of service.

{FB_C_NAME}

Facebook Campaign name. Subject to restrictions based on Facebook's terms of service.

{FB_AS_ID}

Numeric Facebook Ad Set ID. Subject to restrictions based on Facebook's terms of service.

{FB_AS_NAME}

Facebook Ad Set name. Subject to restrictions based on Facebook's terms of service.

{FB_A_ID}

Numeric Facebook Ad ID. Subject to restrictions based on Facebook's terms of service.

{FB_A_NAME}

Facebook Ad name. Subject to restrictions based on Facebook's terms of service.


Twitter Macros

Macro

Value Description

{TWTR_C_NAME}

Twitter Campaign Name. Subject to restrictions based on Twitter's terms of service.

{TWTR_C_ID}

Twitter alphanumeric Campaign ID. Subject to restrictions based on Twitter's terms of service.

{TWTR_G_ID}

Twitter alphanumeric Line Item ID. Subject to restrictions based on Twitter's terms of service.

{tweet_id}

Tweet ID - Applicable to organic twitter installs only.

singular suggests the following convention for capturing the Tweet ID for Twitter associated installs: your_parameter={CREATIVE}{tweet_id}

This will capture the Tweet ID value for installs attributed to Twitter Campaigns and organic Twitter installs.


Time Macros

Macro

Value Description

{DATE}

Install or event date (string formatted as "YYYYMMDD") in GMT timezone

{TIME}

Install or event timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone

{UTC}

Install or event timestamp in UNIX format in seconds

{UTCM}

Install or event timestamp in UNIX format in milliseconds

{CLICK_UTC}

Click timestamp in UNIX format in seconds

{CLICK_UTCM}

Click timestamp in UNIX format in milliseconds

{CLICK_TIME}

Click timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone

{CLICK_DATE}

Click timestamp (string formatted as "YYYYMMDD") in GMT timezone

{INSTALL_UTC}

Install timestamp in UNIX format in seconds

{INSTALL_UTCM}

Install timestamp in UNIX format in milliseconds

{INSTALL_TIME}

Install timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone

{INSTALL_DATE}

Install timestamp (string formatted as "YYYYMMDD") in GMT timezone

{STRFTIME|<constructing values>,ts (optional),round (optional)}

Constructable timestamp. The timestamp can be constructed using the following defined values and any additional desired characters:

  • %d - Day of month as a zero-padded number (01, 02,...,31)
  • %m - Month as a as a zero-padded number (01, 02,...,12)
  • %Y - Year with four digits (2014)
  • %H - Hour in 24 hour format
  • %I - Hour in 12 hour format (the letter is i in caps)
  • %M - Minute as a zero padded number (00, 01,...,59)
  • %S - Second as a zero padded number (00, 01,...,59)

For example, {STRFTIME|%Y-%m-%dT%H:%M:%S} would populate like so: 2014-08-22T10:06:52


"ts" is an optional UNIX timestamp which will be used for the formatting; if no "ts" is specified, the current time is used.  Supported "ts" values are {CLICK_UTC}, {INSTALL_UTC}, and {UTC}.


For example, {STRFTIME|%Y-%m-%dT%H:%M:%S,{UTC}}


"round" is an optional modified which will truncate/round to one of the following: year, month, day, hour, or minute


For example if {CLICK_UTC} is 1435627795:

{STRFTIME|%s,{CLICK_UTC},month} -> 1433116800

{STRFTIME|%s,{CLICK_UTC},day} -> 1435622400

{STRFTIME|%s,{CLICK_UTC},hour} -> 1435626000

{STRFTIME|%s,{CLICK_UTC},minute} -> 1435627740


Other Macros

Macro

Value Description

{RAND}

Random 10 character integer

{JSON}

Used to convert the request from GET to POST with a JSON payload. Everything to the left of that macro is evaluated normally, but the part to the right is removed from the URL, converted into a JSON dictionary equivalent to the query string parameters, and we perform a HTTP POST to the URL left of the {JSON} macro.

{POST}

Similar to the {JSON} macro, except the payload is sent using the older application/x-www-form-urlencoded encoding.

{HTTP_HEADER|k,v}

Add a single key/value pair to the HTTP header using this macro. Add additional key/value pairs by adding additional instances of the macro, e.g.  {HTTP_HEADER|SampleKey1,SampleValue1}{HTTP_HEADER|SampleKey2,SampleValue1}.

This macro will be used to populate the header and will be completely removed from the URL when sent, so do not add any additional characters such as '&' or '?' when adding this macro to the URL, e.g.

https://theURL.com/endpoint?{HTTP_HEADER|SampleKey1,SampleValue1}singular_cl={CLID}&andi={ANDI}{HTTP_HEADER|SampleKey2,SampleValue2}


Macro Modifiers

Macro

Value Description

{SHA1|{Macro}}

Modifier will encode the value as SHA-1. For example, if the {CLID} macro returned '1000', {SHA-1|{CLID}} would return 'fb2f85c88567f3c8ce9b799c7c54642d0c7b41f6'.

{MD5|{Macro}}

Modifier will encode the value as MD5. For example, if the {CLID} macro returned 'ABCD', {MD5|{CLID}} would return 'cb08ca4a7bb5f9683c19133a84872ca7'.

{BASE64|{Macro}}

Modifier will encode the value as standard Base64. For example, if the {CLID} macro returned 'ABCD', {BASE64|{CLID}} would return 'QUJDRA=='. (The returned value will be HTTP encoded in the URL)

{BASE64U|{Macro}}

Modifier will encode the value as url-safe Base64. For example, if the {CLID} macro returned 'ABCD', {BASE64U|{CLID}} would return 'QUJDRA=='. (The returned value will be HTTP encoded in the URL)

{HMACSHA1|{Macro},key}

Modifier will encode the value as HMAC SHA-1 using the provided key. For example, if the {CLID} macro returned 'ABCD', {HMACSHA1|{CLID},sample} would return 'f5143f3dda1b120ac280a82b2cae0ff60dc342b5'.

{HMACMD5|{Macro},key}

Modifier will encode the value as HMAC MD5 using the provided key. For example, if the {CLID} macro returned 'ABCD', {HMACMD5|{CLID},sample} would return '43d752ccec4044f90a66a7d15762075e'.

{UPPER|{Macro}}

Modifier will return the provided value in upper case characters. For example, if the {CLID} macro returned 'abcd', {UPPER|{CLID}} would return 'ABCD'.

{LOWER|{Macro}}

Modifier will return the provided value in lower case characters. For example, if the {CLID} macro returned 'ABCD', {LOWER|{CLID}} would return 'abcd'.

{MULTIPLY|{Macro},multiple}

Modifier will multiply the number by the value returned by the macro to the nearest whole number.  To convert the value of a product purchase in floating point to micro it requires multiplying the {AMOUNT} macro 1e6 (1000000). For example, a $5250.23 purchase would become 5250230000 when formatted as {MULTIPLY|5240.23,1000000}.




Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk