Airbridge Actuals Report
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| Actuals Report | API | 집계 지표 | ✅ | ✅ | ✅ | ✅ |
Airbridge Actuals Report는 비용, 노출, 클릭, 전환 등의 지표를 포함한 집계 리포트 데이터를 제공합니다. 이 통합 계획은 AE 백엔드에서 Airbridge 리포트 데이터를 정기적으로 수집하는 데 사용되며, 인터페이스는 비동기 작업 방식으로 동작합니다. AE는 먼저 리포트 작업을 생성하고 작업 상태를 폴링한 다음, 작업이 완료되면 결과를 페이지 단위로 읽어옵니다.
통합 절차
- Airbridge 백엔드에서 인증 정보
app_name과api_token을 가져옵니다 - AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 Airbridge Actuals Report 계획을 추가하고 관련 설정을 완료합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. Airbridge 인증 정보 가져오기
Airbridge Actuals Report를 사용하기 전에 다음 인증 정보를 준비해야 합니다.
| 인증 정보 | 필수 여부 | 의미 |
|---|---|---|
| app_name | 예 | Airbridge 앱 이름, API 요청 경로 구성에 사용 |
| api_token | 예 | Airbridge API 호출 자격 증명 |
2. 계획 설정
Airbridge 인증 정보를 가져온 후 AE 시스템에 로그인하여 서드파티 통합 모듈에서 새 계획을 설정할 수 있습니다. 다음은 Airbridge Actuals Report의 설정 화면입니다. 이 장의 내용에 따라 계획을 생성하십시오:
2.1 인증 정보 설정
인증 정보 설정에 Airbridge에서 가져온 app_name, api_token을 입력합니다.
2.2 동기화
계획의 정기 수집 빈도를 설정할 수 있습니다. 활성화하면 AE 시스템이 설정된 주기에 따라 Airbridge에 Actuals Report 데이터 조회 작업을 요청합니다.
Airbridge Actuals Report에서 가져올 수 있는 기간은 최대 과거 1000일이며, 1회 최대 400일까지 가져올 수 있습니다.
2.3 이벤트 테이블 저장 설정
데이터를 이벤트 형태로 기록할지 여부를 제어할 수 있습니다. 이벤트 테이블 저장 설정 스위치를 켜면 AE 시스템이 Airbridge Actuals Report에서 수집한 집계 데이터를 이벤트 테이블에 기록합니다.
이벤트 데이터 저장을 활성화할 것을 권장합니다. 이 설정을 끄면 수집한 데이터가 이벤트 테이블에 기록되지 않으며, 이후 이벤트 분석에서 사용할 수 없습니다.
2.4 통합 설정
통합 설정은 Airbridge Actuals Report의 데이터 조회 및 저장 기준을 정의하는 데 사용하며, 지표, 차원, 시간 단위, 날짜 범위, 저장 후 이벤트 이름, 확장 파라미터를 포함합니다.
통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:
| 모듈 | 이름 | 필수 여부 | 의미 |
|---|---|---|---|
source | metrics | 예 | 수집할 지표 목록 |
| group_by | 예 | 데이터를 집계할 차원 | |
| time_granularity | 예 | 시간 단위, 현재 day만 지원 | |
| 루트 설정 | date_range | 예 | 매번 수집할 날짜 범위 |
| sink_event | event_name | 예 | 저장 후 이벤트 이름, 커스텀 가능 |
| extra_params | filters | 아니요 | Airbridge 필터 조건 |
| sorts | 아니요 | Airbridge 정렬 조건 |
{
"source": {
"metrics": [
"app_events",
"app_installs",
"impressions",
"impressions_channel",
"clicks_channel",
"cost_channel"
],
"group_by": [
"ad_account_id",
"campaign_id",
"ad_group_id",
"ad_creative_id",
"event_date",
"channel"
],
"time_granularity": "day"
},
"date_range": "0,1",
"sink_event": {
"event_tracking": true,
"event_name": "airbridge_event_data"
},
"extra_params": {}
}
2.4.1 지표 설정
metrics는 수집할 Airbridge 지표를 설정하는 데 사용합니다. 일반적인 지표로는 이벤트 수, 설치 수, 노출 수, 클릭 수, 비용, 수익 등이 있습니다.
| 지표 필드 | 의미 | 설정 안내 |
|---|---|---|
| app_events | 인앱 이벤트 수 | 예시 설정 |
| app_installs | 앱 설치 수 | 예시 설정 |
| impressions | 노출 수 | 예시 설정 |
| impressions_channel | 채널 노출 수 | 예시 설정 |
| clicks_channel | 채널 클릭 수 | 예시 설정 |
| cost_channel | 채널 비용 | 예시 설정 |
| app_total_revenue | 앱 총수익 | 선택 설정 |
2.4.2 그룹 차원
group_by는 리포트 집계 차원을 설정하는 데 사용합니다. Airbridge 응답의 groupBys는 요청의 group_by 순서대로 반환됩니다.
| 그룹 차원 | 저장 필드명 | 타입 | 설정 안내 | 비고 |
|---|---|---|---|---|
| ad_account_id | ad_account_id | 문자열 | 예시 설정 | 광고 계정 ID |
| campaign_id | campaign_id | 문자열 | 예시 설정 | 캠페인 ID |
| ad_group_id | ad_group_id | 문자열 | 예시 설정 | 광고 그룹 ID |
| ad_creative_id | ad_creative_id | 문자열 | 예시 설정 | 광고 소재 ID |
| event_date | event_date | 날짜 | 예시 설정 | 데이터 날짜 |
| channel | channel | 문자열 | 예시 설정 | 채널 |
| platform | platform | 문자열 | 선택 설정 | 플랫폼 |
| event_type | event_type | 문자열 | 선택 설정 | 이벤트 타입 |
| event_source | event_source | 문자열 | 선택 설정 | 이벤트 소스 |
| event_category | event_category | 문자열 | 선택 설정 | 이벤트 분류 |
파싱하거나 저장할 때
group_by의 순서를 변경하지 마십시오. 순서가 바뀌면 차원 값이 어긋날 수 있습니다.
2.4.3 확장 파라미터
Airbridge Actuals Report는 필터링과 정렬을 지원합니다. extra_params에서 filters와 sorts를 설정할 수 있습니다.
| 구성 항목 | 필수 여부 | 설명 |
|---|---|---|
| extra_params.filters | 아니요 | 필터 조건, dimension은 source.group_by에 속해야 함 |
| extra_params.sorts | 아니요 | 정렬 조건, fieldName은 source.group_by 또는 source.metrics에 속해야 함 |
설정 예시:
{
"extra_params": {
"filters": [
{
"dimension": "channel",
"filterType": "IN",
"values": [
"App"
]
}
],
"sorts": [
{
"fieldName": "event_date",
"isAscending": true
}
]
}
}
2.5 설정 제한
| 모듈 | 제한 항목 | 규칙 |
|---|---|---|
| 동기화 | 1회 조회 기간 | 최대 400일 |
| 조회 가능 기간 | 최대 1000일 | |
| 통합 설정 | source.group_by | 최대 10개 |
| source.metrics | 최대 20개 | |
| extra_params.filters[].dimension | source.group_by에 속해야 함 | |
| extra_params.sorts[].fieldName | source.group_by 또는 source.metrics에 속해야 함 |
2.6 이벤트 저장 규칙
Airbridge Actuals Report의 리포트 결과는 평면적인 필드 객체가 아니라 groupBys와 values로 구성됩니다.
- Actuals Report가 반환하는 데이터는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다.
- 데이터의
event_date필드, 즉 데이터 날짜를 집계 데이터의#event_time으로 설정합니다. - 템플릿에서 사용하는 이벤트 이름은
airbridge_event_data입니다. 변경하려면sink_event.event_name을 조정하십시오. groupBys는 요청의source.group_by순서대로 반환됩니다.- 저장 시
groupBys배열의 값을 같은 순서로 해당 차원 필드에 기록합니다. values.<metric>.value는 지표 값으로 이벤트 속성에 기록됩니다.- 그 밖에 인식 가능한 지표와 차원 필드는 모두 저장됩니다.
- 지표가
isMasked=true를 반환하면 해당 지표 값이 Airbridge에 의해 마스킹되거나 숨겨졌다는 의미이므로 분석 시 유의해야 합니다. - 응답에
notifications가 있으면 Airbridge가 집계 결과에 대해 알림을 표시했거나 처리를 했다는 의미이므로, 데이터 차이를 조사할 때 참고하는 것을 권장합니다.
예시:
{
"groupBys": [
"2026-06-02",
"facebook.business",
"120239009297780452"
],
"values": {
"app_events": {
"value": 2,
"isMasked": false
}
}
}
요청의 group_by가 ["event_date", "channel", "campaign_id"]이면 위 데이터는 다음과 같이 매핑됩니다:
| 저장 필드 | 저장 값 |
|---|---|
| event_date | 2026-06-02 |
| channel | facebook.business |
| campaign_id | 120239009297780452 |
| app_events | 2 |
2.7 표준화 필드
Airbridge 필드는 AE 시스템의 광고 표준 객체 te_ads_object에 따라 표준화할 수 있지만, 최종 매핑 관계는 Airbridge 필드의 의미와 AE 시스템의 공통 필드 정의를 함께 확인한 후 게시해야 합니다.
| 원본 필드 | 표준화 필드 | 의미 |
|---|---|---|
| ad_account_id | te_ads_object.ad_account_id | 광고 계정 ID |
| campaign_id | te_ads_object.campaign_id | 캠페인 ID |
| campaign | te_ads_object.campaign_name | 캠페인 이름 |
| ad_group_id | te_ads_object.ad_group_id | 광고 그룹 ID |
| ad_group | te_ads_object.ad_group_name | 광고 그룹 이름 |
| ad_creative_id | te_ads_object.ad_id | 광고 ID |
| ad_creative | te_ads_object.ad_name | 광고 이름 |
| channel | te_ads_object.media_source | 미디어 소스 |
| platform | te_ads_object.platform | 플랫폼 |
| country | te_ads_object.country | 국가/지역 |
| currency | te_ads_object.currency | 통화 |
| agency_of_the_tracking_link_creator | te_ads_object.agency | 대행사 |
| app_package_name | te_ads_object.app_id | 앱 ID |
| airbridge_app_name | te_ads_object.app_name | 앱 이름 |
| impressions_channel | te_ads_object.impressions | 노출 |
| clicks_channel | te_ads_object.clicks | 클릭 |
| cost_channel | te_ads_object.cost | 광고 비용 |
| app_installs | te_ads_object.installs | 설치 |
3. 후속 사용
3.1 데이터 저장 확인
계획을 저장하고 활성화한 후 AE 시스템에서 sink_event.event_name에 해당하는 이벤트에 데이터가 저장되었는지 확인할 수 있습니다.
3.2 단일 수집
특정 날짜 범위의 데이터를 임시로 보충 수집해야 하는 경우 단일 수집 기능을 사용할 수 있습니다. 보충 수집 시에도 Airbridge Actuals Report의 날짜 범위 제한을 준수해야 합니다.
1회 보충 수집의 날짜 범위는 400일을 초과할 수 없습니다.
3.3 데이터 차이 조사
AE 시스템의 데이터가 Airbridge 백엔드에 표시되는 데이터와 일치하지 않으면 다음 설정을 먼저 확인하는 것을 권장합니다:
date_range와 데이터 수집 시간대가 Airbridge 리포트 기준에 맞는지 여부.metrics와group_by가 Airbridge 백엔드 리포트에서 선택한 항목과 일치하는지 여부.filters와sorts가 반환 결과에 영향을 주었는지 여부.- 페이지 단위 결과를 모두 읽었는지 여부.
- 반환 결과에
isMasked=true또는notifications가 있는지 여부.