Skip to main content

Gravity Engine integration

Last updated 11/10/2026
tip

Third-party callbacks increase project data volume. Check whether the selected events duplicate existing tracking.

Summary​

Interface overview​

APITypeGranularityAttributionCostRevenueImpressionsClicksConversions
Real-time APICallbackUser 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​

  1. 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.
  2. Configure the gravityengine integration in ThinkingData. Set the user identification fields, event reporting, and user property mappings, then obtain the project callback URL.
  3. Enable event callbacks in the Gravity Engine console, select the required events, enter the POST URL, and add the attribution macro parameters described below.
  4. 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​

  1. Initialize the ThinkingData SDK and retrieve the distinct ID.
  2. 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.
  3. 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.
  4. 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 identifierRecommended source fieldValue resolution rules
Account ID (#account_id)user_properties.ta_account_idRead 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_idRead 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 fieldStandardized fieldDescription
callback_params.channelte_ads_object.media_sourceMedia source
callback_params.campaign_namete_ads_object.campaign_nameCampaign name
callback_params.ad_namete_ads_object.ad_nameAd name
callback_params.ad_idte_ads_object.ad_idAd 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 parameterGravity Engine macroDescription
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
}
}
FieldTypeDescription
app_id、client_idstringGravity Engine app and client identifiers. They do not replace ThinkingData project or user identifiers.
eventsarrayEvent batch containing event, time, and properties. It controls event output independently of user property rule execution.
events[].timenumberPositive integer Unix timestamp in milliseconds. Integer strings are accepted. The unit is not inferred from length.
events[].propertiesobjectProperties of the current event.
callback_paramsobjectResolved macro parameters and custom parameters.
user_propertiesobjectThinkingData identifiers and source values for user property mappings.

4. Data ingestion​

4.1 Event data ingestion rules​

ItemRule
Event nameRemove 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 timeConvert 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 propertiesMerge 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 fieldsWhen 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 sourceWrite 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 fieldssign, 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 fieldThinkingData target fieldDescription
$ip#ipTop-level event field. The input must be a string.
$country#countryCountry
$province#provinceProvince
$city#cityCity
$os#osOperating system
$os_version#os_versionOS version
$manufacturer#manufacturerManufacturer
$model#device_modelDevice model, using the established target field name.
$screen_width#screen_widthScreen width
$screen_height#screen_heightScreen height
$app_version#app_versionApp version
$carrier#carrierCarrier
$network_type#network_typeNetwork type
$device_id#device_idDevice identifier
$lib#libSDK identifier
$lib_version#lib_versionSDK version
$browser#browserBrowser
$browser_version#browser_versionBrowser version
$scene#sceneScene value
$system_language#system_languageSystem language
$bundle_id#bundle_idApp bundle ID
$duration#durationDuration. Retains the original numeric type and unit of seconds.
$app_crashed_reason#app_crashed_reasonCrash reason
$background_duration#background_durationBackground duration. Retains the original value.
$element_content#element_contentElement content
$element_id#element_idElement ID
$element_position#element_positionElement position
$element_selector#element_selectorElement selector
$element_type#element_typeElement type
$resume_from_background#resume_from_backgroundResume from background
$scene_name#scene_nameScene name
$scene_path#scene_pathScene path
$screen_name#screen_namePage or screen name
$share_depth#share_depthShare depth
$start_reason#start_reasonLaunch reason
$title#titlePage title
$url#urlPage URL
$url_path#url_pathURL 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.

Was this page helpful?