Reyun TrackingIO integration plan
This article describes how to connect Reyun TrackingIO data in the AE backend. The AE backend supports ingesting Reyun TrackingIO real-time callback data
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 | Callback | User level | ✅ |
Before you start connecting Reyun TrackingIO 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
Currently, Reyun TrackingIO provides callbacks for activation, registration, login, payment, and custom events. For details, see the Reyun TrackingIO callback link documentation.
We recommend that you ingest activation or registration callback data to get customers' attribution information. Because the callback link must be configured by Reyun technical staff, get all the necessary information as described in this section, and then contact Reyun technical staff to configure the callback.
Integration process
- Integrate the Reyun TrackingIO SDK and the AE SDK, and pass in the distinct ID of the AE SDK when calling the registration method of the Reyun SDK
- Log in to the AE backend, go to the Third-party Integration module, add a Reyun TrackingIO integration, complete the related configuration, and copy the callback URL
- Provide the app's APP_ID and Secret, the callback URL, and the callback data types to Reyun technical staff, who will help you configure data callbacks
- Check whether the AE system receives the data successfully, and build reports
1. Client SDK configuration
1.1 Integrate the Reyun SDK and the AE SDK
First, integrate the Reyun TrackingIO SDK and the AE SDK into your app and complete the initialization configuration. The integration documentation for the Reyun TrackingIO SDK and the AE SDK is as follows:
1.2 Configure the SDK
After integrating the SDKs, set the distinct ID and account ID of the AE SDK in the Reyun SDK. Decide in advance which events you want to send back, and complete the SDK configuration according to the corresponding parts of this section
1.2.1 Activation event
In the activation event, you can set the distinct ID of the AE SDK as a custom property. The following is a code sample for Android:
// Initialize the AE SDK
//...
// Report the activation event with Reyun
// Create the initialization parameter object
InitParameters parameters = new InitParameters();
// Initialization parameter appkey, required
parameters.appKey = "appkey";
// Initialization parameter channelId, required
parameters.channelId = "320110";
// Initialization parameter oaid. If oaid is passed in, the Reyun SDK no longer calls the MSA APIs to get the OAID
parameters.oaid = "hahahahahahaha";
// Initialization parameter assetFileName, required when you use OAID version 1.0.26 or later
parameters.assetFileName = "com.reyun.chicken.cert.pem";
// Initialization parameter oaidLibraryString, required when you use OAID version 1.0.26 or later
// According to the MSA documentation, the value is nllvm1623827671 for 1.0.26, nllvm1630571663641560568 for 1.0.27, and msaoaidsec for 1.0.30 and later
parameters.oaidLibraryString = "msaoaidsec";
// Get the distinct ID of the AE SDK
String distinctId = TDAnalytics.getDistinctId();
// Set the distinct ID of the AE SDK in the custom parameters
HashMap<String, Object> params = new HashMap<>();
params.put("param6", distinctId);
parameters.installParams = params;
Tracking.initWithKeyAndChannelId(getApplication(), parameters);
1.2.2 Registration event
Similarly, when reporting the registration event, you can pass in the account ID and distinct ID of the AE SDK as custom properties:
// Initialize the AE SDK and the Reyun SDK
// ...
// Get the account ID and distinct ID of the AE SDK
String teAccountId = "account_id";
String teDistinctId = TDAnalytics.getDistinctId();
// Report the registration event and pass the account ID and distinct ID of the AE SDK
HashMap<String, Object> params = new HashMap<>();
params.put("param6", teDistinctId);
params.put("param7", teAccountId);
Tracking.setRegisterWithAccountID("account_id", params);
1.2.3 Custom events
Reporting custom events is similar to reporting the registration event. Get the account ID and distinct ID of the AE SDK, and pass them in the custom event reporting API of the Reyun SDK:
// Initialize the AE SDK and the Reyun SDK
// ...
// Get the account ID and distinct ID of the AE SDK
String teAccountId = "account_id";
String teDistinctId = TDAnalytics.getDistinctId();
// Report a custom event and pass the account ID and distinct ID of the AE SDK
HashMap<String, Object> params = new HashMap<>();
params.put("param6", teDistinctId);
params.put("param7", teAccountId);
Tracking.setEvent("event_1", params);
2. Plan configuration
After completing the SDK configuration, log in to the AE backend and complete the Reyun TrackingIO configuration in the Third-party Integration module. The image below shows the Reyun TrackingIO configuration page. Follow this section to create the plan:
2.1 User identification fields
Because Reyun sends back user-level data, you need to set user identification rules for it, that is, the fields in the callback data that correspond to #distinct_id and #account_id. Based on this configuration, the AE system sets these fields as the user identification fields of the data when it converts the callback data.
If you configured the client SDK as described in the previous step of this document, you can use the default values directly:
- Field associated with the account ID: param7
- Field associated with the distinct ID: param6
2.2 Event Data Configuration
After you turn on the Event Data Configuration switch, all data sent back by Reyun is written to the event table. We recommend that you enable event data ingestion.
2.3 User Properties Configuration
By default, the AE system automatically writes the attribution fields in the Reyun callback data to standardized user properties. The following are the fields written to user properties and their meanings:
| Reyun field | User property name in AE | Description |
|---|---|---|
| ry_adgroup_name | te_ads_object.ad_group_name | Text |
| channel | te_ads_object.media_source | Text |
| ry_adplan_name | te_ads_object.campaign_name | Text |
| ry_adcreative_name | te_ads_object.ad_name | Text |
The default user property ingestion rules in earlier versions differ from the current ones, so be careful to distinguish them. To merge the old and new properties, you can use the custom property feature
To make changes, click Configure Rules to go to the ingestion rule configuration page, as shown below
Here, you can change which events user properties come from and the Integration method. The default Integration method is user_setOnce, which means only the first reported information is kept.
Click the Property Mapping button to add fields to write to user properties. You can also click the Rule button on the left to add a new set of rules.
To turn off user property ingestion, stop all rules:
2.4 End Point
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 Reyun configuration page and copy the endpoint URL.
2.5 Configuration
Finally, in the integration configuration module, you can control the details 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_mapping | Event name after ingestion. Customizable. Supported keys:
|
2.6 Event ingestion rules
-
The activetime field in the data is used as the event's #event_time
-
The default event names of the callback data are as follows. You can change them by modifying sink_event.event_mapping:
- Activation event: reyun_init
- Registration event: reyun_sign_up
- Login event: reyun_login
- Payment event: reyun_payment
- Custom events: the event name prefixed with reyun_, such as reyun_event_1
-
All other fields are ingested. The Reyun callback data contains the following fields:
| Reyun callback field | Type | Description | Remarks |
|---|---|---|---|
| spreadurl | Text | Promotion campaign short link | Click parameters. These fields are not returned for ASA-attributed or organic users |
| spreadname | Text | Promotion campaign name | |
| channel | Text | Channel Name | |
| clicktime | Text | Click receipt time | |
| uip | Text | Click IP | |
| csite | Text | Ad unit ID | |
| ry_adgroup_id | Text | Ad group ID | |
| ry_adgroup_name | Text | Ad group name | |
| ry_adplan_id | Text | Campaign ID | |
| ry_adplan_name | Text | Campaign name | |
| ry_adcreative_id | Text | Ad creative ID | |
| ry_adcreative_name | Text | Ad creative name | |
| advert_id | Text | Ad ID | Ocean Engine 2.0 only |
| advert_name | Text | Ad name | Ocean Engine 2.0 only |
| project_id | Text | Project ID | Ocean Engine 2.0 only |
| project_name | Text | Project name | Ocean Engine 2.0 only |
| mid1 | Text | Image material ID | Ocean Engine 2.0 only |
| mid2 | Text | Title material ID | Ocean Engine 2.0 only |
| mid3 | Text | Video material ID | Ocean Engine 2.0 only |
| mid4 | Text | Bundled playable material ID | Ocean Engine 2.0 only |
| mid5 | Text | Landing page material ID | Ocean Engine 2.0 only |
| mid6 | Text | Android download detail page material ID | Ocean Engine 2.0 only |
| accountid | Text | Delivery account ID | Media-side delivery account |
| requestid | Text | Ad request ID | Ocean Engine common parameter |
| convertid | Text | Conversion ID | Ocean Engine common parameter |
| appkey | Text | Unique identifier of the Reyun app | |
| activetime | Text | Event receipt time | |
| what | Text | Event type | Activation: install |
| osversion | Text | OS version | |
| ryos | Text | OS | |
| devicetype | Text | Device Type | |
| deviceid | Text | Device ID | |
| Idfa | Text | IDFA on iOS | |
| idfv | Text | IDFV on iOS | |
| imei | Text | IMEI on Android. Unavailable on Android 10 and later | |
| oaid | Text | OAID | |
| androidid | Text | Android ID | |
| aip | Text | Conversion event IP | |
| skey | Text | The securitykey request parameter. Has no meaning | |
| attribution | Text | ASA attribution | ASA parameters. Returned only for ASA ad attribution |
| orgid | Text | Campaign group ID | |
| campaignid | Text | Campaign ID | |
| clickdate | Text | ASA ad click time | |
| adgroupid | Text | Ad group ID | |
| keywordid | Text | Keyword ID | |
| creativesetid | Text | Material ID (creative ID) | |
| conversiontype | Text | Conversion type: new install or reinstall | |
| account | Text | Account ID set during registration | Included only in registration events |
| param1~param10 | Text | Custom parameters | By default, we recommend using param6 for the distinct ID of the AE SDK and param7 for the account ID |
2.7 Standardized fields
The following fields in the Reyun callback data are standardized:
| Callback field | Standardized field | Description |
|---|---|---|
| channel | te_ads_object.media_source | Channel Name |
| csite | te_ads_object.placement | Ad unit ID |
| ry_adgroup_id | te_ads_object.ad_group_id | Ad group ID |
| ry_adgroup_name | te_ads_object.ad_group_name | Ad group name |
| ry_adplan_id | te_ads_object.campaign_id | Campaign ID |
| ry_adplan_name | te_ads_object.campaign_name | Campaign name |
| ry_adcreative_id | te_ads_object.ad_id | Ad creative ID |
| ry_adcreative_name | te_ads_object.ad_name | Ad creative name |
| advert_id | te_ads_object.ad_id | Ad ID |
| advert_name | te_ads_object.ad_name | Ad name |
3. Contact Reyun technical staff to configure callbacks
Next, contact Reyun staff to enable callbacks. Generally, you need to provide Reyun with the following four pieces of information:
| Messages | Description | Example |
|---|---|---|
| Callback data type | The callback data you need to ingest | |
| Callback link | The URL where the AE system receives callback data. Get it on the integration configuration page | https://{receiver-host}/attribution/callback/reyun/{app-id} |
| appkey | Unique identifier of the advertiser's product in the Reyun backend. Get it from the Reyun backend | f819f9cac******812b2067d0cf8 |
| securitykey | Security verification field. Currently not supported by AE; the advertiser can customize it | abc123 |
4. Next steps
4.1 Check data ingestion
Finally, check whether the AE system has received the Reyun callback data. You can check as follows:
- View in detailed data
If the platform connection status is Connected, data has been received from the platform and ingested. In this case, hover over the plan's card in the Third-party Integration list and click the details icon to go to the plan details page, where you can view the latest 1000 records received. Click a row to view the details of that record, including the data before and after conversion. You can copy or export the record, or click Download full data in the upper-right corner of the details page to download the complete data:
- View in other product modules
Besides the integration page, you can also check on the Management page whether the callback events and user properties have been created.
You can also check whether the data has been stored by running analyses in analysis models, such as the Events Analysis model and the Composition Analysis model.
4.2 Recommended reports
Here are a few suggestions for building reports:
- In each model, use the user attribution fields sent back by Reyun to compare audiences and analyze differences in in-game behavior among users from different sources
- In the Retention Analysis model, use the attribution information sent back by Reyun to compare the LTV of users from different sources