Gravity Engine integration
Third-party callbacks increase project data volume. Check whether the selected events duplicate existing tracking.
Summary
Interface overview
| API | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Real-time API | Callback | User level | ✅ | ✅ | ✅ | ✅ |
Gravity Engine sends event batches, user properties, and attribution macro parameters as JSON via POST. ThinkingData converts them into event data and user property operations according to the project configuration.
Before integrating, read the user identification rules to understand how #distinct_id and #account_id are used. See the Gravity Engine documentation for the callback protocol.
Integration process
- Integrate and initialize the ThinkingData SDK to obtain a distinct ID. Integrate the Gravity Engine SDK and sync the ThinkingData identifiers to Gravity Engine user properties.
- Configure the gravityengine integration in ThinkingData. Set the user identification fields, event reporting, and user property mappings, then obtain the project callback URL.
- Enable event callbacks in the Gravity Engine console, select the required events, enter the POST URL, and add the attribution macro parameters described below.
- Trigger events as a test user. Verify the event name, time, user association, and user properties in ThinkingData before enabling production traffic.
1. Client SDK configuration
1.1 Integrate the Gravity Engine and ThinkingData SDKs
Select and initialize the SDKs for your platform. See the Gravity Engine client SDK documentation and the ThinkingData SDK integration guide. Method signatures depend on your SDK version. The following steps explain how to sync identifiers.
1.2 Sync user identifiers
- Initialize the ThinkingData SDK and retrieve the distinct ID.
- When initializing the Gravity Engine SDK, pass the ThinkingData distinct ID and the account ID if known. Gravity Engine stores them as the ta_distinct_id and ta_account_id user properties.
- After login or character sign-in, call login in the ThinkingData SDK and update ta_account_id using the Gravity Engine user property API. Keep the two systems in sync when switching accounts.
- Send a test callback and confirm that user_properties contains these fields. Event properties alone are insufficient.
{
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id"
}
}
Gravity Engine must send ta_distinct_id and should send the account ID when available. Conversion requires at least one valid identifier. The payload's client_id is a Gravity Engine identifier and does not replace the ThinkingData distinct ID.
2. Plan configuration
In the third-party integration area of your target environment, select Gravity Engine. The platform identifier is gravityengine. The following screen shows the configuration from the reference template.
2.1 User identification fields
| ThinkingData identifier | Recommended source field | Value resolution rules |
|---|---|---|
| Account ID (#account_id) | user_properties.ta_account_id | Read the payload path specified under Ingestion settings → User identification fields → Account ID first. If the result is empty, fall back to this field. |
| Distinct ID (#distinct_id) | user_properties.ta_distinct_id | Read the payload path specified under Ingestion settings → User identification fields → Distinct ID first. If the result is empty, fall back to this field. |
The two identifiers are resolved independently. If both are empty, no events or user operations are produced. Event properties such as $ta_account_id, $ta_distinct_id, and client_id do not override these sources.
2.2 Event Data Configuration
When event table ingestion is enabled, each object in events[] with a valid name and millisecond timestamp produces one event. Entries that are not objects, lack a name, or have an invalid timestamp are skipped without affecting valid entries. Select only the events your business needs to avoid duplicate data and unnecessary volume.
By default, ThinkingData removes the leading $ from events[].event and adds the gravity_ prefix. You can override event names in section 2.4.
2.3 User Properties Configuration
By default, AE writes Gravity Engine attribution values to the standardized user properties below.
| Gravity Engine field | Standardized field | Description |
|---|---|---|
| callback_params.channel | te_ads_object.media_source | Media source |
| callback_params.campaign_name | te_ads_object.campaign_name | Campaign name |
| callback_params.ad_name | te_ads_object.ad_name | Ad name |
| callback_params.ad_id | te_ads_object.ad_id | Ad ID |
To make changes, click Configure Rules to go to the ingestion rule configuration page, as shown below
To limit writes to specific events, disable Include all events and enter the source event names. AE then extracts user property values only from the selected callback events. The default operation is user_setOnce, which keeps the first reported value.
To turn off user property ingestion, stop all rules:
2.4 Configuration
You can specify event name mappings in the integration configuration.
2.5 End Point
POST https://<ThinkingData-ingestion-domain>/callback/integration/gravityengine/<ThinkingData-project-APPID>
Content-Type: application/json
Use the verified public ingestion domain and the target project's APPID for the Gravity Engine callback URL. The APPID in the path selects the ThinkingData project. The app_id in the payload identifies the Gravity Engine app. Project association through APPID does not provide strong authentication.
3. Configure callbacks in Gravity Engine
3.1 Configure event callbacks
In the Gravity Engine console, open the application's event callback settings, enable callbacks, and enter the parameters below.
3.2 Configure ad attribution macros
Configure the corresponding macros in the Gravity Engine console using the lowercase callback_params keys below. See the Gravity Engine attribution callback documentation. ThinkingData reads resolved values. It does not expand macros or look up missing ad data.
| Callback parameter | Gravity Engine macro | Description |
|---|---|---|
| advertiser_id | __ADVERTISER_ID__ | Advertiser account ID |
| campaign_id | __CAMPAIGN_ID__ | Campaign ID |
| campaign_name | __CAMPAIGN_NAME__ | Campaign name |
| ad_id | __AD_ID__ | Gravity Engine ad ID |
| ad_name | __AD_NAME__ | Gravity Engine ad name |
| creative_id | __CREATIVE_ID__ | Gravity Engine creative ID |
| creative_name | __CREATIVE_NAME__ | Gravity Engine creative name |
| ad_platform | __AD_PLATFORM__ | Media platform |
| csite | __CSITE__ | Ad placement |
| os_type | __OS_TYPE__ | Device Type |
For example, setting campaign_id to __CAMPAIGN_ID__ should produce callback_params.campaign_id="test-campaign-id" in the request. If a macro is missing or does not return a valid value, the corresponding field is omitted. A key without a $ prefix is not sent automatically.
Event and user macro parameters follow the same convention. See the Gravity Engine integration attachment for platform-specific event properties. The mini-program property $app_id is handled separately from the Gravity Engine app_id at the root of the payload.
3.3 Example callback payload
The sample IDs and historical timestamp illustrate the payload structure. For integration testing, use an actual test user, a current event timestamp, and the signature generated by Gravity Engine. user_properties is part of this specific integration agreement.
{
"app_id": "gravity-app-id",
"client_id": "gravity-client-id",
"sign": "<Gravity Engine signature>",
"events": [
{
"event": "$PayEvent",
"time": 1779439377000,
"properties": {
"$os": "iOS",
"$model": "iPhone 12",
"$country": "China",
"$pay_amount": 600,
"$pay_type": "CNY"
}
}
],
"callback_params": {
"channel": "campaign-a",
"advertiser_id": "ad-account-1",
"campaign_id": "campaign-1",
"campaign_name": "Test campaign",
"ad_id": "group-1",
"creative_id": "creative-1",
"ad_platform": "bytedance",
"os_type": "ios"
},
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id",
"$ad_count": 1
}
}
| Field | Type | Description |
|---|---|---|
| app_id、client_id | string | Gravity Engine app and client identifiers. They do not replace ThinkingData project or user identifiers. |
| events | array | Event batch containing event, time, and properties. It controls event output independently of user property rule execution. |
| events[].time | number | Positive integer Unix timestamp in milliseconds. Integer strings are accepted. The unit is not inferred from length. |
| events[].properties | object | Properties of the current event. |
| callback_params | object | Resolved macro parameters and custom parameters. |
| user_properties | object | ThinkingData identifiers and source values for user property mappings. |
4. Data ingestion
4.1 Event data ingestion rules
| Item | Rule |
|---|---|
| Event name | Remove the first leading $, normalize the name according to third-party naming rules, and prepend gravity_. For example, $PayEvent becomes gravity_PayEvent. If the original name matches a valid event_mapping entry, use the normalized mapped value without the prefix. |
| Event time | Convert events[].time from milliseconds to the service's local time and write #time. Write the offset in hours to #zone_offset in properties. Invalid times are not replaced by the current time. |
| Event properties | Merge callback_params first, then the current event properties. Event properties take precedence after mapping. Within the same source, an explicit property takes precedence over a $ alias, for example #os over $os and amount over $amount. |
| Root fields | When present and non-null, app_id and client_id populate properties.gravity_app_id and properties.gravity_client_id, preserving their original types and overwriting same-name inputs. Empty strings are retained. Missing or null values neither add nor remove these properties. |
| IP and source | Write the merged $ip or #ip to top-level #ip when it is a valid string. The callback server IP is not used as a fallback. #data_source_detail is fixed to GravityEngine and #zone_offset is calculated by the service. Input cannot override either. |
| Other fields | sign, the entire user_properties object, and events are not flattened into properties. Ordinary property names do not receive the gravity_ prefix. Numbers, booleans, arrays, and objects retain their JSON types. |
The example maps $PayEvent to pay_event. Without the mapping, it becomes gravity_PayEvent. In Asia/Shanghai, 1779439377000 corresponds to 2026-05-22 16:42:57.000 and #zone_offset=8. Other deployments use the service's configured time zone.
4.2 Preset event property mappings
The table retains 38 mappings from the original Gravity Engine integration. Values come from callback_params and the current event properties, with no defaults added. #ip is written at the event root. All other targets are written under properties.
| Gravity Engine source field | ThinkingData target field | Description |
|---|---|---|
| $ip | #ip | Top-level event field. The input must be a string. |
| $country | #country | Country |
| $province | #province | Province |
| $city | #city | City |
| $os | #os | Operating system |
| $os_version | #os_version | OS version |
| $manufacturer | #manufacturer | Manufacturer |
| $model | #device_model | Device model, using the established target field name. |
| $screen_width | #screen_width | Screen width |
| $screen_height | #screen_height | Screen height |
| $app_version | #app_version | App version |
| $carrier | #carrier | Carrier |
| $network_type | #network_type | Network type |
| $device_id | #device_id | Device identifier |
| $lib | #lib | SDK identifier |
| $lib_version | #lib_version | SDK version |
| $browser | #browser | Browser |
| $browser_version | #browser_version | Browser version |
| $scene | #scene | Scene value |
| $system_language | #system_language | System language |
| $bundle_id | #bundle_id | App bundle ID |
| $duration | #duration | Duration. Retains the original numeric type and unit of seconds. |
| $app_crashed_reason | #app_crashed_reason | Crash reason |
| $background_duration | #background_duration | Background duration. Retains the original value. |
| $element_content | #element_content | Element content |
| $element_id | #element_id | Element ID |
| $element_position | #element_position | Element position |
| $element_selector | #element_selector | Element selector |
| $element_type | #element_type | Element type |
| $resume_from_background | #resume_from_background | Resume from background |
| $scene_name | #scene_name | Scene name |
| $scene_path | #scene_path | Scene path |
| $screen_name | #screen_name | Page or screen name |
| $share_depth | #share_depth | Share depth |
| $start_reason | #start_reason | Launch reason |
| $title | #title | Page title |
| $url | #url | Page URL |
| $url_path | #url_path | URL path |
For unmapped $xxx fields, remove the first leading $ and normalize the name, for example $pay_amount → pay_amount and $brand → brand. $timezone_offset has no specified unit and is kept as timezone_offset. $event_duration is kept as event_duration. $user_id, $account_id, $distinct_id, $event_name, $event_time, and $server_time do not override the corresponding ThinkingData fields. Support for a preset # property does not imply that Gravity Engine sends it or that storage and internal fields can be overridden.

