마스터(Master) API 사용하기—캠페인 성과 KPI

요약: API를 사용하여 캠페인 성과 KPI를 얻습니다.

마스터(Master) API—캠페인 성과 KPI 리포트

  • 사용 가능한 KPI는 개요, 액티비티, 프로텍트360 대시보드의 KPI와 동일합니다.
  • 마스터 API를 사용하려면, 확인하고 싶은 데이터를 정의하는 URI를 작성합니다. 이는 풀(pull) API 구현과 비슷하며, 결과는 CSV 또는 JSON 파일로 돌아옵니다.
  • 마스터 API는:
    • 앱스플라이어 피봇 테이블의 기반이 되는 인프라 구조입니다.
    • 에이전시와 파트너에서는 사용할 수 없습니다.
  • 마스터 API의 데이터 최신성: 일 별.

마스터 API 상세

개요 API 호출은 경로(path), 헤더(header) 및 데이터 쿼리를 포함한 JSON 으로 구성됩니다. 기본적으로 데이터는 CSV 파일로 돌아옵니다.
경로 https://hq.appsflyer.com/export/master_report/v4?
HTTP 메소드 GET
데이터 최신성
  • 마스터 API 데이터는 매일 계산됩니다. 업데이트된 데이터는 앱 별 시간대에 따라, 24-48시간 내에 사용 가능합니다.
  • 데이터가 준비되었는지 확인하려면, 여기 설명된 데이터 최신성 엔드포인트(data freshness endpoint)를 사용하십시오.

데이터 최신성 엔드포인트:

  • 데이터 최신성 엔드포인트는 사용 가능한 가장 최근 일자의 날짜를 리턴합니다. 형식은 yyyy-mm-dd 입니다. 예, 2019-12-31.
  • 예시: 2020년 1월 2일에 2019년 12월의 모든 31일 간의 데이터를 가져오려고 합니다. 12월에 대한 마스터 API 호출을 제출하기 전에, 데이터 최신성 엔드포인트에 쿼리하여 2019년 12월 31일이 사용 가능한지 확인합니다. 이는 엔드포인트가 2019-12-31보다 크거나 같은 값을 리턴해야 함을 의미합니다. 

https://hq1.appsflyer.com/master/lastupdate?api_token=[token]

마스터 API 상세

API 파라미터

https://hq.appsflyer.com/export/master_report/v4?api_token=api_token &app_id=app_id&from=from&to=to&groupings=groupings&kpis=kpis

호출 파라미터

파라미터

value 필수적
api_token  AppsFlyerAdmin_us-en.png계정 어드민이 토큰을 가져와야 합니다. 토큰을 확인하려면, 계정에서 email 주소 > API Tokens를 클릭합니다. 네 
app_id
  • 앱스플라이어에서 확인되는 앱 식별자입니다.
  • 앱스플라이어에서 찾은대로 정확하게 앱 ID를 입력하십시오.
  • iOS 앱은 접두사 id를 붙입니다.
from

LTV 어트리뷰션 날짜 기간의 하한입니다.

  • 형식: 스트링 yyyy-mm-dd
  • 예: "from": "2020-01-02"
네 
활용  

LTV 어트리뷰션 날짜 기간의 상한입니다.

  • 기간 범위 내의 일 수: 1-31 일
  • 하루에 대해서는: from 과 to 값이 동일합니다. 
  • 형식: yyyy-mm-dd
  • 예: "from": "2020-01-01", "to": 2020-01-31 는 31 일 입니다.
 네
그룹화

조회 기준(Group by) 파라미터이며, 쉼표(,)로 구분됩니다. 사용 가능한 목록을 보려면 조회 기준(groupings) 표를 참고하십시오. 

예: groupings=pid,geo

 네
KPI

포함할 KPI 목록. 각각은 쉼표로 구분됩니다. KPI 목록을 보려면 아래의 KPI 표를 참고하십시오.

예:kpis=installs,clicks, impressions,sessions,retention_day_7

 네
필터

하나 또는 그 이상의 필터 옵션을 사용하여 데이터를 필터링할 수 있습니다.

아니요
currency 데이터를 앱 별 통화를 사용해 리턴하려면, currency=preferred 를 설정합니다. 아니요
timezeone

데이터를 앱 별 시간대를 사용해 리턴하려면, timezone=preferred 를 설정합니다.

아니요
format

기본으로, 응답 데이터는 CSV 파일 형식으로 받아집니다. JSON 형식으로 받고싶은 경우, URI에 &format=json 를 추가합니다.

아니요

그룹화

이러한 디멘션은 정보를 쉽고 정확하게 조사할 수 있도록, 데이터를 그룹 별로 수집하는 데 사용됩니다. 이 필드의 설명은 여기에서 확인할 수 있습니다.

조회 기준(Group by)
API 이름
조회 기준(Group by) 표시 이름 LTV KPI 리텐션 KPI 액티비티 KPI Protect360 코호트

app_id

앱 ID

pid

미디어 소스

af_prt

에이전시

아니요

C

캠페인

af_adset

광고세트

아니요

af_ad

광고

아니요

af_channel

채널

아니요

af_siteid

퍼블리셔 ID

af_keywords

키워드

아니요

아니요

is_primary

Is Primary Attribution

아니요

아니요

af_c_id

캠페인 ID

아니요

아니요

af_adset_id

광고세트 ID

아니요

아니요

af_ad_id

광고 아이디

아니요

아니요

install_time

Install Time

attributed_touch_type

Touch Type

아니요

지역

지역

KPI

KPI는 앱에 대한 인사이트를 얻기 위해 사용되는 지표입니다. KPI는 다음 탭에서의 유형에 따라 분류됩니다. 

LTV리텐션액티비티코호트프로텍트360
라이프타임 값(LTV) - 인스톨 날짜로 코호트 그룹되어 오늘까지 집계된 종합 이벤트
KPI API 이름  설명
임프레션 선택한 기간 동안 노출 수
클릭 선택한 기간 동안 클릭 수
설치 선택한 기간 동안 인스톨 수
cr 전환율
세션(Sessions) 선택한 기간 동안 앱을 설치한 사용자가 수행한 세션 수
loyal_users 선택한 기간 동안 앱을 설치한 사용자 중 충성 고객 수
loyal_users_rate Loyal Users/Installs
비용 선택한 기간 동안의 총 비용
수익 선택한 기간 동안 앱을 설치한 사용자가 현재까지 누적으로 발생시킨 수익
ROI 특정 기간에 대한 투자 대비 수익률. Return on Investment
arpu_ltv 선택한 기간 동안 앱을 설치한 사용자의 사용자 별 평균 수익. Average revenue per user
average_ecpi 특정 기간에 동안의 인스톨 당 효과 비용(eCPI, Effective Cost per Installation). 비용과 인스톨 수가 API 호출에 포함된 경우에만 사용 가능합니다. 
앱 삭제 선택한 기간 동안 앱을 설치한 사용자 중 앱을 삭제한 사용자
uninstalls_rate 앱 삭제 비율
event_counter_[event%20name] 이벤트가 발생한 횟수
unique_users_[event%20name] 이벤트를 수행한 고유 유저 수
sales_in_usd_[event%20name] 리포트된 이벤트의 일부로서 리포트된 수익

 참고

이벤트 이름은 대소문자를 구분합니다. 이벤트 이름을 포함한 KPI에는 앱스플라이어로 전송된 것과 동일한 이벤트 이름을 사용하십시오.

계산된 KPI

앞서 설명한 KPI에 더하여, 마스터 API 리포트에 계산된 KPI를 추가할 수 있습니다. 이렇게 하면 마스터 API 리포트에 자체 계산된 리포트를 포함시킬 수 있습니다.

계산된 KPI 수식을 위해, 몇 개 든지의 기본 KPI를 삽입할 수 있습니다.

표준 산술 연산자가 지원됩니다: 더하기(+)는 인코딩 되어 %2b, 빼기(-), 곱하기(*), 나누기(/)는 %2f 로 인코딩 됩니다.

계산된 KPI 필드 이름은 반드시 "calculated_kpi_"로 시작하여 유효한 스트링으로 이어져야 합니다. 예, "calculated_kpi_purchaserate"

 

첫 3 일의 리텐션 모음

kpis=installs,loyal_users_rate&calculated_kpi_3days_retention=
retention_day_1%2Bretention_day_2%2Bretention_day_3

광고 노출 당 평균 수익

kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression

코호트 day 7의 ROI

kpis=installs,roi,arpu_ltv,cost,revenue&calculated_kpi_roi_day_7=
(cohort_day_7_total_revenue_per_user-average_ecpi)%2Faverage_ecpi

필터 (선택적)

파라미터 설명 필수적?

pid

특정 미디어 소스가 표시된, 행을 선택하는데 사용됩니다. 쉼표(,)로 구분된 다중 선택이 지원됩니다.

pid=organic,applovin_int

아니요

C

캠페인 이름으로 필터링하는 데 사용됩니다. 쉼표로 구분된 다중 선택이 지원됩니다.

c=my_sample_campaign

아니요

af_prt

에이전시 이름으로 필터링하는 데 사용됩니다. 쉼표로 구분된 다중 선택이 지원됩니다.

af_prt=moburst

아니요

af_channel

채널 이름으로 필터링하는 데 사용됩니다. 쉼표로 구분된 다중 선택이 지원됩니다.

af_channel=Instagram

아니요

af_siteid

퍼블리셔 ID로 필터링하는 데 사용됩니다. 쉼표로 구분된 다중 선택이 지원됩니다.

af_siteid=12345678

아니요

지역

국가로 필터링하는 데 사용됩니다. 쉼표로 구분된 다중 선택이 지원됩니다.

geo=US,DE

아니요

시간 기간 필드

다음의 기간 세분성 옵션이 가능합니다: 일간, 주간

  • ToFrom 시간 기간 필드를 사용하여, 원하는 세분성과 시간 기간 선택을 결정합니다.일간 또는 주간 단위 세분성을 선택한 대로, KPI가 표시됩니다.
  • 주 별 또는 일 별 단위 세분성을 선택하는 경우, 선택한 KPI가 해당하는 세분성에 대응하는지 확인합니다. 더 자세한 내용은 여기를 클릭하십시오.
  • 정확한 주 번호는 여기에서 찾을 수 있습니다.

 

  • 일 별 단위 세분성: 날짜 기간을 From=2017-08-15&to=2017-08-17 처럼 선택합니다.
  • 주 별 단위 세분성: 날짜 기간을 From=2017-w04&to=2017-w12 처럼 선택합니다.

현지화

로컬 통화 및 앱 별 시간대는 앱 설정 페이지에 설정되어 있습니다. 마스터 API 데이터는 시스템 기본 통화 및 시간대를 사용하거나 앱 별 설정된 시간대와 통화를 사용하여 데이터를 추출할 수 있습니다. 

다음 사항이 적용됩니다.

  • 앱 별 시간대/통화를 사용하는 것은 모든 앱이 동일한 시간대/통화를 설정한 경우에만 지원됩니다. 그렇지 않으면, UTC 시간대와 USD 가 사용됩니다. 시간대와 통화는 별도로 분리되어 있습니다. 즉, 모든 앱의 통화 설정은 동일한데 시간대는 그렇지 않다면, 앱 별 통화는 사용할 수 있지만, 앱 별 시간대는 사용할 수 없습니다. 
  • 주간 리텐션 KPI에서는 지역화가 지원되지 않습니다.
  • 대시보드에서 선호하는 시간대가 요청한 시간 기간 이내에 변경되었다면, 생성하는 리포트는 가장 최근의 시간대 변경 이후의 값만 포함합니다.

다음 파라미터를 사용하여 앱 별 설정을 선택하십시오. 참고: 만약 preferred 파라미터를 사용하지 않는 경우, 기본 설정인 USD 통화와 UTC 시간대를 갖게 됩니다.

파라미터 설명 필수적?

currency

앱 별 설정한 통화에 따른 금전적 값.

currency=preferred

아니요

시간대

앱 별 설정한 시간대에 따라 시간대 사용.

timezone=preferred

아니요

마스터 API 결과를 시간대에 맞춰 표시하려면, 반드시 timezone=preferred 파라미터를 사용해야합니다.

호출 예시

시간을 절약할 수 있도록, 여기에 다양한 리포트를 추출하는 마스터 API URL의 목록이 있습니다. 복사하고 붙여 넣기하여 사용하십시오. URL을 사용하기 전에 다음 사항을 확인해야 합니다:

  • 앱 이름을 com.greatapp에서 자사의 안드로이드 또는 iOS 앱의 ID로 변경합니다.
  • [api_token ]을 우리 앱의 API token으로 교체합니다.
  • from 과 to 날짜를 필요한 날짜 기간으로 변경합니다.
  • 필요 사항에 따라 KPI를 변경합니다.
  • 쿼리 URL에 &timezone=preferred&currency=preferred 를 사용하여, 앱 별 시간대와 통화를 사용한 리포트를 가져올 수 있습니다.
페이스북 리포트 정교화

페이스북 광고 성과 비교:

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&pid=facebook
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,roi
구글 애즈 리포트 정교화
구글 애즈 성과 비교:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&pid=googleadwords_int
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,sessions,loyal_users,cost,revenue,arpu_ltv,roi
특정 국가 리포트
예를 들어, 계정 내 모든 앱에 대해 미국과 캐나다를 선택하여, 북미 지역 성과를 확인.
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=geo,pid,c&kpis=
installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,
roi&geo=us,ca	
키워드 효과 리포트
인스톨을 위해 사용된 키워드에 따라 사용자의 ROI와 기타 KPI를 비교합니다.
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_keywords
&kpis=roi,arpu_ltv,average_ecpi,installs,loyal_users_rate,cost,revenue
에이전시 성과 리포트
협업하는 모든 에이전시의 성과를 비교합니다:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=af_prt,pid,c&kpis=installs,
loyal_users_rate
어필리에이트(affiliate) 성과 리포트
미디어 소스 'affiliates' 아래에서 양질의 사용자를 가장 많이 앱 설치시키는, 제일 좋은 어필리에이트를 찾습니다. (어필리에이트로 인스톨 어트리뷰션 하기 관련 더 보기)
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_siteid&pid=affiliates
&kpis=installs,loyal_users_rate,arpu_ltv,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_30,retention_rate_day_30
어트리뷰션 유형 리포트
최상의 사용자들은 클릭, 노출에서 유입됩니까? 또는 오가닉 입니까?
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=attributed_touch_type
&kpis=installs,sessions,loyal_users_rate,arpu_ltv
네트워크 리텐션 리포트
계정 내 모든 앱에 대해 모든 네트워크의 사용자 리텐션 (인스톨 후 day 1, 7, 15, 22, 30)을 비교합니다.
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=pid,c
&kpis=installs,loyal_users_rate,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_22,retention_rate_day_22,retention_day_30,retention_rate_day_30

제한 사항 및 문제 해결

제한 사항

  • 비용 데이터
    • eCPI를 포함한 비용 데이터가 항상 가능하지는 않을 수 있습니다. 이것은 네트워크가 비용 데이터를 지원하는지, 네트워크 유형 (앱스플라이어 링크 사용 또는 self-reporting) 또는 호출한 디멘션에 따라 달라집니다. 비용 데이터가 가능한 상황에서 eCPI를 얻으려면, 호출에 인스톨과 비용을 모두 포함하십시오.
    • 일반적으로, 링크에 비용 파라미터를 가진 앱스플라이어 링크를 사용하는, 온드 미디어(owned media)를 포함한 모든 소스는 요청된 디멘션에 관계없이 비용 데이터를 완전히 지원합니다. 자체 API를 가진 SRN(self-reporting network)는 일반적으로 가능한 디멘션 중 오직 일부 디멘션의 비용 데이터만 지원합니다.
    • 예를 들어, 페이스북은 지역 및 채널 조회 기준(grouping by)을 동시에 지원하지 않습니다. (각각 따로 조회하는 것은 지원됩니다.)
    • 비용 데이터를 지원하는 애드 네트워크 전체 목록은 여기에서 확인하십시오.
  • 조회 기준(Grouping): 특정 조회 기준은 오직 LTV KPI, 액티비티 또는 리텐션 KPI에 대해서만 사용할 수 있습니다. 특정 KPI를 위한 데이터가 가능하지 않을 때는 API가 N/A 라고 리턴합니다. 예를 들어, af_channel로 조회 기준 설정한 retention_rate_day_7d 요청은 “N/A” 로 반환됩니다.
  • 최대 행 갯수: 200,000

문제 해결

 

메시지

참고 

200 OK  
  • 증상: 파일이 리턴되지 않습니다.
  • 송신된 토큰이 없음
401 Unauthorized The supplied API token is invalid
  • 서버가 요청을 인증할 수 없습니다. API 토큰이 누락되었거나 올바르지 않습니다.
  • URL에 정확한 API 토큰이 포함되어 있는지 확인하십시오. API 토큰은 api_token 파라미터로 전달됩니다.
404 Not found
  • 네트워크 문제가 있습니다.
  • 마스터 API가 계약한 플랜의 일부가 아닙니다.
416 No Groupings Selected
  • 마스터 API는 종합 리포트를 제공합니다. 이런 리포트는 어떤 데이터가 통합되는지에 따라 KPI가 필요합니다.
  • 희망하는 조회 기준(grouping)groupings 파라미터에 지정하십시오.
403 인식할 수 없는 날짜 형식입니다. 날짜를 확인한 후 정정하십시오. 
403 From 날짜가 To 날짜 이후일 수 없습니다. 날짜를 확인한 후 정정하십시오. 
403 From 과 To 날짜는 반드시 동일한 세분성 형식을 가져야만 합니다. 날짜를 확인한 후 정정하십시오.
403 아무 KPI도 제공되지 않았습니다.  
403 일 별 쿼리는 주간 필드를 포함할 수 없습니다.  
403 주간 결과는 install_day 별로 조회할 수 없습니다. 쿼리를 재작성하고, 대신 install_time 별로 조회(group by)하는 것을 고려해보십시오.  
403 주 별 쿼리는 일간 필드를 포함할 수 없습니다.  
403 앱스플라이어 주 별 리텐션은 최대 12주 까지 지원합니다.  
403 하나 또는 그 이상의 공식 연산자가 유니코드가 아닌 경우, 지원되지 않습니다.  
403 계산된 kpi 이름이 제공되지 않았습니다.  
416 무언가 잘못되었습니다. 몇 분 후 다시 다운로드 시도해보시고, 더 좁은 시간 범위를 선택하거나 지원을 위해 앱스플라이어에 문의해보십시오.
  • 날짜 형식이 yyyy-mm-dd를 준수하는지 확인합니다.
  • KPI 유형이 코호트라면, 요청한 KPI가 형식을 준수하는지 확인하십시오.
416 요청된 시간 범위는 UTC로만 있습니다. (시간대 변경 이전)  
403 인증되지 않은 app-ids: <app_ids>  
  • 대시보드에 등록되지 않은 앱과 관련된 데이터를 요청할 때 이 오류가 발생합니다.
  • app_id 파라미터로 전달한 앱 ID가 정확한 앱 ID인지 확인하십시오.
  • 안드로이드의 경우 앱 ID는 패키지 ID 입니다.

    iOS의 경우, 앱 ID는 번들 ID가 아닌, App ID 입니다.

416 인증된 app-id 를 선택하십시오.  
416 No Groupings Selected  
416 잘못된 API 필드:

필드가 존재하지 않거나 허용되지 않습니다.

도움이 되었습니까?