AppsFlyer Pull Raw Data
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| Pull API Raw Data | API | 유저 수준 | ✅ | ✅ | ✅ |
Pull API Raw Data는 일정 기간의 유저 수준 데이터를 수집할 수 있습니다. 이 통합 방식은 실시간성이 요구되지 않는 상황에서 유저 상세 데이터를 가져올 수 있으며, 유저 단위의 과거 데이터를 수집하는 데도 매우 적합합니다.
통합 절차
- AppsFlyer 클라이언트 SDK와 AE SDK를 연동하고, AF SDK에 AE의 유저 식별 ID를 설정합니다
- AppsFlyer 백엔드에 로그인하여 V2.0 API Token과 App ID를 가져옵니다
- AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 AppsFlyer Pull Raw Data 통합 계획을 추가하고 관련 설정을 완료합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. 클라이언트 SDK 설정
AppsFlyer 데이터 통합의 첫 단계는 클라이언트에서 AE SDK와 AF SDK를 연결하여 AF SDK에 AE 시스템의 유저 식별 ID를 설정하는 것입니다
1.1 방안 1(자동 통합)
- 연동한 AE SDK 버전이 2.8.0~2.8.1이면 이 방안을 바로 사용할 수 있습니다
- 연동한 AE SDK 버전이 2.8.2 이상이면 서드파티 데이터 플러그인도 설치해야 합니다. 자세한 내용은 Android SDK 서드파티 데이터와 iOS SDK 서드파티 데이터를 참고하십시오
// AE SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// AppsFlyer id 연결 활성화
TDAnalytics.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);
// AppsFlyer SDK 초기화
AppsFlyerLib.getInstance().init("appid", null, this);
AppsFlyerLib.getInstance().start(this);
// setcustomerUserId()로 게스트 ID를 한 번 더 설정할 것을 강력히 권장합니다
String distinctId = TDAnalytics.GetDistinctId();
AppsFlyerLib.getInstance().setcustomerUserId(distinctId);
// login을 호출하여 계정 ID를 설정한 후 데이터를 다시 동기화해야 합니다(선택 사항)
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);
AE SDK의 login() 메서드나 identify() 메서드를 호출한 경우 enableThirdPartySharing()을 다시 호출하여 데이터를 동기화해야 합니다.
참고: AppsFlyer SDK의 setAdditionalData() 메서드도 호출해야 하는 경우, 이 메서드를 여러 번 호출하면 이전 파라미터를 덮어쓰므로 파라미터를 AE SDK에 전달할 수 있습니다. AE SDK가 내부에서 파라미터를 병합합니다.
Map<String, Object> additionalData = new HashMap<>();
additionalData.put("af_test_key1", "test1");
additionalData.put("af_test_key2", "test2");
TDAnalytics.enableThirdPartySharing(
TDThirdPartyShareType.TD_APPS_FLYER,
additionalData
);
이 방안은 내부에서 AppsFlyer의 setAdditionalData() 메서드를 자동으로 호출하여 AE 프로젝트의 게스트 ID와 계정 ID를 전달하는 방식으로 동작합니다.
1.2 방안 2(수동 통합)
수동 통합 방안에서는 AppsFlyer SDK에서 setAdditionalData로 AE 프로젝트의 게스트 ID와 계정 ID를 설정해야 합니다. 다음은 Java 코드 예시입니다:
// AE의 게스트 ID 가져오기, AE의 #distinct_id에 대응
String distinctId = TDAnalytics.GetDistinctId();
// 계정 ID(또는 캐릭터 ID), AE의 #account_id에 대응
String accountId = "your_account_id";
// 활성화 시 배포
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);
// setcustomerUserId()로 게스트 ID를 한 번 더 설정할 것을 강력히 권장합니다
AppsFlyerLib.getInstance().setcustomerUserId(distinctId);
...
// 가입 시 배포
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id", distinctId);
CustomDataMap.put("ta_account_id",accountId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);
위와 같이 설정하면 콜백 데이터의 custom_data에 ta_distinct_id, ta_account_id 두 필드가 포함되며, customer_user_id는 게스트 ID와 같아집니다.
2. API Token과 App ID 가져오기
2.1 API Token 가져오기
관리자 계정으로 로그인한 후 AppsFlyer 사이드바 메뉴에서 API Access를 찾아 Pull API Raw Data에 사용할 V2.0 API Token을 가져오십시오.
2.2 App ID 가져오기
AppsFlyer 백엔드의 My Apps에서 앱의 App ID를 찾을 수 있습니다. Android는 com.으로 시작하며(예: com.demoapp.ta), iOS는 id로 시작합니다(예: id12345678)
3. 계획 설정
AppsFlyer의 API Token과 App ID를 가져온 후 AE 시스템에 로그인하여 서드파티 통합 모듈에서 새 계획을 설정할 수 있습니다. 아래 그림은 AppsFlyer Pull Raw Data의 설정 화면입니다. 이 장의 내용에 따라 계획을 생성하십시오:
3.1 인증 정보 설정
인증 정보 아래의 인증 정보 설정 버튼을 클릭하고, 팝업 창에 API Token과 App ID를 입력합니다
3.2 동기화
동기화 모듈에서 AE 시스템이 AppsFlyer Pull Raw Data 데이터를 정기적으로 수집하는 정책을 설정할 수 있으며, 매일 특정 시각에 일정 기간의 데이터를 수집하도록 선택할 수 있습니다. 1회에 최대 31일까지 수집할 수 있습니다. 수집한 데이터도 데이터양에 포함되므로 너무 긴 기간의 데이터를 정기적으로 수집하지 않는 것을 권장합니다
3.3 데이터 수집 시간대
수집할 데이터의 시간대도 설정할 수 있으며, 기본값은 UTC+0입니다
3.4 유저 식별 필드
AppsFlyer Pull Raw Data가 반환하는 것은 유저 수준 데이터이므로 유저 식별 규칙, 즉 AF 콜백 데이터에서 #distinct_id와 #account_id에 대응하는 필드를 설정해야 합니다. AE 시스템은 이 설정에 따라 콜백 데이터를 변환할 때 해당 필드를 데이터의 유저 식별 필드로 설정합니다.
이 문서의 이전 단계에 따라 클라이언트 SDK를 설정한 경우 다음 설정을 사용하십시오:
- 계정 ID 연관 필드: custom_data.ta_account_id
- 게스트 ID 연관 필드: customer_user_id,custom_data.ta_distinct_id
3.5 저장 설정
데이터를 이벤트 형태로 기록할지 제어할 수 있습니다. 끄면 데이터가 이벤트 테이블에 기록되지 않으므로 이 설정을 끄지 마십시오.
3.6 유저 속성 저장 규칙
기본적으로 AE 시스템은 AF 콜백 데이터의 어트리뷰션 필드를 표준화 처리된 유저 속성에 자동으로 기록합니다. 다음은 유저 속성에 기록되는 필드와 그 의미입니다:
| AppsFlyer 필드 | 표준화 필드 | 설명 |
|---|---|---|
| media_source | te_ads_object.media_source | 미디어 채널 |
| campaign | te_ads_object.campaign_name | 캠페인 이름 |
| adset | te_ads_object.ad_group_name | 광고 그룹 이름 |
| ad | te_ads_object.ad_name | 광고 이름 |
이전 버전의 유저 속성 저장 기본 규칙은 현재와 다르므로 구분에 주의하십시오. 새 속성과 기존 속성을 병합해야 한다면 가상 속성 기능을 사용할 수 있습니다
수정이 필요하면 규칙 설정을 클릭하여 저장 규칙 설정 페이지로 이동할 수 있습니다. 아래 그림과 같습니다:
속성 매핑 버튼을 클릭하여 유저 속성에 기록할 필드를 추가할 수 있습니다. 또한 왼쪽의 규칙 버튼을 클릭하여 새 규칙 세트를 추가할 수도 있습니다. 예를 들어 AF가 콜백한 수익화 데이터에서 광고 수익을 추출하여 user_add 방식으로 유저 속성에 기록하면 유저별 누적 광고 수익을 기록할 수 있습니다.
유저 속성 저장을 끄려면 모든 규칙을 중지하면 됩니다:
3.7 통합 설정
마지막으로 통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 여기에는 데이터 유형, 수집할 차원, 저장 후 이벤트 이름 등이 포함됩니다.
통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:
| 모듈 | 이름 | 의미 |
|---|---|---|
| sink_event | event_mapping | 저장 후 이벤트 이름, 커스텀 가능 |
| source | report_types | 수집할 데이터 타입, 커스텀 가능. 기본값은 installs, ad_revenue, 즉 설치 이벤트와 수익화 이벤트입니다 |
| group_by | 데이터의 그룹 차원, 리스트 타입, 커스텀 가능 | |
| extra_params | double_columns | 수치 타입 필드 정의. 여기에 입력한 필드는 수치 타입으로 저장되며, 저장 후 필드명을 입력해야 함 |
기본적으로 Pull API Raw Data는 다음 데이터의 수집을 지원합니다:
AppsFlyer 공식 문서에서 지원하는 더 많은 필드를 확인할 수 있으며, 필요한 필드를 source.group_by에 입력하면 됩니다
3.7.1 기본 포함 지표
| 필드 | 한국어 이름 |
|---|---|
| event_value | 이벤트 값 |
| event_revenue | 이벤트 수익 |
| event_revenue_usd | 이벤트 수익(USD) |
| cost_value | 비용 값 |
3.7.2 기본 차원 필드
| 필드 | 한국어 이름 |
|---|---|
| attributed_touch_time | 어트리뷰션 시간 |
| install_time | 활성화 시간 |
| event_time | 이벤트 시간 |
| event_name | 이벤트 이름 |
| event_value | 이벤트 값 |
| event_revenue | 이벤트 수익 |
| event_revenue_currency | 이벤트 수익 통화 타입 |
| event_revenue_usd | 이벤트 수익(USD) |
| event_source | 이벤트 소스 |
| is_receipt_validated | 영수증 검증 여부 |
| partner | 파트너 |
| media_source | 미디어 채널 |
| channel | 하위 채널 |
| keywords | 키워드 |
| campaign | 캠페인 이름 |
| campaign_id | 캠페인 ID |
| adset | 광고 그룹 이름 |
| adset_id | 광고 그룹 ID |
| ad | 광고 소재 이름 |
| ad_id | 광고 소재 ID |
| ad_type | 광고 유형 |
| site_id | 사이트 ID |
| sub_site_id | 하위 사이트 ID |
| sub_param_1 | 하위 파라미터 1 |
| sub_param_2 | 하위 파라미터 2 |
| sub_param_3 | 하위 파라미터 3 |
| sub_param_4 | 하위 파라미터 4 |
| sub_param_5 | 하위 파라미터 5 |
| cost_model | 비용 모델 (CPC/CPI/CPM/Other) |
| cost_value | 비용 값 |
| cost_currency | 비용 통화 타입 |
| contributor_1_partner | 기여자 1 파트너 |
| contributor_1_media_source | 기여자 1 미디어 채널 |
| contributor_1_campaign | 기여자 1 캠페인 |
| contributor_1_touch_type | 기여자 1 어트리뷰션 타입 |
| contributor_1_touch_time | 기여자 1 어트리뷰션 시간 |
| contributor_2_partner | 기여자 2 파트너 |
| contributor_2_media_source | 기여자 2 미디어 채널 |
| contributor_2_campaign | 기여자 2 캠페인 |
| contributor_2_touch_type | 기여자 2 어트리뷰션 타입 |
| contributor_2_touch_time | 기여자 2 어트리뷰션 시간 |
| contributor_3_partner | 기여자 3 파트너 |
| contributor_3_media_source | 기여자 3 미디어 채널 |
| contributor_3_campaign | 기여자 3 캠페인 |
| contributor_3_touch_type | 기여자 3 어트리뷰션 타입 |
| contributor_3_touch_time | 기여자 3 어트리뷰션 시간 |
| region | 지역 |
| country_code | 국가 코드 |
| state | 주/성 |
| city | 도시 |
| postal_code | 우편번호 |
| dma | DMA 코드 |
| ip | IP 주소 |
| wifi | WI-FI 사용 여부 |
| operator | 이동통신사 |
| carrier | 휴대폰 통신사 |
| language | 언어 |
| appsflyer_id | AppsFlyer ID |
| advertising_id | Advertising ID |
| idfa | IDFA |
| android_id | Android ID |
| customer_user_id | Customer User ID |
| imei | IMEI |
| idfv | IDFV |
| platform | 플랫폼 |
| device_type | 디바이스 타입 |
| os_version | 운영 체제 |
| app_version | 앱 버전 |
| sdk_version | SDK 버전 |
| app_id | App ID |
| app_name | 앱 이름 |
| bundle_id | Bundle ID |
| is_retargeting | 리타겟팅 여부 |
| retargeting_conversion_type | 리타겟팅 전환 타입 |
| attribution_lookback | 어트리뷰션 Lookback |
| reengagement_window | 재참여 윈도우 |
| is_primary_attribution | 주 어트리뷰션 여부 |
| user_agent | 유저 에이전트 |
| http_referrer | HTTP Referrer |
| original_url | 원본 URL |
3.7.3 기본 설정에 추가된 추가 필드
이 부분은 통합 설정의 source.group_by에서 조정할 수 있습니다
| 필드 | 한국어 이름 |
|---|---|
| device_model | 기종 |
| keyword_id | AF의 키워드 ID |
| store_reinstall | 재설치 시의 앱 마켓 |
| deeplink_url | Deeplink 주소 |
| oaid | OAID |
| install_app_store | 설치 시의 앱 스토어 |
| contributor1_match_type | 기여자 1 매칭 모드 |
| contributor2_match_type | 기여자 2 매칭 모드 |
| contributor3_match_type | 기여자 3 매칭 모드 |
| match_type | 어트리뷰션 매칭 모드 |
| device_category | 디바이스 대분류: 휴대폰, 노트북, 기타 |
| gp_referrer | Google Play의 URL referrer |
| gp_click_time | Google Play에서 기록한 광고 클릭 시간 |
| gp_install_begin | Google Play에서 기록한 설치 시간 |
| amazon_aid | Amazon 디바이스 ID |
| keyword_match_type | 키워드 매칭 모드 |
| att | iOS 14+의 ATT 상태 |
| conversion_type | 타입 변환 |
| campaign_type | 캠페인 타입 |
| is_lat | 유저의 데이터 추적 제한 여부. 참이면 IDFA 또는 GAID가 모두 0으로 대체됩니다 |
| custom_data | Custom Data, 유저 식별 필드를 가져오는 데 사용 |
3.8 데이터 저장 규칙
Pull Raw Data 데이터 인터페이스는 여러 종류의 데이터를 저장하며, 각 데이터의 처리 규칙은 다음과 같습니다:
-
Installs 데이터
- user acquisition(UA)만 포함하는 Installs 데이터와 Organic Installs 데이터를 수집합니다
- 데이터는 이벤트 형태로 기록되며, 이벤트 이름은 af_install입니다
- 데이터의 event_time, 즉 이벤트 발생 시각을 이벤트의 #event_time으로 사용합니다
- 기본 유저 속성 저장 규칙에 따라 Installs 데이터의 일부 필드가 유저 테이블에 기록됩니다
- 유저 식별 필드 설정에 따라 유저 식별 필드를 결정합니다. 유저 식별 규칙을 설정하지 않으면 기본적으로 데이터의 customer_user_id를 게스트 ID로 사용합니다. 유저 식별 필드를 가져오지 못한 데이터는 폐기됩니다.
- 모든 필드가 저장되며, double_columns의 필드는 숫자 타입으로, 나머지 필드는 문자열로 저장됩니다
-
Ad Revenue
- Attributed ad revenue와 Organic ad revenue를 수집합니다. 이 중 Attributed ad revenue는 user acquisition(UA)과 retargeting 데이터를 함께 수집합니다
- 데이터는 이벤트 형태로 기록되며, 이벤트 이름은 af_ad_revenue_raw입니다
- 데이터의 event_time, 즉 이벤트 발생 시각을 이벤트의 #event_time으로 사용합니다
- 유저 식별 필드 설정에 따라 유저 식별 필드를 결정합니다. 유저 식별 규칙을 설정하지 않으면 기본적으로 데이터의 customer_user_id를 게스트 ID로 사용합니다. 유저 식별 필드를 가져오지 못한 데이터는 폐기됩니다.
- 모든 필드가 저장되며, double_columns의 필드는 숫자 타입으로, 나머지 필드는 문자열로 저장됩니다
3.9 표준화 필드
다음 이벤트 속성은 표준화 처리됩니다:
| 원본 필드 | 표준화 필드 | 의미 |
|---|---|---|
| media_source | te_ads_object.media_source | 미디어 채널 |
| monetization_network(광고 수익화 데이터) | te_ads_object.media_source | 수익화 채널 |
| campaign | te_ads_object.campaign_name | 캠페인 이름 |
| campaign_id | te_ads_object.campaign_id | 캠페인 ID |
| adset | te_ads_object.ad_group_name | 광고 그룹 이름 |
| ad_unit(광고 수익화 데이터) | te_ads_object.ad_group_name | 수익화 광고의 Unit 이름 |
| adset_id | te_ads_object.ad_group_id | 광고 그룹 ID |
| ad | te_ads_object.ad_name | 광고 이름 |
| ad_id | te_ads_object.ad_id | 광고 ID |
| segment(광고 수익화 데이터) | te_ads_object.placement | 광고 위치 |
| cost_value | te_ads_object.cost | 집행 비용 |
| af_cost_currency | te_ads_object.currency | UA 집행 통화 |
| event_revenue | te_ads_object.revenue | 수익화 수익 |
| event_revenue_currency(광고 수익화 데이터) | te_ads_object.currency | 수익화 수익의 통화 |
| country_code | te_ads_object.country | 국가/지역 코드 |
| platform | te_ads_object.platform | 플랫폼(Android, iOS 등) |
| app_id | te_ads_object.app_id | 앱 ID |
| app_name | te_ads_object.app_name | 앱 이름 |