TradPlus 데이터 연동 솔루션
최종 업데이트 날짜: 2022-08-22
1. 개요
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
이 문서에서는 TradPlus의 광고 수익화 데이터를 Agentic Engine(이하 AE 시스템)으로 콜백하는 방법을 소개합니다. 이 계획은 다음을 지원합니다:
- 디바이스 수준 데이터 리포트 API로 유저 수준의 광고 수익화 데이터를 연동합니다
- 종합 리포트 조회 API로 집계된 광고 수익화 데이터를 연동합니다
TradPlus 연동을 시작하기 전에 AE 시스템의 데이터 규칙을 읽고 AE의 데이터 구조를 이해했는지 확인하십시오. 또한 데이터 수집에 필요한 정보를 저희 고객 성공 매니저에게 전달하는 것을 권장합니다. 형식은 데이터 연동 설정 정보 템플릿을 참고하십시오.
절차
TradPlus 데이터의 연동 절차는 다음과 같습니다:
- 디바이스 수준 데이터 리포트 API 연동
- TradPlus 백엔드에서 Token과 앱 ID를 가져와 ThinkingAI 담당자에게 보냅니다
- 클라이언트 SDK에서 AE 프로젝트의 게스트 ID를 TradPlus의 커스텀 ID로 설정합니다
- 수집할 데이터 차원, 지표 타입, 수집 빈도 및 수집 기간을 확정합니다
- ThinkingAI 담당자가 데이터 수집 개발 작업을 완료합니다
- AE 백엔드에서 대시보드와 리포트를 구축하고 데이터 검증을 완료합니다
- 종합 리포트 조회 API
- TradPlus 백엔드에서 Token과 앱 ID를 가져와 ThinkingAI 담당자에게 보냅니다
- 수집할 데이터 차원, 지표 타입, 수집 빈도 및 수집 기간을 확정합니다
- ThinkingAI 담당자가 데이터 수집 개발 작업을 완료합니다
- AE 백엔드에서 대시보드와 리포트를 구축하고 데이터 검증을 완료합니다
2. 인증
어떤 데이터를 연동하든 먼저 TradPlus 백엔드에 로그인하여 Access Token과 앱 ID를 가져온 후 ThinkingAI 담당자에게 보내야 합니다.
- Access token은 TradPlus 백엔드의 My Account - Report API Key에서 키 생성 버튼을 클릭하여 가져올 수 있습니다
- 앱 ID는 App Management의 앱 및 광고 위치 화면에서 확인할 수 있습니다
3. 디바이스 수준 데이터 리포트 API
인터페이스 기본 정보
| 인터페이스명 | API 타입 | 제품화 | 데이터 세분화 | 어트리뷰션 데이터 | 비용 데이터 | 수익 데이터 | 노출 데이터 | 클릭 데이터 | 전환 데이터 |
|---|---|---|---|---|---|---|---|---|---|
| 디바이스 수준 데이터 리포트 API | 풀 방식 | 아니요 | 유저 수준 | 예 | 예 | 예 |
디바이스 수준 데이터 리포트 API는 유저 수준의 광고 수익화 데이터를 제공하며, 특정 일자의 유저별 광고 노출 횟수, 클릭 수, 수익 등의 지표가 포함됩니다.
3.1 클라이언트 SDK 설정
TradPlus 광고 데이터를 AE 프로젝트의 유저 데이터와 연결하려면 클라이언트 SDK에서 설정하여 AE 프로젝트의 게스트 ID를 TradPlus 백엔드로 전달해야 합니다.
방안 1(자동 통합):
연동한 AE SDK 버전이 2.8.0~2.8.1이면 이 방안을 바로 사용할 수 있습니다
연동한 AE SDK 버전이 2.8.2 이상이면 서드파티 데이터 플러그인도 설치해야 합니다
이 계획은 자동 통합 계획입니다. AE 클라이언트 SDK를 초기화한 후 다음 코드를 호출하여 활성화하십시오. 자세한 내용은 Android SDK 서드파티 데이터 및 iOS SDK 서드파티 데이터를 참고하십시오:
// AE SDK 초기화
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// TradPlus id 연결 활성화
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TRAD_PLUS);
// TradPlus SDK 초기화
// ...
이 방안의 원리는 내부에서 SegmentUtils의 initCustomMap 메서드를 자동으로 호출하여 AE SDK의 게스트 ID를 AppKeyManager.CUSTOM_USERID에 전달하는 것입니다
방안 2(수동 통합):
수동 통합 계획은 TradPlus의 AppKeyManager.CUSTOM_USERID (Android) 또는 dicCustomValue (iOS) 메서드를 통해 AE 게스트 ID를 TradPlus SDK의 userId(디바이스 수준 데이터 리포트 API의 반환 파라미터 중 하나)에 전달하는 방식입니다.
iOS 코드 예시:
//앱 단위의 커스텀 정보
NSString *ta_distinct_id = [instance getDistinctId];
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": ta_distinct_id};
Android 네이티브 코드 예시:
String ta_distinct_id = instance.getDistinctId();
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, ta_distinct_id);
//APP 단위 규칙을 설정하며, 모든 placement에 적용됨
SegmentUtils.initCustomMap(customMap);
Unity SDK 코드 예시:
string ta_distinct_id = ThinkingAnalyticsAPI.GetDistinctId();
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", ta_distinct_id);
//APP 단위 규칙을 설정하며, 모든 placement에 적용됨
TradPlus.initCustomMap(map);
주의(매우 중요):
AppKeyManager.CUSTOM_USERID (Android/Unity) 또는 dicCustomValue (iOS)를 통한 전송은 TradPlus SDK 초기화 전에 완료해야 합니다. 그렇지 않으면 일부 userId가 콜백되지 않을 수 있습니다.
3.2 데이터 수집
3.2.1 포함 필드
- 차원 필드
| 필드 | 타입 | 비고 |
|---|---|---|
| dateTimeStamp | int | 타임스탬프(날짜) |
| #zone_offset | int | 시간대, 즉 요청 시 사용한 시간대 |
| appId | String | 앱 ID (TradPlus) |
| placementId | String | 광고 위치 ID (TradPlus) |
| placementName | String | 광고 위치 이름(TradPlus) |
| adFormat | Int | 광고 위치 유형 |
| adFormatName | String | 광고 위치 유형 이름 |
| area | String | 국가/지역 코드(ISO 3166-1 2자리 국가/지역 코드) |
| network | Int | 광고 네트워크 ID |
| networkName | String | 광고 네트워크 이름 |
| networkPlacementId | String | 광고 네트워크의 광고 위치 ID 정보 |
| networkPlacementName | String | 광고 네트워크의 광고 소스 이름 (TradPlus) |
| networkPlacementInfo | String | 광고 네트워크의 광고 위치 상세 정보 |
| androidId | String | 디바이스 ID, androidid |
| gaid | String | Google의 광고 디바이스 ID |
| idfa | String | iOS의 디바이스 ID |
| userId | 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.2.2 인터페이스 파라미터
- 시간:
- 일 단위로 데이터를 수집합니다
- 시간대는 "UTC+8", "UTC+0", "UTC-8" 중에서 선택할 수 있습니다
- 일 단위로 데이터를 수집합니다
- 통화:
- USD, CNY 중에서 선택할 수 있으며, 기본값은 USD입니다
- 수집 프로젝트:
- 데이터를 수집할 플랫폼 프로젝트를 지정하고 해당 프로젝트의 App ID를 제공해야 합니다
3.2.3 데이터 저장 규칙
기본적으로 수집한 데이터는 이벤트 형태로 AE 프로젝트에 기록됩니다:
- 데이터의 userId를 데이터의 게스트 ID로 사용하며, 이 필드는 AE 프로젝트의 게스트 ID에 대응해야 합니다
- 데이터의 dateTimeStamp 필드, 즉 데이터 타임스탬프를 이벤트의 #event_time으로 사용합니다
- 데이터 이벤트 이름은 -- tradplus_device_report입니다
- 나머지 필드는 모두 저장됩니다
4. 종합 리포트 조회 API
인터페이스 기본 정보
| 인터페이스명 | API 타입 | 제품화 | 데이터 세분화 | 어트리뷰션 데이터 | 비용 데이터 | 수익 데이터 | 노출 데이터 | 클릭 데이터 | 전환 데이터 |
|---|---|---|---|---|---|---|---|---|---|
| 종합 리포트 조회 API | 풀 방식 | 아니요 | 집계 데이터 | 예 | 예 | 예 |
종합 리포트 조회 API는 광고 수익화의 집계 지표 데이터를 제공하며, 광고 노출 횟수, 클릭 수, 수익 등의 지표가 포함됩니다.
4.1 분석 차원
다음은 종합 리포트 조회 API의 모든 분석 차원입니다. 기본적으로 모든 그룹 차원을 사용하며, 조정이 필요하면 수집할 그룹 항목을 데이터 연동 설정 정보 템플릿에 입력하십시오.
| 그룹 항목 | 필드 | 비고 |
|---|---|---|
| date | date | 날짜, 형식: YYYY-mm-dd |
| appId | appId | 앱 ID (TradPlus) |
| packageName | 패키지 이름 | |
| placementId | placementId | 광고 위치 ID (TradPlus) |
| placementName | 광고 위치 이름 (TradPlus) | |
| adFormat | adFormat | 광고 위치 유형 |
| adFormatName | 광고 위치 유형 이름 | |
| area | area | 국가/지역 코드(ISO 3166-1 2자리 국가/지역 코드) |
| network | network | 광고 네트워크 ID |
| networkName | 광고 네트워크 이름 | |
| networkPlacementId | networkPlacementId | 광고 네트워크의 광고 위치 ID 정보 |
| networkPlacementName | 광고 네트워크의 광고 소스 이름 (TradPlus) | |
| networkPlacementInfo | 광고 네트워크의 광고 위치 상세 정보 |
4.2 포함 지표
다음은 종합 리포트 조회 API에 포함된 지표 필드입니다. 기본적으로 모든 필드를 가져오며, 조정이 필요하면 수집할 지표 필드를 데이터 연동 설정 정보 템플릿에 입력하십시오.
| 필드 | 타입 | 비고 |
|---|---|---|
| dau | Int | 일간 활성 유저 수(앱 수준) |
| deu | Int | 매일 광고를 시청한 유저 수 |
| arpu | Float | 유저당 평균 수익 |
| newUsers | Int | 신규 유저(앱 수준) |
| newUserRate | Float | 신규 유저 비율(앱 수준) |
| requestApi | Int | 서드파티 광고 플랫폼의 요청 수 |
| fillrateApi | Float | 서드파티 광고 플랫폼의 채움률 |
| impressionApi | Int | 서드파티 광고 플랫폼의 노출 수 |
| clickApi | Int | 서드파티 광고 플랫폼의 클릭 수 |
| ctrApi | Float | 서드파티 광고 플랫폼의 클릭률 |
| ecpmApi | Float | 서드파티 광고 플랫폼의 eCPM |
| revenue | Float | 수익 |
4.3 인터페이스 파라미터
- 시간:
- 일 단위로 데이터를 수집합니다
- 시간대는 "UTC+8", "UTC+0", "UTC-8" 중에서 선택할 수 있습니다
- 일 단위로 데이터를 수집합니다
- 통화:
- USD, CNY 중에서 선택할 수 있으며, 기본값은 USD입니다
- 수집 프로젝트:
- 데이터를 수집할 플랫폼 프로젝트를 지정하고 해당 프로젝트의 App ID를 제공할 수 있습니다
4.4 데이터 저장 규칙
기본적으로 수집한 데이터는 이벤트 형태로 AE 프로젝트에 기록됩니다:
- 종합 리포트 조회 API는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다
- 데이터의 date 필드, 즉 데이터의 날짜를 이벤트의 #event_time으로 사용합니다
- 데이터 이벤트 이름은 -- tradplus_allreport입니다
- 나머지 필드는 모두 저장됩니다
5. 데이터 연동 설정 정보 템플릿
위 문서를 읽은 후 수집할 API, 필드, 수집 방식 등의 정보를 다음 정보 상자에 입력하여 ThinkingAI의 고객 성공 매니저에게 보내십시오.
인터페이스: TradPlus 디바이스 수준 데이터 리포트 API / 종합 리포트 조회 API
--------
회사 이름: XXX
AE 프로젝트 환경: (SAAS/프라이빗 배포)
AE 프로젝트 이름: XXX
AE 프로젝트 APP ID: XXX
데이터 수신 주소 push_url: XXX
---------
TradPlus Access Token: XXX
---------
데이터 수집 타입: 디바이스 수준 데이터 리포트 API / 종합 리포트 조회 API(둘 다 사용하는 경우 각각 작성)
<-----아래는 디바이스 수준 데이터 리포트 API----->
TradPlus 백엔드의 앱 ID: XXX, XXX
데이터 수집 시간대: XXX (시간대, 열거값: UTC-8, UTC+8, UTC+0, 전달하지 않으면 기본값 "UTC+0")
<--------------------------------->
<-----아래는 종합 리포트 조회 API 정보----->
TradPlus 백엔드의 앱 ID: XXX, XXX
데이터 수집 시간대: XXX (시간대, 열거값: UTC-8, UTC+8, UTC+0, 전달하지 않으면 기본값 "UTC+0")
분석 차원: XXX, XXX(기본값은 전체 필드)
수집 지표: XXX, XXX(기본값은 all, 즉 전체 필드)
<------------------------------------>
과거 데이터 수집 기간: yyyy/mm/dd - yyyy/mm/dd
정기 수집: 매일 X시에 전날 데이터 수집
6. 연동 테스트 및 데이터 활용
6.1 데이터 검증
AE 시스템 백엔드의 데이터 관리 - 이벤트 관리 페이지 또는 SQL IDE 페이지에서 다음 이벤트가 저장되었는지 검색할 수 있습니다:
- 디바이스 수준 데이터 리포트 API: tradplus_device_report
- 종합 리포트 조회 API: tradplus_allreport