본문으로 건너뛰기

AppsFlyer Push API

최근 업데이트 2026. 10. 05.
팁

서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다

개요​

인터페이스 소개​

인터페이스명타입세분화어트리뷰션비용수익노출클릭전환
Push API콜백유저 수준✅✅✅✅✅

Push API는 실시간 AppsFlyer 유저 수준 데이터를 제공하며, 광고 노출, 클릭, 활성화, 수익 데이터 등을 포함합니다. 비용 데이터는 AF 플랫폼의 데이터 제한으로 인해 가져오지 못할 수 있습니다.

AF 데이터 연동을 시작하기 전에 AE 시스템의 유저 식별 규칙을 읽고 AE가 #distinct_id와 #account_id로 유저를 식별하는 방식을 이해했는지 확인하십시오

통합 절차​

  1. AppsFlyer 클라이언트 SDK와 AE SDK를 연동하고, AF SDK에 AE의 유저 식별 ID를 설정합니다
  2. AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 AppsFlyer Push API 통합 계획을 추가하고 관련 설정을 완료합니다
  3. AppsFlyer 백엔드에 로그인하여 콜백 설정을 완료합니다
  4. AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다

1. 클라이언트 SDK 설정​

AppsFlyer 데이터 통합의 첫 단계는 클라이언트에서 AE SDK와 AF SDK를 연결하여 AF SDK에 AE 시스템의 유저 식별 ID를 설정하는 것입니다

1.1 방안 1(자동 통합)​

  • Android, iOS SDK를 연동한 경우

  • Unity SDK 버전 2.4.0 이상, Unreal SDK 버전 1.5.0 이상을 연동한 경우 이 방안을 바로 사용할 수 있습니다

팁

AE의 SDK 초기화와 자동 통합 활성화 코드는 반드시 AppsFlyer SDK 초기화 전에 완료해야 합니다. 다음 단계에 따라 진행하십시오:

1. AE SDK를 초기화합니다.

2. `enableThirdPartySharing`을 호출하여 게스트 ID를 자동으로 설정합니다.

3. AppsFlyer SDK를 초기화합니다.

다음은 각 플랫폼 SDK의 코드 예시입니다:

// 1. Android SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. enableThirdPartySharing 인터페이스를 호출하여 ta_distinct_id를 appsflyer 이벤트에 설정
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER);
// 3. setCustomerUserId()로 게스트 ID를 한 번 더 설정할 것을 강력히 권장합니다
String distinctId = TDAnalytics.getDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);
// 4. Appsflyer SDK 초기화
//  ...
// 5. 회원가입 또는 캐릭터 생성 후 login을 호출하여 계정 ID를 설정한 다음 데이터를 다시 동기화해야 함(선택 사항)
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER);
팁

AE SDK의 login() 메서드나 identify() 메서드를 호출한 경우 enableThirdPartySharing()을 다시 호출하여 데이터를 동기화해야 합니다.

AF SDK의 setAdditionalData() 메서드도 호출해야 하는 경우, 이 메서드를 여러 번 호출하면 이전 파라미터를 덮어쓰므로 다음 코드와 같이 파라미터를 AE SDK에 전달할 수 있습니다. AE SDK가 내부에서 파라미터를 병합합니다. 다음은 Android SDK 연동 예시입니다.

Map<String, Object> additionalData = new HashMap<>();
additionalData.put("af_test_key1", "test1");
additionalData.put("af_test_key2", "test2");
instance.enableThirdPartySharing(
    TDThirdPartyShareType.TD_APPS_FLYER,
    additionalData
);

이 방안은 내부에서 AF의 setAdditionalData() 메서드를 자동으로 호출하여 AE 프로젝트의 게스트 ID와 계정 ID를 전달하는 방식으로 동작합니다.

1.2 방안 2(수동 통합)​

수동 통합 방안에서는 AF SDK에서 setAdditionalData() 인터페이스로 AE 프로젝트의 게스트 ID와 계정 ID를 설정해야 합니다.

팁

AE의 SDK 초기화와 setAdditionalData 인터페이스 호출은 반드시 AF SDK 초기화 전에 완료해야 합니다. 다음 단계에 따라 진행하십시오:

1. AE SDK를 초기화합니다.

2. `setAdditionalData`를 호출하여 게스트 ID를 설정합니다.

3. AF SDK를 초기화합니다.

다음은 각 플랫폼 SDK의 수동 통합 코드 예시입니다:

// 1. Android SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. AE의 게스트 ID 가져오기, AE의 #distinct_id에 대응
String distinctId = TDAnalytics.getDistinctId();

// 3. 게스트 ID를 AF 수집 이벤트에 설정
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

// 4. setCustomerUserId()로 게스트 ID를 한 번 더 설정할 것을 강력히 권장합니다
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);

// 5. AppsFlyer SDK 초기화
...

// 6. 회원가입 또는 캐릭터 생성 후 login을 호출하여 계정 ID를 설정한 다음 데이터를 다시 동기화해야 함(선택 사항)
String accountId = "your_account_id";
instance.login(accountId);
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. 계획 설정​

SDK 설정을 완료한 후 AE 시스템 백엔드에 로그인하여 서드파티 통합 모듈에서 AppsFlyer 설정을 완료해야 합니다. 아래 그림은 AppsFlyer의 설정 화면입니다:

2.1 유저 식별 필드​

AppsFlyer가 콜백하는 것은 유저 수준 데이터이므로 유저 식별 규칙, 즉 AF 콜백 데이터에서 #distinct_id와 #account_id에 대응하는 필드를 설정해야 합니다. AE 시스템은 이 설정에 따라 콜백 데이터를 변환할 때 해당 필드를 데이터의 유저 식별 필드로 설정합니다.

이 문서의 이전 단계에 따라 클라이언트 SDK를 설정한 경우 다음 설정을 사용하십시오:

  • 계정 ID 연관 필드: custom_data.ta_account_id
  • 게스트 ID 연관 필드: customer_user_id,custom_data.ta_distinct_id

2.2 이벤트 테이블 저장 설정​

이벤트 테이블 저장 설정 스위치를 켜면 콜백 데이터(활성화 이벤트와 인앱 이벤트 포함)가 모두 이벤트 테이블에 기록됩니다

이벤트 데이터 저장을 활성화할 것을 권장합니다. 다만 기본적으로 AF가 콜백하는 모든 데이터를 수신한다는 점에 유의하십시오. 콜백하는 이벤트 타입이 너무 많으면 AE 프로젝트의 이벤트량이 과도하게 늘어날 수 있습니다. 따라서 AF 플랫폼에서 콜백을 설정할 때 필요한 이벤트만 선택하여 콜백하는 것을 권장합니다.

2.3 유저 속성 저장 규칙​

기본적으로 AE 시스템은 AF 콜백 데이터의 어트리뷰션 필드를 표준화 처리된 유저 속성에 자동으로 기록합니다. 다음은 유저 속성에 기록되는 필드와 그 의미입니다:

AppsFlyer 필드표준화 필드설명
media_sourcete_ads_object.media_source미디어 채널
campaignte_ads_object.campaign_name캠페인 이름
af_adsette_ads_object.ad_group_name광고 그룹 이름
af_adte_ads_object.ad_name광고 이름
팁

이전 버전의 유저 속성 저장 기본 규칙은 현재와 다르므로 구분에 주의하십시오. 새 속성과 기존 속성을 병합해야 한다면 가상 속성 기능을 사용할 수 있습니다

수정이 필요하면 규칙 설정을 클릭하여 저장 규칙 설정 페이지로 이동합니다. 아래 그림과 같습니다

여기에서 유저 속성을 어떤 이벤트에서 가져올지 수정할 수 있습니다. 유저 속성이 빈번하게 기록되지 않도록 하려면 모든 이벤트 포함을 끄고 소스 이벤트명을 install로 수정하십시오. 이렇게 설정하면 AE 시스템은 AF가 콜백한 install 이벤트에서만 유저 속성에 기록할 필드를 추출하여 기록합니다. 저장 방식의 기본값은 user_setOnce이며, 최초로 전송된 정보만 유지됩니다.

속성 매핑 버튼을 클릭하여 유저 속성에 기록할 필드를 추가할 수 있습니다. 또한 왼쪽의 규칙 버튼을 클릭하여 새 규칙 세트를 추가할 수도 있습니다. 예를 들어 AF가 콜백한 수익화 데이터에서 광고 수익을 추출하여 user_add 방식으로 유저 속성에 기록하면 유저별 누적 광고 수익을 기록할 수 있습니다.

유저 속성 저장을 끄려면 모든 규칙을 중지하면 됩니다:

2.4 엔드포인트 주소​

엔드포인트 주소에는 AE 시스템이 AppsFlyer 콜백 데이터를 수신하는 주소가 표시됩니다. 이 주소를 그대로 복사하여 이후 AF 콜백을 설정할 때 입력하십시오:

여기에 주소가 표시되지 않으면 오른쪽 상단 메뉴의 프로젝트 관리 → 프로젝트 구성 → 연동 설정에서 공용 네트워크 주소를 설정하십시오. 설정 페이지 알림 배너의 데이터 수집 주소 링크를 클릭하여 이동할 수도 있습니다. 이 주소는 AE SDK에 설정한 데이터 수집 주소입니다. 설정한 후 AppsFlyer 설정 페이지로 돌아와 엔드포인트 주소에서 주소를 복사하십시오.

2.5 이벤트 저장 규칙​

  • 데이터의 event_time_selected_timezone 필드에서 시간과 시간대 정보를 가져와 시간은 #event_time으로, 시간대는 #zone_offset으로 기록합니다. event_time_selected_timezone이 비어 있으면 event_time을 #event_time으로 사용하며, 시간대 #zone_offset은 0으로 설정됩니다
  • 데이터 이벤트 이름은 해당 이벤트의 AppsFlyer에서의 이벤트 이름입니다
  • 나머지 필드는 모두 저장됩니다

2.6 표준화 필드​

다음 이벤트 속성은 표준화 처리됩니다:

원본 필드표준화 필드의미
media_sourcete_ads_object.media_source미디어 채널
monetization_network(광고 수익화 데이터)te_ads_object.media_source수익화 채널
campaignte_ads_object.campaign_name캠페인 이름
af_c_idte_ads_object.campaign_id캠페인 ID
af_adsette_ads_object.ad_group_name광고 그룹 이름
ad_unit(광고 수익화 데이터)te_ads_object.ad_group_name수익화 광고의 Unit 이름
af_adset_idte_ads_object.ad_group_id광고 그룹 ID
af_adte_ads_object.ad_name광고 이름
af_ad_idte_ads_object.ad_id광고 ID
placement(광고 수익화 데이터)te_ads_object.placement광고 위치
af_cost_valuete_ads_object.cost집행 비용
af_cost_currencyte_ads_object.currencyUA 집행 통화
event_revenuete_ads_object.revenue수익화 수익
event_revenue_currency(광고 수익화 데이터)te_ads_object.currency수익화 수익의 통화
country_codete_ads_object.country국가/지역 코드
platformte_ads_object.platform플랫폼(Android, iOS 등)
app_idte_ads_object.app_id앱 ID
app_namete_ads_object.app_name앱 이름

3. AppsFlyer Push API 설정​

AE 백엔드 설정을 완료한 후 관리자 계정으로 AppsFlyer 백엔드에 로그인하여 Integration - API Access에서 Push API 부분을 찾아 다음과 같이 콜백 주소를 설정하십시오:

  • 콜백 API 버전(Push API Version)

    • 2.0 버전을 선택하십시오

  • HTTP 요청 메서드(HTTP method)

    • AE 시스템은 POST와 GET 방식의 콜백을 모두 지원하며, POST 방식을 선택할 것을 권장합니다

  • 엔드포인트 주소(Endpoint URL)

    • AE 시스템 백엔드의 AppsFlyer 설정 페이지에 있는 엔드포인트 주소 항목에서 주소를 가져와 그대로 붙여 넣으면 됩니다

  • 이벤트 메시지 타입(Event Messages)

    • 최소한 활성화(Install) 이벤트는 선택해야 합니다. 다른 인앱 이벤트(Install in-app events)도 콜백하려면 여기에서 체크하고, 콜백할 인앱 이벤트(In-app events)에 콜백할 이벤트의 이벤트 이름을 입력하십시오

  • 콜백 필드(Message Fields)

    • 메시지 필드에는 최소한 다음 정보가 포함되어야 합니다:

      • 모바일 어트리뷰션 관련 필드: media_source, channel, af_adset, af_ad 등
      • 유저 식별 ID 관련 필드: custom_data, customer_user_id, event_value 등
      • 이벤트 속성 또는 유저 속성으로 사용할 필드: app_version, platform 등
      • 이벤트 관련 필드: event_time_selected_timezone

  • 콜백할 인앱 이벤트(In-app events)

    • 필요에 따라 콜백할 이벤트를 선택합니다. 콜백하려면 이벤트 메시지 타입(Event Messages)에서 인앱 이벤트 콜백(Install in-app events)을 체크하십시오
팁

Facebook 데이터를 콜백하려면 AF 백엔드의 Facebook 채널 설정에서 Facebook 데이터 사용 약관(Terms of Service)에 동의해야 합니다. 동의하지 않으면 Facebook의 유저 수준 데이터를 가져올 수 없습니다.

4. 후속 사용​

4.1 데이터 저장 확인​

데이터 관리 페이지에서 콜백 이벤트와 유저 속성이 생성되었는지 확인할 수 있습니다.

이벤트 분석 모델, 유저 속성 분석 모델 등의 분석 모델에서 분석을 통해 데이터가 저장되었는지 확인할 수도 있습니다.

리포트 구축에 대한 몇 가지 권장사항은 다음과 같습니다:

  1. 이벤트 분석 모델에서 AF 콜백 데이터로 광고 집행 및 광고 수익화 핵심 지표를 구성하고 광고 분석 리포트를 생성합니다
  2. 리텐션 분석 모델에서 콜백 데이터의 광고 수익화와 게임 내 결제 이벤트를 결합하여 미디어 채널, 캠페인 등의 세분화 수준별로 광고 수익화를 포함한 LTV를 계산합니다
  3. 퍼널 분석 모델에서 설치 이벤트를 신규 유저 전환 퍼널에 추가하고, 미디어 채널, 캠페인 등의 세분화 수준으로 소스별 유저의 전환 현황을 분석합니다
이 문서가 도움이 되었나요?
이 페이지의 내용