Postback Macros and Passthrough Parameters for Ad Networks

Follow
Avatar
Luanna Rossi
Updated

Postbacks and Postback Macros

Postbacks are automatic notifications that Singular sends to ad network partners via a predefined URL specified by the network. These notifications are triggered when Singular records a successful conversion event--such as an install, in-app action, web event, PC event or console event--resulting from an ad campaign. The postback ensures that the ad network is informed in realt time about the user interactions. 

As an ad network partner, you define the structure of your postback template in collaboration with Singular. Below is an example postback format, showcasing various support postback macros:

https://YourCompanyEndpoint.com?cl_id={cl?NetworkName}&app_id={{app_id}}&ip={EVENT_IP}&amount={AMOUNT}&event={EVTNAME}&timestamp={UTCM}

 

Supported Macro Types in Postbacks

Application Macros

Application macros contain data derived from the advertiser's implementation with Singular's mobile or web SDK or from server-to-server (S2S) events shared by the advertiser.

Macro Value Description
{APP_NAME} Display Name of the application
{LONGNAME} The bundle ID on iOS and package name on Android applications (e.g., com.example.myapp)
{PUBLIC_ID}

The App Store ID (Store ID) of the application from Apple's App Store URL (e.g., 1441750662). This is only available on iOS.

Example URL of Singular's Device Assist app: https://apps.apple.com/kz/app/singular-device-assist/id1441750662

Campaign Macros

Information sent from campaign macros are referred to as passthrough macros which send information ad networks include on Singular's tracking links. Singular also supports sending Static Postback values which can be inputted at the time of advertiser setup. Please see Static Postback Parameters below.

Macro Value Description
{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

Device-related macros contain information derived from the advertiser's implementation with Singular's mobile or web SDK, server-to-server (S2S) events shared by the advertiser, and the timestamp when Singular logs an event received from the advertiser.

Macro Value Description
{TOUCHPOINT_IP} IPv4 of the device at the time of the attributed touchpoint
{ATTRIBUTION_IP} IPv4 of the device at the time of the attribution, install or re-engagement
{EVENT_IP} IPv4 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. This identifier is not collected if AIFA and ASID are available on a device, so 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 (AAID) of the device, a.k.a. GAID. (This ID is available through Google Play services.)
{AIF1} SHA-1 of Android advertising identifier of the device
{AIF5} MD5 of Android advertising identifier of the device
{OAI1} SHA-1 of OAID of the device
{OAI5} MD5 of OAID of the device
{AMI1} SHA-1 of AMID of the device
{AMI5} MD5 of AMID of the device
{ASID} Android App Set ID device identifier (available on Singular Android SDK 12+) (This ID is available through Google Play services.)
{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 an attribution is Organic (null value), deterministic (device ID matching or install referrer) or probabilistic (Android only)
{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.
{GLOBAL_PROPERTIES:propertyName} Pass the value of a global property, if available through the SDK (iOS, Android)
{GLOBAL_PROPERTIES} Pass all global properties (JSON formatted and URL encoded), if available through the SDK (iOS, Android)
{USER_AGENT} The user agent of the device, (Determined by the SDK).  
{ATT_AUTHORIZATION_STATUS}

The current App Tracking Transparency authorization status of the device. This value is populated for iOS 14 and above devices.

  • -1 - Not determined, App Tracking Transparency not implemented
  • 0 - Not determined
  • 1 - Restricted
  • 2 - Denied
  • 3 - Authorized
{ATT_NAME}

The name of the current App Tracking Transparency authorization status of the device. This value is populated for iOS 14 and above devices.

  • NOT_DETERMINED - -1
  • NOT_DETERMINED - 0
  • RESTRICTED - 1
  • DENIED - 2
  • AUTHORIZED. -3

Event Macros

Event-related macros contain information derived from the advertiser's implementation with Singular's mobile or web SDK, server-to-server (S2S) events shared by the advertiser. These macros pass key details about an event to help ad network partners track and optimize campaign performance. 

Macro Value Description
{AMOUNT}

Revenue event postbacks only. The transaction amount in the transaction currency, rounded to two digits after decimal, e.g., revenue amount 1.346 will be sent as 1.35. This rounds up in-app ad (IAA) revenue from 0.001 to 0.00. See {RAW_AMOUNT} for receiving ad revenue.

For rejected revenue events, the value is 0 (see IAP_RECEIVED_REVENUE for the original event name).

If used in a re-engagement postback, this macro passes the user LTV.
{ORIGINAL_REVENUE} Revenue in dollars as we received from the app via SDK / S2S.
{CONVERTED_REVENUE}
 Revenue according to the client's organization currency (configured in the org's admin dashboard page). For example, if we received Rev in JPY but the Org's currency is configured to USD, the CONVERTED_REVENUE will be in USD. 
{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.
{EVTATTRS} This macro passes all attributes and arguments associated with the event (if any). The macro populates the JSON payload of the attributes.  For example, if there is an event named "Checkout" and the advertiser has passed information about the transaction, {EVTATTRS} may include the following: 
{
 "number_of_items": 5,
 "cost":{
 "sub_total": 50.99,
 "tax": 1.01,
 "total": 52.00
}
{EVTATTR:Attribute_Name} Value from the specified attribute.  Advertisers may optionally pass event attributes and arguments when reporting events to Singular.  Attributes and arguments are passed as JSON key-value pairs, and the {EVTATTR:Attribute_Name} macro can be used to pass a value from a specific JSON key.  For example, if you have an event named 'Checkout' with the 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) or '0' for every subsequent event from the same device ID.
{RAW_AMOUNT} The amount received in the revenue event without rounding. E.g., revenue amount 1.346 will be sent as 1.346. Use this if you expect several fractional revenue amounts, such as with in-app ad (IAA) revenue.

Time Macros

Time macros provide information based on Singular's recorded timestamps of advertiser events or touchpoints captured through Singular's tracking links.  

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

The following macros can be used to format the postback or enable authentication, if required. 

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}
{FRAUD_REASON_EXTERNAL} The rejection reason can be either one of Singular's built-in Fraud Protection Methods (see details) or a custom rule defined by the customer.
{JSON_EXTRACTOR|json,q}

Extracted values from JSON based on the GJSON Syntax, which supports dot notation syntax, pipe, and other functionality for complex extraction. The macro takes two parameters: a json and an extraction string q in the package's syntax.

Example using the evtattr json:
{JSON_EXTRACTOR|{EVTATTRS}, SampleKey.1.SampleKey}

Note: For extraction query that includes the characters "{","}" or ",", use the macro GJSON on q: {JSON_EXTRACTOR|json,{GJSON|q}}

Macro Modifiers

Macro modifiers allow you to format data or set conditions that determine when information is included in postbacks. These modifiers help customize postback data to meet specific reporting needs. 

Macro Value Description
{SHA1|{Macro}} Modifier will encode the value as SHA-1. For example, if the {CLID} macro returned '1000', {SHA1|{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}.
{TERNARY|a,b,x,y} Takes 4 arguments, a,b,x,y and returns x if a == b, and y otherwise.

For example:
{TERNARY|0,1,yes,no} will return "no"
{MAPPER|
P,v1:r1,v2:r2,D}
 		First argument is the parameter to check.
After that you can add the cases(no limit on the number of cases), in the format "a:b" - if the value of P is "a", return "b".
Last argument is the default value to return - if P didn't match any value. For example:
{MAPPER|{OS_VERSION},14.1:AB,14.2:CD,14.3:EF,ZZ}
which equal to:
if {OS_VERSION} is 14.1, return AB
if {OS_VERSION} is 14.2, return CD
if {OS_VERSION} is 14.3, return EF
else return ZZ

Passthrough Postback Parameters

 When integrating with Singular, ad networks can request additional data to be included in their attribution postbacks. These extra data points, known as passthrough parameters, allow networks to pass custom values via tracking links and receive them back in postbacks for events that have been attributed to their campaign. Passthrough parameters can include any information not already used in a Singular tracking link.

How Passthrough Parameters Work

An ad newtork can define a custom parameter in the tracking link, such as an internal advertiser ID. For example, a network may choose to pass this ID using a parameter like "aid" and populate it with their macro (e.g., aid=115873). Singular then creates a corresponding passthrough macro to ensure this value is included in the partner postback integration. 

Example:

Partner name: BestROI

Tracking link example:

https://singularassist2.sng.link/C90g4/uar5?aid={macro_for_advertiser_id}

Populated version:

https://singularassist2.sng.link/C90g4/uar5?aid=115873

Postback example:

https://YourCompanyEndpoint.com/attribution?aid={aid?BestROI}

Populated version:

https://YourCompanyEndpoint.com/attribution?aid=115873

 

Passthrough parameters can also be used to attach other types of information to tracking links that ad networks want to receive in postbacks. This flexibility allows partners to customize the data flow according to their specific needs. 

Static Postback Parameters

Ad network partners may require static values to be included in postbacks to ensure their system logs data correctly. When setting up static values, it's important to clarify whether they should:

  • Apply universally to all postbacks received from Singular
  • Be specific to a particular advertiser's app
  • Vary based on both the advertiser and the event

Defining these details helps ensure accurate data transmission and seamless integration with Singular. 

Examples:

  • A security token: generally a single global token that has been assigned to identify events coming from Singular for any advertiser. 
  • An advertiser ID/key: generally unique to identify the advertiser or advertiser's application for which events are being sent from Singular. 
  • Goal values: generally unique per advertiser's application and each event when a partner needs to map specific events per client. Singular's {EVTNAME} macro can be used or Singular can support a list of static values which advertisers map the {EVTNAME} value to that the partner's system is configured to report.

FAQ

How are Postbacks sent?

  1. Singular makes an HTTP GET request with the data structured defined by the media partner.
  2. If Singular receives an HTTPS response code between 500 and 599, it retries sending the postback (there is a maximum of 5 retries).
  3. Retries are attempted after 1, 5, 15, 30, and 60 minutes from the original send attempt.
  4. For an up-to-date list of IP addresses postbacks are sent from, see Postback Server IP Addresses.

How can my ad network integrate with Singular if they use a tracking platform?

Singular integrates with ad network partners using various third-party tracking platforms. Some of the commonly supported platforms include: 

  • Affise
  • Everflow
  • Tune (formerly Hasoffers)

If your tracking platform is not listed above, we recommend reaching out to your platform's support team and providing Singular with the necessary documentation. This should include details on the macros used in tracking links and the postback parameters required for data transmission.

How can data be sent to third-party analytics platforms?

Singular supports integrations with third-party analytics platforms and can help you scope out what data and macros to use. The following macros is often helpful to align the data with Singular tracking tag names.

Macro Value Description
{CID} Campaign Name as specified in Attribution Tracking Tags