본문으로 건너뛰기

Gravity Engine 연동

최근 업데이트 2026. 11. 10.
팁

서드파티 콜백은 프로젝트의 데이터량을 늘립니다. 선택한 이벤트가 기존 추적과 중복되는지 확인하세요.

개요​

인터페이스 소개​

API타입데이터 단위어트리뷰션비용수익노출클릭전환
실시간 API콜백유저 수준✅✅✅✅

Gravity Engine은 이벤트 배치, 유저 속성, 어트리뷰션 매크로 매개변수를 JSON 형식으로 POST합니다. ThinkingData는 프로젝트 설정에 따라 이를 이벤트 데이터와 유저 속성 작업으로 변환합니다.

연동 전 사용자 식별 규칙에서 #distinct_id와 #account_id의 용도를 확인하세요. 콜백 프로토콜은 Gravity Engine 공식 문서를 참고하세요.

통합 절차​

  1. ThinkingData SDK를 연동하고 초기화하여 방문자 ID를 가져옵니다. Gravity Engine SDK를 연동하고 ThinkingData 식별자를 Gravity Engine 유저 속성과 동기화합니다.
  2. ThinkingData에서 gravityengine 연동을 구성합니다. 사용자 식별 필드, 이벤트 전송 및 유저 속성 매핑을 설정하고 프로젝트 콜백 URL을 가져옵니다.
  3. Gravity Engine 콘솔에서 이벤트 콜백을 활성화합니다. 필요한 이벤트를 선택하고 POST URL과 아래의 광고 어트리뷰션 매크로 매개변수를 설정합니다.
  4. 테스트 사용자로 이벤트를 발생시킵니다. ThinkingData에서 이벤트 이름, 시간, 사용자 연결 및 유저 속성을 확인한 후 운영 트래픽을 활성화합니다.

1. 클라이언트 SDK 설정​

1.1 Gravity Engine 및 ThinkingData SDK 연동​

대상 플랫폼에 맞는 SDK를 선택하고 초기화합니다. Gravity Engine 클라이언트 SDK 문서와 ThinkingData SDK 연동 가이드를 참고하세요. 메서드 시그니처는 SDK 버전에 따라 다릅니다. 아래 단계는 식별자 동기화 방법을 설명합니다.

1.2 사용자 식별자 동기화​

  1. ThinkingData SDK를 초기화하고 방문자 ID를 가져옵니다.
  2. Gravity Engine SDK 초기화 시 ThinkingData 방문자 ID와 확인된 계정 ID를 전달합니다. Gravity Engine은 이를 유저 속성 ta_distinct_id와 ta_account_id에 저장합니다.
  3. 사용자가 로그인하거나 캐릭터가 접속한 후 ThinkingData SDK의 login을 호출하고 Gravity Engine 유저 속성 API로 ta_account_id를 업데이트합니다. 계정 변경 시에도 두 시스템의 식별자를 동기화합니다.
  4. 테스트 콜백을 보내 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.channelte_ads_object.media_source미디어 채널
callback_params.campaign_namete_ads_object.campaign_name캠페인 이름
callback_params.ad_namete_ads_object.ad_name광고 이름
callback_params.ad_idte_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_idstringGravity Engine 앱 및 클라이언트 식별자입니다. ThinkingData 프로젝트 또는 사용자 식별자를 대체하지 않습니다.
eventsarrayevent, time, properties를 포함한 이벤트 배치입니다. 이벤트 출력에만 영향을 주며 사용자 규칙의 실행 여부는 제어하지 않습니다.
events[].timenumber밀리초 단위의 양의 정수 Unix 타임스탬프입니다. 정수 문자열도 허용하며 길이로 단위를 추정하지 않습니다.
events[].propertiesobject현재 이벤트의 속성입니다.
callback_paramsobject해석된 매크로 매개변수 및 사용자 정의 매개변수입니다.
user_propertiesobjectThinkingData 식별자와 유저 속성 매핑에 사용할 원본 값입니다.

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#libSDK 식별자
$lib_version#lib_versionSDK 버전
$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_pathURL 경로

표에 없는 $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의 전송이나 저장용 및 내부 필드의 덮어쓰기가 보장되는 것은 아닙니다.

이 문서가 도움이 되었나요?