Gravity Engine 연동
서드파티 콜백은 프로젝트의 데이터량을 늘립니다. 선택한 이벤트가 기존 추적과 중복되는지 확인하세요.
개요
인터페이스 소개
| API | 타입 | 데이터 단위 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| 실시간 API | 콜백 | 유저 수준 | ✅ | ✅ | ✅ | ✅ |
Gravity Engine은 이벤트 배치, 유저 속성, 어트리뷰션 매크로 매개변수를 JSON 형식으로 POST합니다. ThinkingData는 프로젝트 설정에 따라 이를 이벤트 데이터와 유저 속성 작업으로 변환합니다.
연동 전 사용자 식별 규칙에서 #distinct_id와 #account_id의 용도를 확인하세요. 콜백 프로토콜은 Gravity Engine 공식 문서를 참고하세요.
통합 절차
- ThinkingData SDK를 연동하고 초기화하여 방문자 ID를 가져옵니다. Gravity Engine SDK를 연동하고 ThinkingData 식별자를 Gravity Engine 유저 속성과 동기화합니다.
- ThinkingData에서 gravityengine 연동을 구성합니다. 사용자 식별 필드, 이벤트 전송 및 유저 속성 매핑을 설정하고 프로젝트 콜백 URL을 가져옵니다.
- Gravity Engine 콘솔에서 이벤트 콜백을 활성화합니다. 필요한 이벤트를 선택하고 POST URL과 아래의 광고 어트리뷰션 매크로 매개변수를 설정합니다.
- 테스트 사용자로 이벤트를 발생시킵니다. ThinkingData에서 이벤트 이름, 시간, 사용자 연결 및 유저 속성을 확인한 후 운영 트래픽을 활성화합니다.
1. 클라이언트 SDK 설정
1.1 Gravity Engine 및 ThinkingData SDK 연동
대상 플랫폼에 맞는 SDK를 선택하고 초기화합니다. Gravity Engine 클라이언트 SDK 문서와 ThinkingData SDK 연동 가이드를 참고하세요. 메서드 시그니처는 SDK 버전에 따라 다릅니다. 아래 단계는 식별자 동기화 방법을 설명합니다.
1.2 사용자 식별자 동기화
- ThinkingData SDK를 초기화하고 방문자 ID를 가져옵니다.
- Gravity Engine SDK 초기화 시 ThinkingData 방문자 ID와 확인된 계정 ID를 전달합니다. Gravity Engine은 이를 유저 속성 ta_distinct_id와 ta_account_id에 저장합니다.
- 사용자가 로그인하거나 캐릭터가 접속한 후 ThinkingData SDK의 login을 호출하고 Gravity Engine 유저 속성 API로 ta_account_id를 업데이트합니다. 계정 변경 시에도 두 시스템의 식별자를 동기화합니다.
- 테스트 콜백을 보내 user_properties에 다음 필드가 있는지 확인합니다. 이벤트의 properties에만 식별자를 저장하면 충분하지 않습니다.
{
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id"
}
}
연동 규약에 따라 Gravity Engine은 ta_distinct_id를 보내고, 계정 ID를 사용할 수 있으면 함께 보냅니다. 변환하려면 유효한 식별자가 하나 이상 필요합니다. 본문의 client_id는 Gravity Engine 식별자로 ThinkingData 방문자 ID를 대체하지 않습니다.
2. 계획 설정
대상 환경의 서드파티 연동 메뉴에서 Gravity Engine을 선택합니다. 플랫폼 식별자는 gravityengine입니다. 다음 화면은 참조 템플릿에 해당하는 설정입니다.
2.1 유저 식별 필드
| ThinkingData 식별자 | 권장 소스 필드 | 값 가져오기 규칙 |
|---|---|---|
| 계정 ID(#account_id) | user_properties.ta_account_id | 수집 설정 → 사용자 식별 필드 → 계정 ID에 지정된 본문 경로를 먼저 읽습니다. 값이 비어 있으면 이 필드를 사용합니다. |
| 방문자 ID(#distinct_id) | user_properties.ta_distinct_id | 수집 설정 → 사용자 식별 필드 → 방문자 ID에 지정된 본문 경로를 먼저 읽습니다. 값이 비어 있으면 이 필드를 사용합니다. |
두 식별자는 각각 조회하고 대체 필드도 각각 적용합니다. 둘 다 비어 있으면 이벤트와 사용자 작업을 생성하지 않습니다. 이벤트 속성의 $ta_account_id, $ta_distinct_id 및 client_id는 이 식별자 소스를 덮어쓰지 않습니다.
2.2 이벤트 테이블 저장 설정
이벤트 테이블 수집을 켜면 유효한 이름과 밀리초 타임스탬프가 있는 events[] 객체마다 이벤트 하나가 생성됩니다. 객체가 아닌 항목, 이름이 없는 항목, 시간이 잘못된 항목은 건너뛰며 유효한 항목에는 영향이 없습니다. 중복과 데이터량 증가를 줄이려면 필요한 이벤트만 선택하세요.
기본적으로 events[].event의 맨 앞 $를 제거하고 gravity_ 접두사를 붙입니다. 이벤트 이름 매핑은 2.4 연동 설정에서 지정할 수 있습니다.
2.3 유저 속성 저장 규칙
기본적으로 AE는 Gravity Engine의 어트리뷰션 값을 아래의 표준화된 유저 속성에 기록합니다.
| Gravity Engine 필드 | 표준화 필드 | 설명 |
|---|---|---|
| callback_params.channel | te_ads_object.media_source | 미디어 채널 |
| callback_params.campaign_name | te_ads_object.campaign_name | 캠페인 이름 |
| callback_params.ad_name | te_ads_object.ad_name | 광고 이름 |
| callback_params.ad_id | te_ads_object.ad_id | 광고 ID |
수정이 필요하면 규칙 설정을 클릭하여 저장 규칙 설정 페이지로 이동합니다. 아래 그림과 같습니다
특정 이벤트에서만 속성을 쓰려면 모든 이벤트 포함을 끄고 소스 이벤트 이름을 입력합니다. AE는 지정한 콜백 이벤트에서만 유저 속성 값을 추출합니다. 기본 작업인 user_setOnce는 처음 보고된 값을 유지합니다.
유저 속성 저장을 끄려면 모든 규칙을 중지하면 됩니다:
2.4 통합 설정
연동 설정에서 이벤트 이름 매핑을 지정할 수 있습니다.
2.5 엔드포인트 주소
POST https://<ThinkingData-수신-도메인>/callback/integration/gravityengine/<ThinkingData-프로젝트-APPID>
Content-Type: application/json
검증한 공개 수신 도메인과 대상 프로젝트의 APPID를 Gravity Engine 콜백 URL에 사용합니다. 경로의 APPID는 ThinkingData 프로젝트를 지정하고 본문의 app_id는 Gravity Engine 앱을 식별합니다. APPID는 프로젝트 연결에 사용되며 강력한 인증 수단이 아닙니다.
3. Gravity Engine에서 콜백 설정
3.1 이벤트 콜백 설정
Gravity Engine 콘솔의 앱 관리에서 이벤트 콜백 설정을 열고 활성화한 뒤 아래의 매개변수를 입력합니다.
3.2 광고 어트리뷰션 매크로 설정
Gravity Engine 콘솔에서 아래의 소문자 callback_params 키에 대응하는 매크로를 설정합니다. 정의는 Gravity Engine 어트리뷰션 콜백 문서를 참고하세요. ThinkingData는 해석된 값을 읽으며 매크로를 치환하거나 누락된 광고 정보를 조회하지 않습니다.
| 콜백 매개변수 | Gravity Engine 매크로 | 의미 |
|---|---|---|
| advertiser_id | __ADVERTISER_ID__ | 광고주 계정 ID |
| campaign_id | __CAMPAIGN_ID__ | 캠페인 ID |
| campaign_name | __CAMPAIGN_NAME__ | 캠페인 이름 |
| ad_id | __AD_ID__ | Gravity Engine 광고 ID |
| ad_name | __AD_NAME__ | Gravity Engine 광고 이름 |
| creative_id | __CREATIVE_ID__ | Gravity Engine 크리에이티브 ID |
| creative_name | __CREATIVE_NAME__ | Gravity Engine 크리에이티브 이름 |
| ad_platform | __AD_PLATFORM__ | 미디어 플랫폼 |
| csite | __CSITE__ | 광고 게재 위치 |
| os_type | __OS_TYPE__ | 디바이스 타입 |
예를 들어 campaign_id를 __CAMPAIGN_ID__로 설정하면 요청에 callback_params.campaign_id="테스트 캠페인 ID"가 포함됩니다. 매크로를 설정하지 않았거나 유효한 값이 반환되지 않으면 해당 필드가 생성되지 않습니다. $가 없는 키도 자동으로 전송되지 않습니다.
이벤트와 사용자 매크로에는 동일한 규칙이 적용됩니다. 플랫폼별 이벤트 속성은 Gravity Engine 연동 문서의 첨부 파일을 참고하세요. 미니 프로그램의 $app_id는 본문 루트의 Gravity Engine 앱 app_id와 별도로 처리합니다.
3.3 콜백 데이터 예시
예시 ID와 과거 타임스탬프는 데이터 구조를 설명하기 위한 것입니다. 연동 테스트에는 실제 테스트 사용자, 현재 이벤트 시간 및 Gravity Engine에서 생성한 서명을 사용하세요. user_properties는 이번 연동에서 합의한 필드입니다.
{
"app_id": "gravity-app-id",
"client_id": "gravity-client-id",
"sign": "<Gravity Engine에서 생성한 서명>",
"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": "테스트 캠페인",
"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
}
}
| 필드 | 타입 | 설명 |
|---|---|---|
| app_id、client_id | string | Gravity Engine 앱 및 클라이언트 식별자입니다. ThinkingData 프로젝트 또는 사용자 식별자를 대체하지 않습니다. |
| events | array | event, time, properties를 포함한 이벤트 배치입니다. 이벤트 출력에만 영향을 주며 사용자 규칙의 실행 여부는 제어하지 않습니다. |
| events[].time | number | 밀리초 단위의 양의 정수 Unix 타임스탬프입니다. 정수 문자열도 허용하며 길이로 단위를 추정하지 않습니다. |
| events[].properties | object | 현재 이벤트의 속성입니다. |
| callback_params | object | 해석된 매크로 매개변수 및 사용자 정의 매개변수입니다. |
| user_properties | object | ThinkingData 식별자와 유저 속성 매핑에 사용할 원본 값입니다. |
4. 데이터 저장
4.1 이벤트 데이터 수집 규칙
| 항목 | 규칙 |
|---|---|
| 이벤트 이름 | 맨 앞의 $ 하나를 제거한 뒤 서드파티 이름 규칙으로 정규화하고 gravity_를 붙입니다. 예를 들어 $PayEvent는 gravity_PayEvent가 됩니다. 원래 이름에 유효한 event_mapping이 있으면 정규화한 매핑 값을 사용하며 접두사를 추가하지 않습니다. |
| 이벤트 시간 | events[].time의 밀리초 타임스탬프를 서비스의 현지 시간으로 변환해 #time에 기록하고 시간 단위 오프셋을 properties의 #zone_offset에 기록합니다. 잘못된 시간은 현재 시간으로 대체하지 않습니다. |
| 이벤트 속성 | callback_params를 먼저 병합한 다음 현재 이벤트의 properties를 병합합니다. 이름 매핑 후 이벤트 속성이 우선합니다. 같은 소스에서는 명시적 속성이 $ 별칭보다 우선합니다. 예를 들어 #os는 $os보다, amount는 $amount보다 우선합니다. |
| 루트 필드 | app_id와 client_id가 존재하고 null이 아니면 원래 유형을 유지하며 properties.gravity_app_id와 properties.gravity_client_id에 기록하고 같은 이름의 값을 덮어씁니다. 빈 문자열은 유지합니다. 값이 없거나 null이면 값을 추가하거나 병합된 동명 속성을 삭제하지 않습니다. |
| IP 및 데이터 소스 | 병합된 $ip 또는 #ip가 유효한 문자열이면 이벤트 루트의 #ip에 기록합니다. 콜백 서버 IP로 대체하지 않습니다. #data_source_detail은 GravityEngine으로 고정되며 #zone_offset은 서비스에서 계산합니다. 입력값으로 둘을 덮어쓸 수 없습니다. |
| 기타 필드 | sign, 전체 user_properties 및 events는 속성으로 자동 확장되지 않습니다. 일반 속성 이름에는 gravity_를 붙이지 않습니다. 숫자, 불리언, 배열 및 객체는 원래 JSON 유형을 유지합니다. |
예시에서는 $PayEvent를 pay_event로 매핑합니다. 매핑하지 않으면 gravity_PayEvent가 됩니다. Asia/Shanghai에서 1779439377000은 2026-05-22 16:42:57.000이며 #zone_offset=8입니다. 다른 환경에서는 서비스의 실제 시간대를 따릅니다.
4.2 이벤트 사전 정의 속성 매핑
아래 표는 기존 Gravity Engine 연동의 매핑 38개를 유지합니다. 값은 callback_params와 현재 이벤트 속성에서 가져오며 기본값을 추가하지 않습니다. #ip는 이벤트 루트에, 나머지는 properties에 기록합니다.
| Gravity Engine 소스 필드 | ThinkingData 대상 필드 | 설명 |
|---|---|---|
| $ip | #ip | 이벤트 루트에 기록합니다. 입력값은 문자열이어야 합니다. |
| $country | #country | 국가 |
| $province | #province | 주 또는 도 |
| $city | #city | 도시 |
| $os | #os | 운영 체제 |
| $os_version | #os_version | 운영 체제 버전 |
| $manufacturer | #manufacturer | 제조사 |
| $model | #device_model | 기기 모델입니다. 기존 대상 필드 이름을 유지합니다. |
| $screen_width | #screen_width | 화면 너비 |
| $screen_height | #screen_height | 화면 높이 |
| $app_version | #app_version | 앱 버전 |
| $carrier | #carrier | 통신사 |
| $network_type | #network_type | 네트워크 유형 |
| $device_id | #device_id | 기기 식별자 |
| $lib | #lib | SDK 식별자 |
| $lib_version | #lib_version | SDK 버전 |
| $browser | #browser | 브라우저 |
| $browser_version | #browser_version | 브라우저 버전 |
| $scene | #scene | 장면 값 |
| $system_language | #system_language | 시스템 언어 |
| $bundle_id | #bundle_id | 앱 번들 ID |
| $duration | #duration | 소요 시간입니다. 초 단위와 숫자 유형을 유지합니다. |
| $app_crashed_reason | #app_crashed_reason | 충돌 원인 |
| $background_duration | #background_duration | 백그라운드 시간입니다. 원래 값을 유지합니다. |
| $element_content | #element_content | 요소 콘텐츠 |
| $element_id | #element_id | 요소 ID |
| $element_position | #element_position | 요소 위치 |
| $element_selector | #element_selector | 요소 선택자 |
| $element_type | #element_type | 요소 유형 |
| $resume_from_background | #resume_from_background | 백그라운드에서 복귀 |
| $scene_name | #scene_name | 장면 이름 |
| $scene_path | #scene_path | 장면 경로 |
| $screen_name | #screen_name | 페이지 또는 화면 이름 |
| $share_depth | #share_depth | 공유 깊이 |
| $start_reason | #start_reason | 시작 이유 |
| $title | #title | 페이지 제목 |
| $url | #url | 페이지 URL |
| $url_path | #url_path | URL 경로 |
표에 없는 $xxx는 맨 앞의 $ 하나를 제거하고 이름을 정규화합니다. 예를 들어 $pay_amount → pay_amount, $brand → brand입니다. 단위가 정해지지 않은 $timezone_offset은 timezone_offset으로 유지하고 $event_duration은 event_duration으로 유지합니다. $user_id, $account_id, $distinct_id, $event_name, $event_time, $server_time은 대응하는 ThinkingData 필드를 덮어쓰지 않습니다. 사전 정의 # 속성이 지원되더라도 Gravity Engine의 전송이나 저장용 및 내부 필드의 덮어쓰기가 보장되는 것은 아닙니다.

