본문으로 건너뛰기

AppsFlyer FAQ(자가 점검용)

최근 업데이트 2026. 10. 07.

1. Push Api​

1.1 SDK 초기화 순서(필독)​

경고

ThinkingData SDK와 AF SDK는 반드시 다음 절차에 따라 초기화하고 인터페이스를 호출해야 합니다

  • ThinkingData 클라이언트 SDK를 초기화합니다
  • 자동 통합 또는 수동 통합 인터페이스를 호출하여 distinct_id를 서드파티 이벤트에 설정합니다(설정 코드는 공식 문서 AppsFlyer Push API를 참고하십시오. 이 문서에서는 자세히 설명하지 않습니다)
  • AF SDK를 초기화합니다

1.2 AE 설정 - 데이터 소스의 엔드포인트 주소가 비어 있는 경우 처리​

  • AE 백엔드의 프로젝트 관리 - 연동 설정 - 데이터 수집 주소에 8991 포트의 서버 주소를 추가합니다. 서버 주소는 회사의 운영 관리 담당자에게 확인할 수 있습니다. 이후 AppsFlyer 플랫폼의 엔드포인트 주소가 자동으로 동기화됩니다.

1.3 콜백 계획의 상태 상세 설명​

1.3.1 상태 1: 연동 오류​

  • 연동 오류의 원인

    • AF 콜백 계획을 생성하거나 업데이트한 후 2시간 이내에 콜백된 데이터가 없음.
    • 72시간 이내에 연동된 데이터는 있지만 변환 실패가 있거나, 72시간이 넘도록 새 이벤트가 콜백되지 않음.

  • 변환 실패 원인 분석

    • 데이터 변환 실패 원인을 확인하려면 계획 오른쪽 상단의 상세 아이콘을 클릭하고 데이터 상세 정보에서 변환 실패 원인을 확인합니다

    • 시나리오: 변환 실패, 사유: 유저 ID를 연결할 수 없음

      • 문제 원인 1: 문서의 요구 사항에 따라 AE 유저 식별자를 AF 이벤트에 할당하지 않았기 때문입니다
      • 문제 원인 2: 이전 버전의 APP에서 유저 식별자를 AF 이벤트에 설정하지 않았거나 ThinkingData SDK를 통합하지 않았기 때문입니다
      • 구체적인 조사 절차는 서드파티 데이터 콜백 유저 변환 실패 문제 해결 모범 사례를 참고하십시오

1.3.2 상태 2: 연동됨​

  • 플랫폼 연동 상태가 연동됨이면 해당 플랫폼에서 데이터를 수신했고 데이터가 이미 저장되었음을 의미합니다. 이때 통합 페이지 또는 각 플랫폼의 설정 페이지에서 상세 데이터를 클릭하여 최근 수신한 1000건의 데이터를 바로 확인할 수 있습니다:

1.3.3 상태 3: 연동 대기 중​

  • 설정을 완료한 후 AE로 콜백된 이벤트가 없거나, 계획을 수정한 후 AE로 콜백된 새 데이터가 없는 상태입니다

1.4 AF-install과 AE-ta_app_install 이벤트 수가 일치하지 않는 문제​

  • 일반적으로 설치 이벤트의 수집 규칙이 다르기 때문입니다. ta_app_install은 APP을 새로 설치하거나 삭제 후 재설치할 때마다 한 번씩 트리거됩니다. 반면 af sdk install에는 일정한 윈도우 기간이 있어, 윈도우 기간 내에 삭제 후 재설치해도 설치 이벤트를 다시 전송하지 않습니다. AF 윈도우 기간은 다음 문서를 참고하십시오: 재어트리뷰션 윈도우 기간 상세 설명

  • 자연적으로 발생하는 차이 외에 기타 데이터 차이의 조사 단계는 다음과 같습니다(1, 2, 3 순서로 조사할 것을 권장합니다):

    사용 인터페이스설치 차이인앱 이벤트 차이

    Push API

    1.비교 샘플링 기간이 너무 짧지 않은지, 비교하는 시간대가 일치하는지

    2.AE SDK 또는 AppsFlyer SDK가 연동되지 않은 App 버전이 있는지

    3. AE 서버가 수신한 AppsFlyer의 install 이벤트에 Custom Data/Customer User Id 필드가 포함되어 있고 값이 정상적으로 비어 있지 않은지

    4.AppsFlyer 백엔드에서 다운로드한 원본 데이터의 Custom Data/Customer User Id 필드의 키 이름이 ta_account_id, ta_distinct_id인지

    5.AppsFlyer 백엔드에서 다운로드한 원본 데이터의 Custom Data/Customer User Id 필드에 누락된 값이 있는지

    5.1 비어 있지 않다면 Push API 푸시 설정 시 Custom Data/Customer User Id를 선택하지 않은 것입니다

    5.2 비어 있다면 클라이언트 SDK가 Custom Data/Customer User Id를 전송하지 않은 것입니다

    6.AppsFlyer SDK가 setAdditionalData() 또는 setCustomerUserId()로 ta_account_id 또는 ta_distinct_id를 전송할 때 실패율이 높은지

    7.서버 보안 그룹의 인바운드 허용 대상 설정을 확인하십시오. 모든 AppsFlyer IP 주소를 화이트리스트에 추가할 수도 있습니다

    1. AppsFlyer 이벤트 테이블 데이터 저장 설정을 활성화했는지
    2. 비교 샘플링 기간이 너무 짧지 않은지, 비교하는 시간대가 일치하는지
    3. AE SDK 또는 AppsFlyer SDK가 연동되지 않은 App 버전이 있는지
    4. 비용 차이: Facebook, Google 등 SRN 채널을 연동했는지. 이러한 채널의 비용 데이터는 Push API로 가져올 수 없습니다
    5. 수익 차이: 수익을 담는 데 사용하는 이벤트 이름이 무엇인지 확인하고, 해당 이벤트를 AppsFlyer가 일괄로 가져오는지 실시간으로 가져오는지 확인합니다

1.5 콜백 이벤트가 모두 전환 성공했는데 데이터를 조회할 수 없는 원인은 무엇인가요​

  • 프로젝트에서 강력 검증 모드를 활성화했는지 확인하십시오. 활성화되어 있으면 먼저 이 모드를 끄고, 데이터가 한 차례 콜백된 후 다시 활성화할 것을 권장합니다.
  • 강력 검증 모드인지 확인: 오른쪽 상단의 설정 버튼을 클릭하고 프로젝트 관리를 찾아 클릭한 후 데이터 처리 규칙을 확인합니다.

1.6 기타​

1.6.1 채널 media_source에 restricted가 표시되거나 변환 후 유저 속성에 media_source만 있는 문제​

  • Google Install Referrer를 기반으로 AppsFlyer Android FB 유저 수준 데이터를 가져오는 방안을 참고할 수 있습니다.

1.6.2 AppsFlyer 채널 media_source가 비어 있지만 캠페인 이름에는 값이 있는 경우​

  • 일반적으로 대행사 투명성과 관련이 있으므로 대행사 투명성을 활성화한 후 다시 확인해 보십시오. 자세한 내용은 문서를 참고하십시오.

1.6.3 S2S 데이터를 연동하고 변환하는 방법​

  • AppsFlyer S2S 데이터를 연동할 때는 이후 AE 유저와 연결할 수 있도록 클라이언트 SDK에서 가져온 customer_user_id 또는 custom_data 필드를 전송해야 합니다. S2S 필드의 구체적인 전송 방법은 AppsFlyer 모바일 기기용 S2S 이벤트 API(S2S-mobile)를 참고하십시오

1.6.4 AppsFlyer Push API Raw data 데이터를 다운로드하는 방법​

  • AppsFlyer 백엔드에 로그인하여 대시보드 왼쪽 탐색 메뉴에서 Export - Raw Data Export로 이동한 후 organic 및 non-organic 이벤트를 선택하고 create를 클릭합니다. 이어서 customize를 선택하고 custom_data 필드를 선택한 후 데이터를 다운로드합니다

1.6.5 te_ads_object 속성은 무엇을 의미하며, 다른 필드를 저장할 수 있나요​

  • te_ads_object 객체는 표준화된 객체 필드로, 서드파티 플랫폼마다 필드 이름은 다르지만 의미가 같은 필드를 이 객체에 통일하여 저장하여 이후 분석에 활용할 수 있도록 합니다.
  • 가능합니다. 유저 속성 저장 규칙 설정 모듈에서 설정할 수 있으며, 소스 데이터명은 변환 전 필드이고 대상 속성명은 저장할 필드 이름입니다
    • 예: af가 콜백한 원본 데이터 필드 idfa를 te_ads_object 객체에 매핑합니다.

2. Pull/Master/Cohort Api​

2.1 수집 빈도 설정 권장 사항​

API당일 데이터 수집 지원 여부수집 빈도 선택 방법
Pull API

예

실시간 요구가 없으면 매일 정오 12시(UTC)에 AppsFlyer의 최근 3-7일 데이터를 수집할 것을 권장합니다. 높은 실시간성이 필요하면 매시간 수집합니다.

Master API

아니요

실시간 요구가 없으면 매일 정오 12시(UTC)에 AppsFlyer의 지난 3-7일 데이터를 수집할 것을 권장합니다. 높은 실시간성이 필요하면 매시간 수집합니다.
Cohort API아니요실시간 요구가 없으면 매일 정오 12시(UTC)에 AppsFlyer의 지난 3-7일 데이터를 수집할 것을 권장합니다. 높은 실시간성이 필요하면 매시간 수집합니다.

2.2 같은 계획에 여러 App ID를 설정하려면 어떻게 하나요?​

  • 여러 App ID를 영문 쉼표 ,로 구분하면 됩니다. 아래 그림과 같습니다

2.3 같은 기간의 데이터를 반복 수집하면 중복 데이터가 생기나요?​

  • 같은 기간의 데이터를 여러 번 수집해도 데이터가 중복되지 않습니다. 같은 기간의 데이터는 새 데이터로 전체 덮어쓰기됩니다

2.4 수집 이벤트 이름은 어떻게 수정하나요?​

  • Pull Api

    • partner 데이터를 수집하도록 설정했다면 event_mapping 객체에서 partner에 해당하는 값을 수정하십시오.
    • geo 데이터를 수집하도록 설정했다면 event_mapping 객체에서 geo에 해당하는 값을 수정하십시오.

  • Master Api

    • event_name에 해당하는 값을 수정하면 됩니다

  • CohortApi

    • event_name에 해당하는 값을 수정하면 됩니다

2.5 데이터 수집 성공·실패 확인 방법​

  • 설정에 성공한 후 계획 오른쪽 상단의 단일 수집을 클릭하면 수집 결과가 내부 메시지로 통지됩니다.
  • 수집 성공 예시
  • 수집 실패 예시

2.6 시간대를 지정하여 AF 데이터를 수집하는 설정​

  • extra_params - timezone 설정을 추가합니다. 전체 예시는 다음과 같습니다

    팁

    • 주의 사항:

      • af에 설정하는 시간대는 AF 백엔드에 설정된 시간대와 같아야 합니다

      • AE 백엔드에 설정하는 시간대는 urlencode(http://www.jsons.cn/urlencode/) 변환을 거쳐야 합니다:

    • AF 공식 웹사이트 설명
    • 예시 
      • {
          "extra_params": {
            "timezone": "China%2FShanghai"
          },
          "sink_event": {
            "event_mapping": {
              "geo": "appsflyer_geo_data",
              "partner": "appsflyer_partner_data"
            }
          },
          "sink_user": [],
          "source": {
            "report_types": [
              "partner"
            ]
          },
          "transfer": {
            "fields_whitelist": [
             " 。。。。"
            ],
            "double_columns": [
             " 。。。。"
            ]
          }
        }

2.7 SKAN 데이터 콜백을 지원하나요?​

  • 현재 미지원: iOS 플랫폼의 제한으로 인해 현재 AE 유저 식별자를 SKAN 이벤트에 설정할 수 없습니다

2.8 자주 발생하는 수집 오류 및 처리 방법​

  • Create event and props failed!

    • 이 오류는 일반적으로 처음 데이터를 수집하거나 계획에 수집 필드를 새로 추가할 때 발생하며, 서버 과부하로 새 필드 생성에 실패하여 발생했을 수 있습니다. 약 10분 정도 기다린 후 데이터 수집을 다시 시도하십시오. 문제가 계속되면 전담 그룹 채팅의 ThinkingAI 고객 성공 매니저(CSM) 또는 ThinkingAI 기술 담당자에게 문의하십시오.
    이미지 없음：img-7250795c0df5

  • Get thirdparty data failed! The possible error is: AppsFlyer - Page Not Found

    • 가능한 원인 1: AF cohort & master API는 AF 유료 API이므로 관련 권한이 활성화되어 있는지 확인하십시오.
    • 가능한 원인 2: 잘못된 AppID를 입력했을 수 있습니다. AE 계획에 설정한 AppID가 AF 관리 백엔드에서 제공한 것과 일치하는지 확인하십시오.
    • 가능한 원인 3: App ID가 AppsFlyer 측에서 아직 출시되지 않아 테스트 상태에 있습니다.
    • 위 원인에 모두 해당하지 않으면 전담 그룹 채팅의 ThinkingAI 고객 성공 매니저(CSM) 또는 ThinkingAI 기술 담당자에게 문의하십시오.
    이미지 없음：img-504127009267

2.9 기타​

2.9.1 수집한 데이터와 AppsFlyer 대시보드의 데이터가 일치하지 않는 문제​

  • AppsFlyer에서 대조한 지표와 AE 백엔드에서 대조한 데이터 지표가 같은지 확인합니다.

    • 차원이 다르거나 파라미터 설정 때문에 데이터 차이가 발생했는지 분석합니다
    • 선택한 앱/비용 채널이 일치하지 않음

  • AppsFlyer 플랫폼 대시보드 데이터의 시간대와 계획의 수집 시간대가 일치하는지 확인합니다(계획은 기본적으로 UTC 시간대로 데이터를 수집합니다)

  • AppsFlyer api 데이터에는 지연과 업데이트에 따른 변동이 있으므로, 일부 날짜의 데이터가 부정확하다면 계획 오른쪽 상단의 단일 수집을 클릭하여 다시 수집해 보십시오.

  • 위 내용을 확인해도 해결되지 않으면 ThinkingAI 기술 지원에 문의하여 조사를 요청하십시오.

2.9.2 AppsFlyer 대시보드 코호트 분석 리포트의 수익 데이터와 Master API로 수집한 데이터가 일치하지 않는 문제​

  • 아래 그림과 같이 AppsFlyer의 코호트 대시보드에서 확인하는 수익 데이터는 활성화 후의 누적 값이므로, Cohort api를 호출하여 데이터를 수집한 후 대조해야 합니다.
    이미지 없음：img-e47832d7ddef

2.9.3 Cohort API로 수집한 데이터에서 FB 채널에 cost 값이 없는 문제​

  • cost는 합계 데이터가 아니므로 그룹 항목에 따라 데이터 차이가 발생할 수 있습니다. 예를 들어 Geo와 Channel을 동시에 그룹 항목으로 사용하면 FB의 cost 값이 0이 됩니다. AF 공식 문서 설명: 비용 지표는 일부 그룹 차원과 결합할 수 없습니다. 예를 들어 Facebook 데이터는 Geo(국가/지역) 또는 Channel(트래픽 유입 경로)로 그룹화할 수 있지만 이 두 차원을 동시에 결합하여 그룹화할 수는 없습니다. 사용 가능한 그룹 차원 조합은 광고 플랫폼에 따라 다릅니다. 자세한 내용은 ThinkingAI 기술 지원에 문의하십시오.

2.9.4 Cohort API로 수집한 데이터에서 applovin 채널에 cost 값이 없는 문제​

  • group_by를 "date","c","pid"로 설정하여 cost 데이터가 있는지 확인합니다.

2.9.5 AppsFlyer Master API의 최근 7일 cost 데이터가 AF 백엔드의 데이터 개요 대시보드와 일치하지 않음​

  • AF 백엔드에서 대조하는 개요 대시보드의 보기 유형을 User acquisition, 즉 활성화 유저의 데이터로 필터링해야 합니다. Master API는 활성화 유저의 비용 데이터 수집만 지원합니다. 자세한 내용은 문서 https://support.appsflyer.com/hc/zh-cn/articles/213223166#limitations를 참고하십시오

추가 질문​

일부 데이터가 without_id로 표시됨​

  • without_id인 데이터의 App version이 일치하는지 확인합니다
  • 최신 버전 앱에서도 without_id가 발생하는지 확인합니다
  • 클라이언트 ID 연결 로직을 확인하여 ThinkingData SDK 초기화 → AF에 ID 전달 → AF SDK 초기화 순서를 지키는지 확인합니다

AF에서 Adjust로 전환할 때 주의할 점​

  • 게스트 ID를 Adjust에 할당해야 합니다(새 버전을 다시 출시해야 함)
  • 비용 데이터는 Adjust Report API를 연동할 것을 권장합니다
  • Facebook 광고를 집행하는 경우 Adjust 실시간 콜백 부록을 참고하여 Facebook 상세 광고 정보를 설정해야 합니다

AE의 FB 채널 유저 데이터가 AF 백엔드보다 많음​

  • 사유: install 이벤트와 af_app_install 이벤트는 모두 AF 플랫폼이 AE로 콜백한 데이터이며, AF 플랫폼에서 이 두 이벤트는 같은 유형의 행동에 대한 서로 다른 데이터 소스입니다
  • 해결: 이벤트 정의를 구분하는 데 유의하십시오

AF revenue raw data 수집 실패​

  • 사유: group by 설정 문제
  • 해결: group by 설정을 확인하여 gp_install_begin, campaign_type, att, keyword_match_type, conversion_type 등 필수 필드가 포함되어 있는지 확인합니다

AF pull raw data는 timezone 필드를 지원하지 않음​

  • Pull API raw data 인터페이스는 시간대 설정을 지원하지 않습니다

AF 리타기팅 비용 수집​

  • 리타기팅 비용 또는 리타기팅 비용이 포함된 데이터는 Cohort API로 수집해야 합니다

AF meta 데이터의 country 수집 값이 0임​

  • 사유: 설정에 event_mapping이 누락되었습니다
  • 해결: 표준 설정으로 교체하고 계획을 저장한 후 다시 수집합니다. 먼저 오늘 하루의 데이터를 수집하고, 성공하면 과거 데이터를 수집합니다

AF master FB 비용이 일치하지 않음​

  • 사유: 문서에 따르면 geo와 channel은 동시에 전달할 수 없습니다
  • 해결: 둘 다 삭제해야 AF 백엔드와 일치합니다

설정 보충​

저장 필드 화이트리스트(fields_whitelist)를 추가하는 방법​

transfer에 fields_whitelist를 추가합니다. 형식은 ["field_1", "field_2"]이며, 저장할 필드를 지정하는 데 사용합니다:

"transfer": {
  "double_columns": ["impressions", "installs", "loyal_users"],
  "fields_whitelist": ["agency_pmd_af_prt", "app_id", "arpu"]
}

Master API 시간대를 설정하는 방법​

Master API는 기본적으로 UTC 시간대를 사용하며, extra_params로 timezone을 preferred(앱 시간대)로 설정할 수 있습니다:

"extra_params": {"timezone": "preferred"}

Cohort API 시간대를 설정하는 방법​

preferred_timezone의 기본값은 true(앱 시간대)입니다. UTC 시간대로 설정하려면 preferred_timezone을 false로 설정하고 custom_properties(base64 인코딩)를 사용해야 합니다:

"extra_params": {
    "custom_properties": "eyJwcmVmZXJyZWRfdGltZXpvbmUiOmZhbHNlfQ"
}

Cohort로 총비용을 가져오는 방법​

총비용(리타기팅 cost 데이터 포함)을 가져오려면 {"cohort_type":"unified"}를 설정합니다:

"extra_params": {
    "custom_properties": "eyJjb2hvcnRfdHlwZSI6InVuaWZpZWQifQ=="
}

Cohort 집계 타입을 설정하는 방법​

aggregation_type=on_day이면 고유 session 데이터(예: sessions_unique_users_day_*)를 반환하며, 이때 partial_data를 반드시 false로 설정해야 합니다:

{"extra_params": {"aggregation_type": "on_day", "partial_data": "false"}}

오류 보충​

AF Pull API 오류 403 Limit reached for partners-report​

  • AF는 API 수집 빈도를 제한하므로 수집 빈도를 조절하십시오.

AF pull raw data revenue 요청 실패​

  • campaign_type, att, keyword_match_type, conversion_type 등 유효하지 않은 필드를 제거해야 하는 경우 group by 설정을 확인하고 조정하십시오.
이 문서가 도움이 되었나요?
이 페이지의 내용