Table of Contents
Overview
To manage conversions when a javascript tag or image pixel cannot be installed, such as for app installs, postback tags can be used.
Custom Server-Side Postback Attribution (Not using common vendors listed below)
When creating an event for tracking conversions, select Generic URL for mobile app install Postback under "Tag Type".
Fire this postback URL complete with the corresponding AUCTION_ID of the auction that deserves credit for the conversion. The AUCTION_ID can be obtained in the following ways:
- For click attribution, in any environment, the AUCTION_ID may be passed to the attribution server directly upon the click using the {{AUCTION_ID}} macro in the click URL on the creative. The postback should then be fired if the user ID converts. In desktop or mobile web, this generally requires a cookie sync in place with Beeswax.
- Alternatively, for click attribution in desktop and mobile web, if there is no attribution server, no desire to set up cookie sync, or if redirecting from an app environment to a mobile web environment, the AUCTION_ID can be passed to the website in a landing page URL parameter using the {{AUCTION_ID}} macro in the click URL on the creative. The AUCTION_ID can then be grabbed from the landing page URL for usage in the data layer. The postback should then be fired at the point of conversion on the website.
- For viewthrough attribution, the AUCTION_ID may be passed to a server using the {{AUCTION_ID}} macro in an image pixel included on the creative.
For more custom attribution models, the desired AUCTION_ID can be obtained by looking up the corresponding USER_ID and timestamp info for the conversion in win logs.
Using Common Attribution Vendors
If using an attribution vendor such as Tune, Kochava, or Apsalar, it must be ensured that the Beeswax {{AUCTION_ID}} macro is used against the correct key within the respective attribution partner’s click URL tag. This key-value pair should be appended to the attribution partner’s click URL tag on the creative loaded in the Beeswax UI.
It is STRONGLY recommended that the device ID be passed to the attribution vendor using the {{IOS_ID_SHA1}}, {{ANDROID_ID_SHA1}}, or {{USER_ID_SHA1}} macros; otherwise, the vendors default to their fingerprinting technology, and significantly lower attribution will be seen.
An install action occurs when a device opens an advertiser app for the first time. If an affiliate, the postback must be provided to the client for installation in their app. Or, if an attribution toolset's SDK is installed, the parameters of the postback must be configured in that vendor's platform—more info on common vendors is below. When the app is opened for the first time, the postback is reported to Beeswax, and the Beeswax Auction ID that is passed will allow Beeswax to tie the conversion to a given campaign and line item.
Below are the latest configurations that are known for various partners. While efforts are made to keep these up to date, note that these may have been recently updated by the partner. It is recommended to correspond with support teams at those partners before installing a Beeswax postback to ensure it is done properly.
Branch Postback Configuration
Please see Branch documentation for specific guidance on tag handling. Customers who have a legacy TUNE SDK in their apps should also follow the Branch workflow for setting up postbacks.
- Branch’s instructions must be followed to configure postbacks in Branch for attribution reporting to Beeswax.
- Beeswax specific fields required for setup:
- The ‘Buzz Key’ field should be populated in the ‘Accounts Settings’ tab.
- The ‘Event ID’ fields should be populated in the ‘Postback Config’ tab with the relevant event ID from Beeswax.
- Once events have been set up, a new Ad Link should be generated by selecting ‘Create Beeswax Link’ and then selecting the type of link to create.
- Link parameters should be configured, and Beeswax should be selected as the ‘Ad Partner.’
- The click and impression Ad Links should be copied and added to the creatives.
Singular (Apsalar) Postback Configuration
Please see Singular documentation for guidance on partner configurations. See also singular link creation and legacy link generation.
- Singular click URL key-value for Beeswax Macro:
cl={{AUCTION_ID}}
- Users must follow Singular’s instructions to configure postbacks in Singular for attribution reporting to Beeswax.
- Once configured, use the Beeswax postback URL generated from the Conversion Event in Step 3 above. Example with Singular parameters below:
- https://cnv.event.prod.bidr.io/log/pbk?tag_id=[Event_ID]&buzz_key=[buzz_key]&value={AMOUNT}&auction_id={cl?Beeswax}
AppsFlyer Postback Configuration
Please see AppsFlyer documentation on integrated partner configurations
- In the Create Event screen in the UI, select "Generic URL for mobile app install Postback"
- Once in AppsFlyer, enter Beeswax as a partner on the configuration page and toggle on the "activate partner" switch:
- Once the "Set integration parameters" screen appears in the AppsFlyer user interface, fill in the Event_ID (the ID of the event object generated when saving the event in the UI from step 3 above) and the applicable buzz_key.
- For in-app events (NOTE: In-app events are not supported within Query Tool, and conversion data in Query Tool will be incorrect if also posting back in-app events. In-app events should only be used by clients who are receiving Conversion Logs or Real Time Win Logs.):
- Select "Only Beeswax attributed installs' in-app events"
- Insert the buzz_key
- Select the SDK event to capture and insert the corresponding event ID for that event
- AppsFlyer will pass us back the buzz_key, auction_ID, event_ID, and monetary value of the event. These values will show up in the corresponding columns of the conversion logs or messages in the real time win logs.
Adjust Postback Configuration
Please see this page for full details on how to setup postbacks using Adjust: How to Adjust with Beeswax
Kochava Postback Configuration
Please see Kochava documentation for specific guidance on Kochava system configurations
- App Install Events
- In the Create Event screen in the Buzz UI, select "Generic URL for mobile app install Postback"
- From the "Edit Postback: Install" screen in the Kochava user interface, fill in the TAG_ID (the ID of the Event object generated when saving the event in the UI from step 3 above) and the applicable Buzz Key.
- Post-install Events
In-app events are not supported within Query Tool, and conversion data in Query Tool will be incorrect if also posting back in-app events. In-app events should only be used by clients who are receiving Conversion Logs or Real Time Win Logs
- In the Create Event screen in the Buzz UI, select "Generic URL for mobile app install Postback"
- In the "Edit Postback: Purchase Event" screen in the Kochava user interface, fill in the TAG_ID (the ID of the Event object generated when saving the event in the Buzz UI from step 3 above), applicable Buzz Key (as this is case sensitive, ensure lower case is used), the order quantity (optional) and event value (optional)
Postback Attribution Without auction_id
The following applies to all MMPs/Attribution Partners.
If the mobile measurement partner (MMP) is unable to match a conversion event to an auction_id, a postback event containing the device ID can be sent to Beeswax. This will enable Beeswax to perform cross-device attribution based on the device_id.
To implement this, include the ios_id or android_id parameter in the postback URL, ensuring that it is correctly mapped to the appropriate device ID as specified in the MMP's documentation.
Example Postback URL:
[https://cnv.event.prod.bidr.io/log/pbk?tag_id=[Event_ID]&buzz_key=[buzz_key]&value={AMOUNT}&auction_id={cl?Beeswax}&ios_id={ios_id}]
These conversion events will also be eligible for cross-device attribution using the Freewheel ID graph. Conversion data will be available in the Conversion logs, and any user_id-based conversions will appear in the Attributed Conversion logs. In reporting, the Attribution Method dimension will categorize conversions as either 'CLICK_THROUGH' or 'VIEW_THROUGH,' depending on whether the corresponding impression received a click. In logs, the 'conversion_type' will be marked as 'NON_POSTBACK,' but clients can check the 'postback_url' field to determine if the conversion was sent via the postback mechanism.
- Note that in the scenario where there is both an auction_id and a device ID, Beeswax will default to using the auction_id and will not perform any further attribution based on the device ID.
- Note that the conversion type will be set to as ‘Non-postback’. Any Freewheel ID graph-attributed conversions will only be available via Report Builder. Enabling this feature (sending device IDs via postback URL) is expected to result in an increase in attributed conversions.
GDPR Changes for Mobile Attribution Vendors
In response to the upcoming GDPR regulations in the European Union, Beeswax is taking measures to ensure compliance. As part of this process, changes are required for integrations with mobile attribution vendors. Specifically, all creatives must use the SHA1 versions of our user ID macros instead of the original versions.
Beeswax is working with each integrated vendor to ensure their auto-generated click and impression URLs reflect these changes. For existing creatives running in EMEA, the clickthrough URLs must be updated accordingly. Creatives in other regions will not be impacted.
Kochava
• Add "&device_id_is_hashed=true&device_hash_method=sha1" to the URL
• Replace any identifier macro above with the same suffixed by SHA1
◦ e.g. "{{IOS_ID}}" becomes "{{IOS_ID_SHA1}}"
Tune
• Replace "ios_ifa={{USER_ID}} with "ios_ifa_sha1={{USER_ID_SHA1}}"
• Replace "google_aid={{USER_ID}}" with "google_aid_sha1={{USER_ID_SHA1}}"
AppsFlyer
• Replace "idfa={{USER_ID}}" with "sha1_idfa={{USER_ID_SHA1}}"
• Replace "android_id={{USER_ID}}" with "sha1_android_id={{USER_ID_SHA1}}"
Adjust
• Replace "idfa={{IOS_ID}}" with "idfa_lower_sha1={{IOS_ID_SHA1}}"
• Replace "gps_adid={{ANDROID_ID}}" with "gps_adid_lower_sha1={{ANDROID_ID_SHA1}}"
Postback Setup
Nothing should change with the postback setup. Beeswax uses the auction ID sent back by the partner to tie the conversion event to the impression. As such, no change needs to be made on that end to ensure that postback conversions continue to work.