TopOn

이 문서에서는 TE에서 Adjust 데이터를 통합하는 방법에 대해 설명합니다.

현재 TE는 TopOn의 디바이스 리포트 API (opens new window)를 지원합니다.

::: Tip

주의. 플랫폼 데이터 통합을 통해 생성된 데이터는 클러스터의 데이터 소비량으로 계산됨을 유의하십시오.

:::

개요

API 이름	통합 유형	데이터 세분화	어트리뷰션	비용	수익	노출	클릭	전환
Device Reporting	API	유저			✅	✅	✅

디바이스 리포트 API (opens new window)에서는 유저를 기준으로 한 집계 지표를 얻을 수 있습니다. 이에는 일정 기간 내 유저의 총 노출 횟수, 클릭 횟수, 수익 데이터가 포함됩니다. 따라서 TE 시스템은 각 유저별로 매일 데이터를 개별적으로 취득합니다. 즉, 1 유저 당 하루 광고 노출 횟수, 클릭 횟수 및 수익 상황이 포함됩니다.

TopOn 데이터와 연동하기 전에, TE 시스템의 유저 식별 규칙에 대한 #distinct_id와 #account_id를 이해해 두십시오.

통합 절차

1. TopOn 클라이언트 SDK (opens new window)와 TE SDK에 연결하고, TopOn SDK에서 TE의 유저 식별 ID를 설정합니다.
2. TopOn의 백엔드에 로그인하여, Publisher Key와 APP Key를 얻습니다.
3. TE에 로그인하고, 서드파티 통합 페이지에서, TopOn의 통합을 추가하고 설정을 완료합니다.
4. TE 시스템이 데이터를 정상적으로 수신하고, 리포트 구축이 완료되었는지 확인합니다.

클라이언트 SDK 설정

TopOn 데이터를 통합하는 첫 번째 단계는, TE의 SDK와 TopOn의 SDK를 클라이언트 측에서 연결하고, AF의 SDK 내에서 TE 시스템의 유저 식별 ID를 설정하는 것입니다.

1.1 방법① (자동 통합)

• TE의 SDK의 버전이 2.8.0~2.8.1인 경우, 이 방법을 직접 사용할 수 있습니다.
• TE의 SDK의 버전이 2.8.2 이상이면, 서드파티 데이터 플러그인을 설치해야 합니다. 자세한 사항은 Android SDK과 iOS SDK를 참조하십시오.

이 플랜은 자동 통합 방법으로, TE 클라이언트 SDK를 초기 설정한 후에 아래의 코드를 호출하여 시작하십시오.

// TE SDK 초기화
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// TopOn ID 연결 활성화.
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);

// TopOn SDK 초기화
// ...


// 등록이나 캐릭터 생성 후, 로그인을 호출하여 계정 ID를 설정한 후, 데이터를 다시 동기화하는 것이 필요합니다 (선택사항).
instance.identify("distinct_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);

이 방법의 원리는 내부에서 AT SDK의 initCustomMap 메소드를 자동으로 호출하고, AT CustomRuleKeys.USER_ID를 전달하며, 값으로 TE 프로젝트의 게스트 ID를 전달하는 것입니다.

1.2 방법② (수동 통합)

TopOn의 앱 전체에 걸친 커스텀 규칙 설정을 사용하고, TE의 distinct_id를 TopOn SDK의 custom_rule 내의 user_id로 전달합니다.

iOS 클라이언트 코드 예시：

[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:self.TA_DISTINCT_ID}];

Android 클라이언트 코드 예시：

Map<String, String> customMap = new HashMap<>(); 
customMap.put(ATCustomRuleKeys.USER_ID,"ta_distinct_id"); 
ATSDK.initCustomMap(customMap);

::: 주의（매우 중요）

setCustomData（iOS）메소드 또는 initCustomMap（Android）를 사용하여 전송할 때, TopOn SDK의 초기화 전에 완료해야 합니다. 그렇지 않으면, 일부 user_id를 얻지 못할 수 있습니다.

:::

TopOn 백엔드 정보 획득

SDK의 설정이 완료되면, TopOn 백엔드에 로그인하여, 데이터를 획득하기 위해 필요한 인증 정보를 얻어야 합니다. 인증 정보를 획득하기 위해서는 먼저 TopOn의 담당자에게 연락하여, 디바이스 레벨의 데이터 리포트 API 접근 권한을 신청해야 합니다. 허가된 후, 개발자 대시보드의 계정 관리 페이지에서 Publisher Key와 App Key를 확인할 수 있습니다. 이 두 정보를 복사하여, 다음에 TE 시스템 구성에서 사용합니다.

TE의 서드파티 통합 설정

SDK의 설정이 완료되면, 다음에 TE에 로그인하여 '서드파티'에서 TopOn의 설정을 완료해야 합니다. 아래는 TopOn의 설정 페이지입니다. '통합 스위치'를 열어 TopOn의 설정을 시작하십시오.

3.1 유저의 식별 및 연결

TopOn은 커스텀 유저 ID 필드만 반환할 수 있으므로 식별 필드 변경을 허용하지 않습니다. 이 문서에 따라 클라이언트 SDK 구성을 완료해야 합니다. TopOn 데이터 내의 user_id는 TE 시스템의 게스트 ID로 식별됩니다.

3.2 통합 파라미터

다음으로, 데이터를 얻기 위한 설정을 해야 합니다. 주요 구성은 두 가지입니다:

• 데이터 연동 시간대 선택: UTC-9, +9, ±0의 세 가지 시간대를 선택할 수 있습니다.
• 동기화 : TE 시스템은 동기화 설정을 할 수 있습니다. 매일 또는 시간마다 일정 기간 동안 데이터를 연동할 수 있습니다. 단, TopOn 장치 수준의 데이터 리포트 API는 과거 29일간의 데이터만 지원합니다.
  

3.3 통합 계획 생성

데이터를 연동하기 위해서는 통합 계획을 생성하고 TopOn 백엔드에서 획득한 인증 정보를 통합 계획에 입력해야 합니다. 다음 그림처럼 계획명을 설정하고 Publisher Key와 App Key를 입력하세요.

3.4 설정 저장 및 한 번 획득

마지막으로, 위의 설정이 모두 정확하게 입력되었는지 확인하고 페이지 오른쪽 하단의 '저장'을 클릭하세요. 이로써 TopOn의 통합 설정 작업이 완료됩니다.

설정을 저장한 후, 페이지 오른쪽 위에 있는 '단일 당김' 버튼을 클릭하고 데이터 연동을 수동으로 실행하는 것이 좋습니다. 팝업에서 필요한 데이터 범위와 어떤 계획이 필요한지 설정하세요.

데이터 저장 규칙

4.1 유저 식별 규칙

TopOn API의 데이터 필드 제한으로 인해, TopOn API의 유저 식별 규칙은 고정되어 있습니다:

• 계정 ID: 확인하지 않고, 공백으로 둡니다.
• 게스트 ID: user_id가 존재하는지 확인하고, 존재하면 그것을 #distinct_id로 설정합니다. 존재하지 않으면, 이 데이터는 무효한 데이터로 간주되고 직접 폐기됩니다.

4.2 이벤트 저장 규칙

• TE 시스템은 매일 0시를 이벤트의 #event_time으로 취급합니다.
• 이벤트 이름: -- ta_ad_revenue_topon
• 기타 필드는 모두 저장됩니다.

4.3 필드

TopOn의 데이터에는 다음과 같은 이벤트 속성이 포함됩니다. 일부 필드는 TE 시스템에 의해 표준화 처리됩니다.

필드	설명	표준화 필드
placement_id	광고 플레이스 ID
placement_name	광고 플레이스 이름	te_ads_object.placement
placement_format	광고 유형: 0: native; 1: rewarded_video; 2: banner; 3: interstitial; 4: splash
android_id	장치 ID, androidid
gaid	Google의 광고 장치 ID
idfa	iOS의 장치 ID
area	국가(지역)
impression	노출 수
click	클릭 수
revenue	수익은, 3개의 광고 플랫폼에 기반하여 장치 수준으로 분할되며, 통화 단위는 개발자의 백엔드 구성과 동일합니다.	te_ads_object.revenue
ecpm	TopOn은 수익 API에 기반하여, 장치의 노출당 분할된 수익과 TopOn이 통계한 장치의 노출에서 eCPM을 계산합니다. 계산식: (장치 수익 / TopOn이 통계한 노출 장치) * 1000. 주의: eCPM은 2일 지연으로 제공됩니다.
is_abtest	대조 그룹 또는 실험 그룹: 0: 대조 그룹 또는 A/B 테스트가 설정되지 않음 1: 실험 그룹
traffic_group_id	대상 그룹 또는 실험 그룹 ID
segment_id	트래픽 세그먼트 ID
segment_name	트래픽 세그먼트 이름
idfv	iOS의 장치 ID
oaid	Android의 장치 ID
user_id	개발자의 커스텀 유저 ID
network_firm_id	광고 플랫폼 ID
network_firm	광고 플랫폼 명칭	te_ads_object.media_source
currency	개발자 계정의 통화 코드	te_ads_object.currency
os_version	iOS 디바이스의 운영 OS
att_status	iOS 장치의 ATT 권한 상태: 0: Not determined(권한 미정); 1: Restricted (제한); 2: Denied(거부됨); 3: Authorize(권한 있음)
imei	Android의 장치 식별 코드
device_type	iOS의 장치 유형: 0: 비iOS 장치; 1: iPhone; 2: iPad
brand	장치의 브랜드 이름
model	장치의 모델
app_vn	앱 버전 이름
app_vc	앱 버전
new_user_type	신규 유저 여부: 1: 신규 유저; 2: 신규 유저가 아님
channel	채널, TopOn SDK를 통해 개발자가 입력한 채널
estimate_revenue	추정 수익은, 입찰 광고 소스에서 실시간 광고 노출 가격을 집계하여 추정 수익을 계산하고, 비입찰 광고 소스는 TopOn이 통계한 노출 수에 인위적으로 설정된 eCPM 가격을 곱하여 추정 수익을 계산합니다.

4.4 유저 속성 저장 규칙

현재, TopOn은 사용자 속성의 데이터 저장 규칙을 지원하지 않습니다.

후속 사용

5.1 데이터 저장 검증

마지막으로 TE 시스템이 TopOn의 데이터를 수신했는지 확인하세요. 다음 방법에 따라 확인할 수 있습니다:

• '데이터 관리' - '데이터' 페이지에서, ta_ad_revenue_topon 이벤트가 생성되었는지 확인하세요.
• 이벤트 분석 모델에서 ta_ad_revenue_topon에 데이터가 있는지 확인할 수도 있습니다.

5.2 리포트 제안

다음은 리포트를 구축하기 위한 몇 가지 제안입니다.

1. 이벤트 분석 모델에서 TopOn의 데이터를 사용하여 광고 수익의 핵심 지표를 구축하고, 광고 분석 리포트를 작성합니다.
2. 잔존 분석 모델에서, TopOn의 데이터를 활용하여 광고 수익 정보와 게임 내 결제 이벤트를 결합하여, 광고 수익을 포함한 LTV를 계산합니다.