Postback Macros and Passthrough Parameters

 

Postbacks and Postback Macros

Postbacks are automatic notifications sent by Singular to ad networks through a specific URL selected by the network. For example, whenever Singular registers a successful install resulting from an ad campaign, we alert the ad network with a postback.

Singular supports the following macros in postbacks:

Application Macros

Macro Value Description
{APP_NAME} Display Name of the 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)
{cl?Network Name} Network click ID (string) which is passed by the network through Singular's tracking link's cl parameter. Network Name must be replaced with the name by which it is integrated with Singular
{pcrid?Network Name} Creative ID - Available only if provided in the click.
{pcrn?Network Name} Creative Name - Available only if provided in the click.
{pshid?Network Name} Hashed or anonymized ID for the publishing app for the click(string). Available if passed with the click.
{psid?Network Name} Source site or application ID for the click(string). Available if passed with the click.
{psn?Network Name} Source site or application name for the click(string). Available if passed with the click.
{NETWORK=Network Name} Will return '1' if the attributed network equals to specified Network Name in the macro, '0' if not.
{IS_RE_ENG} Will return '1' if attributed to a re-engagement campaign, '0' if not.
{IS_VIEWTHROUGH} Will return '1' if attributed due to an impression link, '0' if not.

Device Related Macros

Macro Value Description
{TOUCHPOINT_IP} IP of the device at the time of the attributed touchpoint
{ATTRIBUTION_IP} IP of the device at the time of the attribution, install or re-engagement
{EVENT_IP} IP of the device at the time of the executed event
{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 the device
{IFA1} SHA-1 of iOS advertising identifier of the device
{IFA5} MD5 of iOS advertising identifier of the device
{IDFV} Unhashed iOS identifier for the 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 the device
{AIF1} SHA-1 of Android advertising identifier of the device
{AIF5} MD5 of Android advertising identifier of the 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
{TOUCHPOINT_COUNTRY} Country location of the device at the time of the attributed touchpoint
{ATTRIBUTION_COUNTRY} Country location of the device at the time of the attribution, install or re-engagement
{EVENT_COUNTRY} Country location of the device when the event occurred
{TOUCHPOINT_CITY} City location of the device at the time of the attributed touchpoint
{ATTRIBUTION_CITY} City location of the device at the time of the attribution, install or re-engagement
{EVENT_CITY} City location of the device when the event occurred
{TOUCHPOINT_STATE} State/province location of the device at the time of the attributed touchpoint
{ATTRIBUTION_STATE} State/province location of the device at the time of the attribution, install or re-engagement
{EVENT_STATE} State/province location of the device when the event occurred
{USERID|user.key} {CUSTOM_USERID|user.key} Custom user ID. Replace "user.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 install referrer) or with fingerprinting methodology
{ATTRIBUTION_WINDOW} The window, in hours, used to attribute the install or re-engagement
{INSTALLER_SOURCE} Android only - Package name of the source that caused the install. E.g. 'com.android.vending' if the install was from the Google Play store.
{APPSTORE_FLAG} Android only - 0, 1 or NULL depending on the installer source. Value is NULL if the data is unavailable.

Event Macros

Macro Value Description
{AMOUNT} Revenue event postbacks only. The transaction amount in the transaction currency. For rejected revenue events, this will become 0 - see IAP_RECEIVED_REVENUE for the original event name.
{CURRENCY} Revenue event postbacks only. The three-letter ISO 4217 currency code for the transaction
{EVTNAME} Name of the event. For rejected revenue events, this will become __iapinvalid__ - see IAP_RECEIVED_EVENT_NAME for the original event name.
{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.
{IAP_RECEIVED_EVENT_NAME} For revenue events, the original event name. If the event is valid, this would be the same as EVTNAME.
{IAP_RECEIVED_REVENUE} For revenue events, the original purchase amount. If the event is valid, this would be the same as AMOUNT.
{IAP_RECEIPT_RECEIVED} For Revenue events, Returns '1' if a purchase receipt was included, '0' otherwise.
{IAP_RECEIPT_VALID} For Revenue events, Returns '1' if a purchase was deemed valid, '0' otherwise.
{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 of latest attribution in UNIX format in seconds (including reengagements)
{INSTALL_UTCM} Install timestamp of latest attribution in UNIX format in milliseconds (including reengagements)
{INSTALL_TIME} Install timestamp of latest attribution (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone (including reengagements)
{INSTALL_DATE} Install timestamp of latest attribution(string formatted as "YYYYMMDD") in GMT timezone (including reengagements)
{STRFTIME|<constructing values>,ts (optional),round (optional)} Constructible 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 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 "i" is 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 an 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}.

Passthrough Parameters

In the process of creating an integration with Singular, ad networks can ask to receive additional pieces of information in their attribution postbacks. These are called passthrough parameters and they can include any parameter that is not already used or included in the Singular tracking link. For example, an ad network can ask to receive the internal advertiser ID, e.g. aid=115873.

Advertisers can also take advantage of passthrough parameters to add information to the tracking link that they wish to receive in postbacks to their own servers.

Was this article helpful?
0 out of 0 found this helpful