TradPlus 디바이스 수준 데이터 리포트 API
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| 디바이스 수준 데이터 리포트 API | API | 유저 수준 | ✅ | ✅ | ✅ |
디바이스 수준 데이터 리포트 API는 유저 수준의 광고 수익화 데이터를 제공하며, 특정 일자의 유저별 광고 노출 횟수, 클릭 수, 수익 등의 지표가 포함됩니다.
통합 절차
- TradPlus 클라이언트 SDK와 AE SDK를 연동하고, TradPlus SDK에 AE의 유저 식별 ID를 설정합니다
- TradPlus 백엔드에 로그인하여 Access Token과 앱 ID를 가져옵니다
- AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 TradPlus 디바이스 수준 데이터 리포트 API 통합 계획을 추가합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. 클라이언트 SDK 설정
TradPlus 데이터 통합의 첫 단계는 클라이언트에서 AE SDK와 TradPlus SDK를 연결하여 TradPlus SDK에 AE 시스템의 유저 식별 ID를 설정하는 것입니다
1.1 방안 1(자동 통합)
-
Android, iOS SDK를 연동한 경우
- SDK 버전이 2.8.0~2.8.1이면 이 방안을 바로 사용할 수 있습니다
- SDK 버전이 2.8.2 이상이면 서드파티 데이터 플러그인도 설치해야 합니다. 자세한 내용은 Android SDK 서드파티 데이터와 iOS SDK 서드파티 데이터를 참고하십시오
-
Unity SDK 버전 2.4.0 이상, Unreal SDK 버전 1.5.0 이상을 연동한 경우 이 방안을 바로 사용할 수 있습니다
AE SDK 초기화와 자동 통합 활성화 코드는 반드시 TradPlus SDK 초기화 전에 완료해야 합니다. 다음 단계에 따라 진행하십시오:
1. AE SDK를 초기화합니다.
2. `enableThirdPartySharing`을 호출하여 게스트 ID를 자동으로 설정합니다.
3. TradPlus SDK를 초기화합니다.
다음은 각 플랫폼 SDK의 코드 예시입니다:
- Android
- iOS
- Unity
- Unreal
// 1. Android SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. enableThirdPartySharing 인터페이스를 호출하여 ta_distinct_id를 TradPlus 이벤트에 설정
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.TRAD_PLUS);
// 3. TradPlus SDK 초기화
// ...
// 1. iOS SDK 초기화
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. enableThirdPartySharing 인터페이스를 호출하여 ta_distinct_id를 TradPlus 이벤트에 설정
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeTradPlus];
// 3. TradPlus SDK 초기화
// ...
// 1. Unity SDK 초기화
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. enableThirdPartySharing을 호출하여 ta_distinct_id를 TradPlus 이벤트에 설정
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.TRADPLUS);
// 3. TradPlus SDK 초기화
// ...
// 1. Unreal SDK 초기화
UTDAnalytics::Initialize();
// 2. enableThirdPartySharing을 호출하여 ta_distinct_id를 TradPlus 이벤트에 설정
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeTRADPLUS"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);
// 3. TradPlus SDK 초기화
// ...
이 방안의 원리는 내부에서 TradPlus의 내부 메서드를 자동으로 호출하여 AE SDK의 게스트 ID를 TradPlus SDK의 userId(디바이스 수준 데이터 리포트 API의 반환 파라미터 중 하나)에 전달하는 것입니다.
1.2 방안 2(수동 통합)
수동 통합 계획은 TradPlus의 AppKeyManager.CUSTOM_USERID (Android) 또는 dicCustomValue (iOS) 메서드를 통해 AE 게스트 ID를 TradPlus SDK의 userId(디바이스 수준 데이터 리포트 API의 반환 파라미터 중 하나)에 전달하는 방식입니다.
주의(매우 중요): AE SDK 초기화와 dicCustomValue /initCustomMap 인터페이스 호출은 반드시 TradPlus SDK 초기화 전에 완료해야 합니다. 다음 단계에 따라 진행하십시오:
1. AE SDK를 초기화합니다.
2. ` dicCustomValue ` / ` initCustomMap` 인터페이스를 호출하여 게스트 ID를 설정합니다.
3. TradPlus SDK를 초기화합니다.
다음은 각 플랫폼 SDK의 수동 통합 코드 예시입니다:
- Android
- iOS
- Unity
// 1. Android SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. AE의 게스트 ID 가져오기(AE의 #distinct_id에 해당)
String distinctId = TDAnalytics.getDistinctId();
// 3. 게스트 ID를 TradPlus 수집 이벤트에 설정
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, distinctId);
//APP 단위 규칙을 설정하며, 모든 placement에 적용됨
SegmentUtils.initCustomMap(customMap);
// 4. TradPlus SDK 초기화
// ...
// 1. iOS SDK 초기화
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. AE의 게스트 ID 가져오기(AE의 #distinct_id에 해당)
NSString *distinctId = [TDAnalytics getDistinctId];
// 3. 게스트 ID를 TradPlus 수집 이벤트에 설정
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": distinctId};
// 4. TradPlus SDK 초기화
// ...
// 1. Unity SDK 초기화
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. AE의 게스트 ID 가져오기(AE의 #distinct_id에 해당)
var distinctId = TDAnalytics.GetDistinctId();
// 3. 게스트 ID를 TradPlus 수집 이벤트에 설정
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", distinctId);
//APP 단위 규칙을 설정하며, 모든 placement에 적용됨
TradPlus.initCustomMap(map);
// 4. TradPlus SDK 초기화
// ...
2. TradPlus 백엔드 정보 가져오기
SDK 설정을 마친 후 TradPlus 백엔드에 로그인하여 Access Token과 앱 ID를 가져와야 합니다
- Access token은 TradPlus 백엔드의 My Account - Report API Key에서 키 생성 버튼을 클릭하여 가져올 수 있습니다
- 앱 ID는 App Management의 앱 및 광고 위치 화면에서 확인할 수 있습니다
3. 계획 설정
SDK 설정을 완료하고 Access Token과 앱 ID를 가져온 후 AE 시스템에 로그인하여 서드파티 통합 모듈에서 새 계획을 설정할 수 있습니다. 다음은 TradPlus 디바이스 수준 데이터 리포트 API의 설정 화면입니다. 이 장의 내용에 따라 계획을 생성하십시오:
3.1 인증 정보 설정
인증 정보 아래의 인증 정보 설정 버튼을 클릭하고, 팝업 창에 인증 작업에서 가져온 정보를 입력합니다
3.2 동기화
동기화 모듈에서 AE 시스템이 TradPlus 디바이스 수준 데이터 리포트 API 데이터를 정기적으로 수집하는 전략을 설정할 수 있으며, 매일 특정 시각 또는 매시간 일정 기간의 데이터를 수집하도록 선택할 수 있습니다. 수집한 데이터도 데이터양에 포함되므로 너무 긴 기간의 데이터를 정기적으로 수집하지 않는 것을 권장합니다
3.3 데이터 수집 시간대
수집할 데이터의 시간대도 설정할 수 있으며, 기본값은 UTC+8입니다
3.4 유저 식별 필드
TradPlus 디바이스 수준 데이터 리포트 API는 유저 수준 데이터이므로 유저 식별 규칙, 즉 TradPlus SDK에 설정한 AE 시스템의 유저 식별 ID를 설정해야 합니다. AE 시스템은 이 설정에 따라 콜백 데이터를 변환할 때 해당 필드를 데이터의 유저 식별 필드로 설정합니다.
이 문서의 이전 단계에 따라 클라이언트 SDK를 설정한 경우 다음 설정을 사용하십시오:
- 계정 ID 연관 필드: 없음
- 게스트 ID 연관 필드: user_id
3.5 이벤트 테이블 저장 설정
이벤트 테이블 저장 설정 스위치를 켜면 콜백 데이터가 모두 이벤트 테이블에 기록됩니다. 이벤트 데이터 저장을 활성화할 것을 권장합니다.
3.6 유저 속성 저장 규칙
기본적으로 AE 시스템은 TradPlus 디바이스 수준 데이터 리포트 API의 데이터를 유저 속성에 기록하지 않습니다. 일부 필드를 유저 테이블에 기록하려면 먼저 규칙을 켜서 실행한 다음, 속성 매핑 기능으로 유저 테이블에 기록할 필드를 추가하십시오. 소스 속성명에는 필드의 저장 후 이름을 입력해야 합니다:
3.7 통합 설정
통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 예를 들어 저장 후 이벤트 이름 등이 있습니다
통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:
| 모듈 | 이름 | 의미 |
|---|---|---|
| sink_event | event_name | 저장 후 이벤트 이름, 커스텀 가능 |
| transfer | double_columns | 지표 필드. 수정하지 마십시오 |
3.8 이벤트 저장 규칙
- 데이터의 dateTimeStamp 필드, 즉 데이터 타임스탬프를 이벤트의 #event_time으로 사용합니다
- 데이터 이벤트 이름은 -- tradplus_device_report입니다
- 기타 필드는 모두 저장되며, 다음은 저장되는 모든 이벤트 속성입니다
| 필드 | 타입 | 비고 |
|---|---|---|
| #zone_offset | int | 시간대, 즉 요청 시 사용한 시간대 |
| currency | String | 통화 |
| appid | String | 앱 ID (TradPlus) |
| placement_id | String | 광고 위치 ID (TradPlus) |
| placement_name | String | 광고 위치 이름(TradPlus) |
| ad_format | Int | 광고 위치 유형 |
| ad_format_name | String | 광고 위치 유형 이름 |
| area | String | 국가/지역 코드(ISO 3166-1 2자리 국가/지역 코드) |
| network | Int | 광고 네트워크 ID |
| network_name | String | 광고 네트워크 이름 |
| network_placement_id | String | 광고 네트워크의 광고 위치 ID 정보 |
| network_placement_name | String | 광고 네트워크의 광고 소스 이름 (TradPlus) |
| network_placement_info | String | 광고 네트워크의 광고 위치 상세 정보 |
| android_id | String | 디바이스 ID, androidid |
| gaid | String | Google의 광고 디바이스 ID |
| idfa | String | iOS의 디바이스 ID |
| user_id | String | 유저가 커스텀으로 업로드한 Custom User ID. 여기에는 AE 프로젝트의 게스트 ID가 들어가야 함 |
| channel | String | 채널 |
| sub_channel | String | 하위 채널 |
| oaid | String | Android 디바이스 식별자 |
| idfv | String | 앱 개발사 식별자 |
| os_version | String | 디바이스 OS 버전 |
| att_status | Int | Apple ATT 상태 (0: 유저 미결정; 1: 제한됨; 2: 거부됨; 3: 승인됨) |
| impression | Int | 노출 수(TradPlus) |
| click | Int | 클릭 수(TradPlus) |
| revenue | Float | 수익 |
| ecpm | Float | 1,000회 노출당 수익 |
3.9 표준화 필드
TradPlus 디바이스 수준 데이터 리포트의 일부 필드는 AE 시스템에서 표준화 처리됩니다
| 원본 필드 | 표준화 필드 | 의미 |
|---|---|---|
| network_name | te_ads_object.media_source | 수익화 채널 |
| placement_name | te_ads_object.placement | 광고 위치 |
| area | te_ads_object.country | 국가/지역 코드 |
| currency | te_ads_object.currency | 비용 또는 수익의 통화 |
| impression | te_ads_object.impressions | 노출 수 |
| click | te_ads_object.clicks | 클릭 수 |
| revenue | te_ads_object.revenue | 수익화 수익 |