TopOn 종합 리포트 조회 API
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| 종합 리포트 조회 API | API | 집계 지표 | ✅ | ✅ | ✅ |
종합 리포트는 TopOn 데이터 리포트 조회 API의 종합 리포트 데이터를 말하며, 노출, 클릭 및 수익 지표를 포함한 집계된 광고 수익화 데이터를 제공합니다.
통합 절차
- TopOn 백엔드에 로그인하여 Publisher Key와 APP ID를 가져옵니다
- AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 TopOn 통합을 추가하고 통합 계획을 생성한 다음, 1회 수집을 실행하여 데이터를 동기화합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. TopOn 백엔드 정보 가져오기
데이터를 수집하기 전에 먼저 TopOn 담당자에게 데이터 리포트 조회 API 권한 개통을 신청해야 합니다. 개통되면 개발자 백엔드의 계정 관리 페이지에서 Publisher Key를 확인할 수 있습니다.
다음으로 TopOn 백엔드의 앱 페이지로 이동하여 데이터를 연동할 앱의 앱 ID를 가져옵니다
2. 계획 설정
Publisher Key와 App ID를 가져온 후 AE 시스템에 로그인하여 서드파티 통합 모듈에서 새 계획을 설정할 수 있습니다. 다음은 TopOn 종합 리포트 조회 API의 설정 화면입니다. 이 장의 내용에 따라 계획을 생성하십시오:
2.1 인증 정보 설정
인증 정보 아래의 인증 정보 설정 버튼을 클릭하고, 팝업 창에 인증 작업에서 가져온 정보를 입력합니다
참고:
-
APP ID: 방금 가져온 앱 ID
-
Publisher Key: 방금 가져온 Publisher Key
-
Brand: 기존 TopOn은 산하 비즈니스를 분리했습니다(자세한 내용은 이 글 참고). 사용 중인 구체적인 비즈니스 브랜드를 입력해야 합니다
- Taku를 사용하는 경우(공식 웹사이트 주소: takuad.com)
taku를 입력합니다(입력하지 않아도 taku로 간주) - TopOn을 사용하는 경우(공식 웹사이트 주소: www.toponad.com)
topon을 입력합니다
- Taku를 사용하는 경우(공식 웹사이트 주소: takuad.com)
2.2 동기화
동기화 모듈에서 AE 시스템이 TopOn 종합 리포트 조회 API 데이터를 정기적으로 수집하는 전략을 설정할 수 있으며, 매일 특정 시각 또는 매시간 일정 기간의 데이터를 수집하도록 선택할 수 있습니다. 수집한 데이터도 데이터양에 포함되므로 너무 긴 기간의 데이터를 정기적으로 수집하지 않는 것을 권장합니다
2.3 데이터 수집 시간대
수집할 데이터의 시간대도 설정할 수 있으며, 기본값은 UTC+8입니다
2.4 이벤트 테이블 저장 설정
이벤트 테이블 저장 설정 스위치를 켜면 콜백 데이터가 모두 이벤트 테이블에 기록됩니다. 이벤트 데이터 저장을 활성화할 것을 권장합니다.
2.5 통합 설정
통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 여기에는 수집할 지표 필드와 차원, 저장 후 이벤트 이름 등이 포함됩니다.
통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:
| 모듈 | 이름 | 의미 |
|---|---|---|
| sink_event | event_name | 저장 후 이벤트 이름, 커스텀 가능 |
| source | metrics | 데이터의 지표, 리스트 타입. 계층마다 지원하는 metrics가 다르므로 입력 시 주의 필요 |
| group_by | 데이터의 그룹 차원, 리스트 타입. 계층마다 지원하는 group_by가 다르므로 입력 시 주의 필요 |
- 그룹 차원
아래 표는 종합 리포트 조회 API가 지원하는 모든 그룹 차원입니다. 참고: 10일 이내의 데이터를 조회할 때는 그룹 차원을 최대 6개, 10일 이전의 데이터를 조회할 때는 최대 3개까지 선택할 수 있으며, time_zone과 currency는 그룹 차원 수에 포함되지 않습니다. 조정하려면 그룹 차원을 source.group_by에 추가하십시오:
| 그룹 차원 | 저장 필드명 | 타입 | 기본 여부 | 비고 |
|---|---|---|---|---|
| date | date | 문자열 | 예 | 날짜, 형식: YYYYmmdd |
app | app_id | 문자열 | 예 | 개발자 백엔드의 앱 ID |
| app_name | 문자열 | 예 | 앱 이름 | |
| app_platform | 문자열 | 예 | 앱의 시스템 플랫폼 | |
| app_pkg_name | 문자열 | 예 | 앱의 패키지명 | |
| placement | placement_id | 문자열 | 예 | 개발자 백엔드의 광고 위치 ID |
| placement_name | 문자열 | 예 | 광고 위치 이름 | |
adsource | adsource_network | 문자열 | 예 | 광고 소스가 속한 광고 플랫폼 이름 |
| adsource_token_position_id | 문자열 | 예 | 광고 소스의 위치 ID | |
| adsource_token_orientation | 문자열 | 예 | 광고 소스의 방향 | |
| adsource_token_video_muted | 문자열 | 예 | 광고 음소거 여부 | |
| adsource_token_app_id | 문자열 | 예 | 광고 소스의 App ID | |
| adsource_token_app_name | 문자열 | 예 | 광고 소스의 App 이름 | |
| adsource_id | 문자열 | 예 | 광고 소스 id | |
| adsource_name | 문자열 | 예 | 광고 소스 이름 | |
| network_firm_id | network_firm_id | 문자열 | 예 | 광고 플랫폼 ID |
| network_firm | 문자열 | 예 | 광고 플랫폼 이름 | |
항상 반환 | time_zone | 문자열 | 예 | 시간대, 열거값: UTC+8, UTC+0, UTC-8 |
| currency | 문자열 | 예 | 개발자 계정 통화. 이 필드와 revenue 필드로 구성된 수익은 개발자 백엔드 리포트의 수익과 일치해야 함 | |
adformat | adformat | 문자열 | 광고 형식, 열거값: Rewarded Video, Interstitial, Banner, Native, Splash | |
| area | area | 문자열 | 국가(지역) 코드 | |
network | network | 문자열 | 광고 플랫폼 계정 ID | |
| network_name | 문자열 | 광고 플랫폼 계정 이름 | ||
| scenario | scenario_id | 문자열 | 광고 시나리오 ID | |
| scenario_name | 문자열 | 광고 시나리오 이름 | ||
traffic_group | traffic_group_id | 문자열 | 트래픽 그룹 id | |
| traffic_group_name | 문자열 | 트래픽 그룹 이름 | ||
| traffic_group_segment_id | 문자열 | 트래픽 그룹 숫자 ID. 참고: 기본 트래픽 그룹이면 segment_id = 0이며 반환되지 않음 | ||
| channel | channel | 문자열 | 채널 이름 | |
| sdk_version | sdk_version | 문자열 | SDK 버전 | |
| app_version | app_version | 문자열 | 앱 버전 |
- 지표 필드
기본적으로 다음 필드를 모두 저장합니다. 조정이 필요하면 source.metrics를 수정하십시오:
| 필드 | 비고 |
|---|---|
| new_user_rate | 신규 유저 비율 |
| deu | DEU |
| engaged_rate | 침투율 |
| imp_dau | 노출 / DAU |
| imp_deu | 노출 / DEU |
| impression_rate | 노출률 |
| dau | group_by 조건에 따라서만 반환됨 |
| arpu | dau가 있을 때만 반환됨 |
| request | 요청 수 |
| fillrate | 채움률 |
| impression | 노출 수 |
| click | 클릭 수 |
| ctr | 클릭률 |
| ecpm | TopOn이 리포트 API로 광고 플랫폼에서 수집한 실제 수익과 TopOn이 집계한 노출로 계산한 eCPM. 계산 공식: (수익/TopOn이 집계한 노출)*1000. 참고: eCPM은 1일 지연되어 제공 |
| revenue | 서드파티 광고 플랫폼의 수익. 통화는 개발자 계정 통화 |
| request_api | 서드파티 광고 플랫폼의 요청 수 |
| fillrate_api | 서드파티 광고 플랫폼의 채움률 |
| impression_api | 서드파티 광고 플랫폼의 노출 수 |
| click_api | 서드파티 광고 플랫폼의 클릭 수 |
| ctr_api | 서드파티 광고 플랫폼의 클릭률 |
| ecpm_api | TopOn이 리포트 API로 광고 플랫폼에서 수집한 실제 수익과 노출 API로 계산한 eCPM API. 계산 공식: (수익/노출 API)*1000. 참고: eCPM API는 1일 지연되어 제공 |
| estimate_revenue | 예상 수익, 통화: 미국 달러 |
estimate_revenue_ecpm | 예상 수익과 TopOn이 집계한 노출로 계산한 예상 eCPM. 계산 공식: (예상 수익/TopOn이 집계한 노출)*1000. 참고: 1. 예상 eCPM은 당일 제공, 2. 일반 광고 소스는 수동으로 입력한 eCPM 가격으로, 입찰 광고 소스는 실시간 입찰 가격으로 계산 |
| ready_request | isReady 호출 횟수 |
| ready_rate | isReady 성공률 |
| cy_estimate_revenue | 개발자 계정 통화로 반환되는 예상 수익 |
| cy_estimate_revenue_ecpm | 개발자 계정 통화로 반환되는 예상 eCPM. 계산 방식은 estimate_revenue_ecpm과 동일 |
2.6 이벤트 저장 규칙
기본적으로 수집한 데이터는 이벤트 형태로 AE 프로젝트에 기록됩니다:
- 종합 리포트 조회 API는 집계 데이터를 반환하므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결된다고 보면 됩니다
- 데이터의 date 필드, 즉 데이터의 날짜를 집계 데이터의 #event_time으로 설정합니다
- 데이터 이벤트 이름은 -- topon_fullreport입니다
- 나머지 필드는 모두 저장됩니다
2.7 표준화 필드
TopOn 종합 리포트 조회 API의 일부 필드는 AE 시스템에서 표준화 처리됩니다
| 원본 필드 | 표준화 필드 | 의미 |
|---|---|---|
| adsource_name | te_ads_object.ad_name | 광고 이름 |
| adsource_id | te_ads_object.ad_id | 광고 ID |
| placement_name | te_ads_object.placement | 광고 위치 |
| network_firm | te_ads_object.media_source | 수익화 채널 |
| app_pkg_name | te_ads_object.app_id | 앱 ID |
| app_name | te_ads_object.app_name | 앱 이름 |
| app_platform | te_ads_object.platform | 플랫폼(Android, iOS 등) |
| 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 | 수익화 수익 |