Tenjin real-time callback API
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Real-time callback API | Callback | User level | ✅ | ✅ |
Tenjin provides a way to configure real-time callback links. By sending back activation events, you can get user-level attribution data.
Before you start connecting Tenjin real-time callback data, make sure that you have read the AE system's user identification rules and understand how AE identifies a user through #distinct_id and #account_id
Integration process
- Log in to the AE backend, go to the Third-party Integration module, add a Tenjin real-time callback API plan, and complete the related configuration
- Configure Webhooks in the Tenjin dashboard and pass in the AE callback link
- Check whether the AE system receives the data successfully, and build reports
1. Plan configuration
The first step in connecting Tenjin callback data is to log in to the AE backend and configure the Tenjin real-time callback API plan in the Third-party Integration module. The image below shows the configuration page of the Tenjin real-time callback API plan:
1.1 Event Data Configuration
After you turn on the Event Data Configuration switch, all data sent back by Tenjin is written to the event table. We recommend that you enable event data ingestion.
1.2 User Properties Configuration
By default, the AE system does not write data sent back by Tenjin to user properties. Because Tenjin does not contain the AE system's user identification fields, the callback data cannot be bound to AE users, so we do not recommend enabling user property ingestion
1.3 Configuration
In the Configuration module, you can control the detailed settings of data pulling, such as the event name after ingestion
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable. |
1.4 End Point
1.4.1 Default configuration
If you have configured system-level and project-level data reporting URLs, the following link is displayed. You can copy the URL directly:
If no URL is displayed here, open Project Settings → Settings → Implementation from the menu in the upper right corner and configure the URL for public network. This URL is the data reporting URL configured in the AE SDK. After configuring it, go back to End Point on the Tenjin real-time callback API configuration page and copy the endpoint URL.
1.4.2 Custom macros
The callback URL of the Tenjin real-time callback API contains a structure called a macro, written as {{macro_name}}. You can think of a macro as a placeholder: when the data that Tenjin needs to send back contains a field that corresponds to the macro, Tenjin fills in the value of that field where the macro is. Taking {{campaign_name}} as an example, when Tenjin sends back data, it fills in the value of Campaign where the macro is in the callback URL.
Replace the beginning of the following URL with the endpoint URL you just obtained, and copy the resulting callback URL. You will need to enter it in the Tenjin dashboard later:
https://{endpoint URL}?bundle_id={{bundle_id}}&platform={{platform}}&store_id={{store_id}}&time_in_ms={{time_in_ms}}&engaged_at_s={{engaged_at_s}}&acquired_at_ms={{acquired_at_ms}}&advertising_id={{advertising_id}}&developer_device_id={{developer_device_id}}&allow_ad_tracking={{allow_ad_tracking}}&ip_address={{ip_address}}&country={{country}}&campaign_name={{campaign_name}}&tenjin_campaign_id={{tenjin_campaign_id}}&click_id={{click_id}}&referrer={{referrer}}&site_id={{site_id}}&ad_network={{ad_network}}&device={{device}}&os_version={{os_version}}&app_version={{app_version}}&sdk_version={{sdk_version}}&language={{language}}&user_agent={{user_agent}}&creative_name={{creative_name}}&device_brand={{device_brand}}&device_model={{device_model}}&carrier={{carrier}}&locale={{locale}}&timezone={{timezone}}&tracking_status={{tracking_status}}
2. Tenjin dashboard configuration
2.1 Setup
First, log in to the Tenjin dashboard, select the app you want to configure under CONFIGURE - Apps, and click + New Callback to add a callback
Click Create Custom Callback in the upper right corner
- For the trigger event, select the App Open event
- For the trigger condition, you can select Ping on Every Install
- For the callback URL, you can enter the macros we recommend in section 1.4.2
After completing the configuration, you can see the configuration information shown in the image below. When Active shows true, the callback is configured
2.2 Recommended macros
Callback link macros are placeholder fields configured in the callback link. When data is sent back, Tenjin replaces these macros with the field values. Therefore, the macros determine which fields are sent back.
The following table lists the macros we recommend, which are also the macros used in the callback URL with macros provided in 1.4.2. You can visit the Tenjin official website for a more detailed list of macros. To adjust the macros, modify the Callback URL in the Tenjin callback yourself.
| Macro | Description |
|---|---|
| {{bundle_id}} | Bundle ID (such as com.tenjin.wordfinder) |
| {{platform}} | Platform |
| {{store_id}} | App Store ID (numeric part) |
| {{time_in_ms}} | Request time (milliseconds) |
| {{engaged_at_s}} | Timestamp of the click or impression (seconds) |
| {{acquired_at_ms}} | Timestamp of the install (milliseconds) |
| {{advertising_id}} | Advertising ID of the device |
| {{developer_device_id}} | IDFV or the developer's Device ID |
| {{allow_ad_tracking}} | Whether ad tracking is allowed (true means allowed, false means not allowed) |
| {{ip_address}} | IP address |
| {{country}} | Country code of the user's device |
| {{campaign_name}} | Attributed campaign name |
| {{tenjin_campaign_id}} | Attributed campaign ID |
| {{click_id}} | Click ID of the channel |
| {{referrer}} | Referrer on Android |
| {{site_id}} | Site ID of the channel |
| {{ad_network}} | Source channel name |
| {{device}} | Device model |
| {{os_version}} | OS version of the device |
| {{app_version}} | App version |
| {{sdk_version}} | Version of the Tenjin SDK |
| {{language}} | Language of the device |
| {{user_agent}} | User Agent of the device |
| {{creative_name}} | Creative name |
| {{device_brand}} | Device brand |
| {{device_model}} | Device model |
| {{carrier}} | Device carrier |
| {{locale}} | Locale information |
| {{timezone}} | Time zone of the device |
| {{tracking_status}} | ATT authorization status of the iOS device.
|
3. Data ingestion
3.1 Ingestion rules
- Because Tenjin does not contain the AE system's user identification fields, we use a fixed value as the user identifier. You can think of all data as attached to a single virtual user
- The time_in_ms field in the data is used as the event's #event_time
- The default event name is -- tenjin_callback
- All other fields configured in the callback link are stored
If you need to associate user-level callback data with AE users, record GAID and IDFA in user properties (we recommend recording them in a single user property), and then associate the Tenjin callback data with AE users through data backfilling
3.2 Standardized fields
The AE system standardizes some fields in Tenjin real-time callback data
| Original field | Standardized field | Description |
|---|---|---|
| campaign_name | te_ads_object.campaign_name | Campaign name |
| tenjin_campaign_id | te_ads_object.campaign_id | Campaign ID |
| creative_name | te_ads_object.ad_name | Ad name |
| ad_network | te_ads_object.media_source | Media source |
| bundle_id | te_ads_object.app_id | App ID |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| country | te_ads_object.country | Country or region code |