Unity Ads Advertising Statistics API V2.0
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| Advertising Statistics API V2.0 | API | 집계 지표 | ✅ | ✅ | ✅ | ✅ | ✅ |
Unity Ads 광고 집행 데이터 2.0을 Advertising Statistics API v2.0을 통해 Thinking Analytics(이하 AE 시스템)로 전송하는 방안으로, 이 방안은 다음을 지원합니다:
- Unity Ads의 비용, 클릭, 노출 등 기본 리포트 지표를 AE 시스템으로 전송
통합 절차
- Unity 백엔드에 로그인하여 데이터를 연동할 프로젝트의 Organization ID와 API Key를 가져옵니다
- AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 Unity 통합 계획을 추가하고 관련 설정을 완료합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. 인증 정보 가져오기
1.1 Organization ID 가져오기
Unity Ads User Acquisition 백엔드로 이동하여 왼쪽 사이드바의 Administration 페이지 아래에 있는 Settings 페이지를 선택하고, Organization Settings 표에서 Organization ID를 찾아 복사해 저장합니다.
1.2 API Key 및 Secret 가져오기
다음으로 서비스 계정(service account)을 생성하고 광고 통계 API 뷰어(Advertise Stats API Viewer) 권한을 설정해야 합니다. 이 계정의 API Key와 Secret을 사용해야 데이터를 가져올 수 있습니다. 다음은 서비스 계정 생성부터 시작하는 전체 절차입니다:
- 서비스 계정 생성
Unity Cloud 백엔드로 이동하여 Administration > Service accounts 페이지에서 오른쪽 상단의 생성 버튼을 클릭하여 서비스 계정 생성 단계로 들어갑니다.
이어서 필요에 따라 서비스 계정 이름과 설명을 입력하고 계정 생성을 완료합니다.
- 인증 Key 생성
계정 생성을 완료한 후 계정의 설정 페이지로 이동하여 Keys 섹션에서 새 인증 Key를 생성합니다.
생성이 완료되면 Key ID, Secret Key 및 Authorization header를 기록하여 안전하게 보관하십시오. 이 정보는 통합 계획을 생성할 때 사용됩니다.
- 계정 권한 설정
다음으로 이 계정에 광고 통계 API 뷰어(Advertise Stats API Viewer) 권한을 설정해야 합니다. Organization roles 섹션에서 역할 생성 절차를 클릭하여 권한 선택 화면으로 이동합니다.
권한 선택 화면의 Growth 옵션에서 Advertise Stats API Viewer를 선택하여 권한 설정을 완료합니다.
2. 계획 설정
Unity 백엔드에서 인증 정보를 가져온 후 AE 시스템에 로그인하여 서드파티 통합 모듈에서 새 계획을 설정할 수 있습니다. 아래 그림은 Unity Ads Advertising Statistics API V2.0의 설정 화면입니다. 이 장의 내용에 따라 계획을 생성하십시오:
2.1 인증 정보 설정
인증 정보 아래의 인증 정보 설정 버튼을 클릭하고 팝업 창에 이전 단계에서 얻은 정보를 입력합니다:
Unity 백엔드에서 가져온 정보를 빠짐없이 입력하십시오. Authorization header를 입력할 때는 앞의 Basic 접두사를 포함하십시오
2.2 동기화
동기화 모듈에서 AE 시스템이 Unity Ads Advertising Statistics API V2.0 데이터를 정기적으로 수집하는 정책을 설정할 수 있으며, 매일 특정 시각에 일정 기간의 데이터를 수집하도록 선택할 수 있습니다. 수집한 데이터도 데이터양에 포함되므로 너무 긴 기간의 데이터를 정기적으로 수집하지 않는 것을 권장합니다
2.3 저장 설정
데이터를 이벤트 형태로 기록할지 제어할 수 있습니다. 끄면 데이터가 이벤트 테이블에 기록되지 않으므로 이 설정을 끄지 마십시오.
2.4 통합 설정
마지막으로 통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 데이터의 시간 집계 단위, 수집할 지표 필드와 차원, 저장 후 이벤트 이름 등이 포함됩니다.
통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:
| 모듈 | 이름 | 의미 |
|---|---|---|
| sink_event | event_name | 저장 후 이벤트 이름, 커스텀 가능, 문자열 타입. |
| source | time_granularity | 데이터 수집의 시간 단위. 다음 중에서 선택할 수 있습니다:
|
| metrics | 해당 인터페이스의 지표 필드, 리스트 타입, 커스텀 가능 | |
| group_by | 데이터의 그룹 차원, 리스트 타입, 커스텀 가능 | |
| transfer | double_columns | 데이터의 지표, 리스트 타입. 여기에 포함된 필드는 데이터 수신 시 숫자 타입으로 저장되고, 나머지 필드는 문자열(또는 시간)로 저장됩니다. 조정하지 않는 것을 권장 |
- 그룹 차원
다음은 Unity Advertising Statistics API V2.0이 지원하는 그룹 차원입니다. 조정하려면 필요한 그룹 차원의 차원 이름을 source.group_by에 입력하십시오
| 차원명 | 설명 | 저장 필드명 | 기본 수집 여부 |
|---|---|---|---|
| app | App 기준 그룹화 | app_id | 예 |
| app_name | 예 | ||
| campaign | Campaign 기준 그룹화 | campaign_id | 예 |
| campaign_name | 예 | ||
| country | 국가(지역)별 그룹화 | country | |
| creativePack | Creative Pack 기준 그룹화 | creative_pack_id | 예 |
| creative_pack_name | 예 | ||
| creativePackType | Creative Pack 타입 기준 그룹화 | creative_pack_type | 예 |
| osVersion | 시스템 버전 기준 그룹화 | os_version | 예 |
| platform | 플랫폼 기준 그룹화 | platform | 예 |
| sourceAppId | 소스 게임 기준 그룹화 | source_app_id | |
| store | 앱 스토어 기준 그룹화 | store | 예 |
targetGame | 대상 게임 기준 그룹화 | target_id | 예 |
| target_store_id | 예 | ||
| target_name | 예 | ||
| eventType | Unity 이벤트 타입 기준 그룹화 | event_type | |
| eventName | Unity 이벤트 이름 기준 그룹화 | event_name |
- 지표 필드
그룹 차원 외에도 Unity Ads Advertising Statistics API v2.0은 다음 지표 필드를 제공합니다. 조정하려면 필요한 지표 이름을 source.metrics에 입력하십시오.
| 지표명 | 저장 필드명 | 필드 설명 | 기본 수집 여부 |
|---|---|---|---|
| timestamp | timestamp | 이벤트 시간 | 예 |
| starts | starts | 광고 노출 횟수 | 예 |
| views | views | 광고 완료 재생 횟수 | 예 |
| clicks | clicks | 광고 클릭 수 | 예 |
| installs | installs | 광고 조회 후 설치 횟수 | 예 |
| spend | spend | 비용 | 예 |
| cpi | cpi | 설치당 비용 | |
| ctr | ctr | 클릭률 | |
| cvr | cvr | 전환율 | |
| ecpm | ecpm | eCPM | |
| d[x]AdRevenue | d[x]_ad_revenue | N일 광고 수익 | |
| d[x]AdRevenueRoas | d[x]_ad_revenue_roas | N일 광고 수익 ROAS | |
| d[x]IapRevenue | d[x]_iap_revenue | N일 인앱 결제 수익 | |
| d[x]IapRoas | d[x]_iap_roas | N일 인앱 결제 수익 ROAS | |
| d[x]Purchases | d[x]_purchases | N일 인앱 결제 횟수 | |
| d[x]UniquePurchasers | d[x]_unique_purchasers | N일 최초 인앱 결제 유저 수 | |
| d[x]Retained | d[x]_retained | N일 잔존 유저 수 | |
| d[x]RetentionRate | d[x]_retention_rate | N일 잔존율 | |
| d[x]TotalRoas | d[x]_total_roas | N일 총수익 ROAS | |
| d[x]LevelComplete | d[x]_level_complete | N일 특정 레벨 통과 유저 수 | |
| d[x]CostPerLevelComplete | d[x]_cost_per_level_complete | N일 특정 레벨 통과 유저의 평균 비용 | |
| d[x]LevelCompleteRate | d[x]_level_complete_rate | N일 특정 레벨 통과율 |
위 표의 [x]는 0, 1, 3, 7, 14 등의 실제 숫자로 바꿀 수 있습니다. 예를 들어 d7은 7일째까지의 지표를 나타냅니다
2.5 이벤트 저장 규칙
- 데이터의 timestamp 필드, 즉 데이터 집계 시간 필드를 집계 데이터의 #event_time으로 설정합니다
- 이름을 변경하지 않은 경우 데이터의 이벤트 이름은 -- unity_ads_api_data입니다
- 나머지 필드는 모두 저장됩니다
2.6 표준화 필드
Unity Ads Advertising Statistics API v2.0 데이터의 일부 필드는 AE 시스템에서 표준화 처리합니다:
| 필드 | 표준화 필드 | 의미 |
|---|---|---|
| campaign_name | te_ads_object.campaign_name | 캠페인 이름 |
| campaign_id | te_ads_object.campaign_id | 캠페인 ID |
| creative_pack_name | te_ads_object.ad_group_name | 광고 그룹 이름 |
| creative_pack_id | te_ads_object.ad_group_id | 광고 그룹 ID |
| country | te_ads_object.country | 국가/지역 코드 |
| platform | te_ads_object.platform | 플랫폼(Android, iOS 등) |
| starts | te_ads_object.impressions | 노출 수 |
| clicks | te_ads_object.clicks | 클릭 수 |
| installs | te_ads_object.installs | 전환 수(설치) |
| spend | te_ads_object.cost | UA 비용 |