Pull API 로데이터 사용하기

프리미엄
권장 대상
마케터 마케터
마지막 업데이트:

요약: URI를 사용하여 로데이터 리포트를 CSV 파일로 가져옵니다.

PullAPIRaw_us-en.png

Pull API 로데이터 특성

  • 로데이터 리포트 내용 설명.
  • 보고서는 CSV 파일로 반환됩니다.
  • 필터 기준 옵션은 미디어소스, 날짜 범위, 인앱이벤트 이름 및 지역입니다. 
  • 시간대 및 통화는 선택 가능합니다.
  • Pull API는 계정 사용자와 BI 개발자에게 적합합니다.
  • 속도 제한: 할당량 메커니즘은 하루에 생성할 수 있는 리포트의 수를 제한합니다. 

 관련 자료: 올바른 데이터 전달 도구/리포팅 API 선택하기

용어

용어 설명
Pull API 

URI를 사용하여 CSV 리포트를 다운로드 하는 솔루션.
API 호출(call) 또는 호출 

브라우저 주소창에 붙여 넣거나 스크립트를 사용하여 URI를 앱스플라이어에 전송.

URI
  • 인터넷 식별자(Uniform Resource Identifier)는 때때로, 리포트 사양을 포함한 웹페이지 주소(URL)와 유사합니다.
  • URI 템플릿은 대시보드의 API 액세스 메뉴에서 확인할 수 있습니다.

계정 사용자용 안내서

URI 템플릿

  • dev hub에서 확인되는 URI 템플릿은 앱 ID와 보고서 유형 값이 채워져 있습니다.
  • API V1.0 토큰과 기간의 시작과 끝 날짜를 편집해야 하는 플레이스홀더를 가지고 있습니다.
  • URI에서 물음표(?) 오른쪽 부분은 파라미터를 포함합니다. 각 파라미터는 앰퍼샌드 기호(&)로 시작합니다. 파라미터는 조회 기준을 설정하고, 포함할 추가 필드, 통화 및 시간대를 지정하는 데 사용됩니다. 예를 들어, 로데이터 리포트에서 특정 미디어소스로 (조회 기준을) 제한하려면, media_source 파라미터를 사용하십시오. &media_source=facebook
  • Pull API에 대해 더 살펴보려면, 이어지는 안내 설명을 참고하십시오.
  • 포스트백 URI는 대시보드에서 사용할 수 없습니다. 스프레드 시트의 포스트백 URI를 사용합니다.

Pull API 리포트 내려받기 설명서

개발 허브를 사용하면 사용자 지정 데이터를 쉽게 입력하고 리포트를 다운로드하여 테스트할 수 있습니다.

시작하기 전에:

개발 허브에서 리포트를 다운로드하려면: 

  1. 앱스플라이어 개발 허브 API 참조로 이동합니다.

    API_Reference.jpg

  2. 왼쪽 메뉴에서 리포트 유형을 선택합니다.
    예를 들어 로데이터 리포트(논오가닉) > 인스톨.
     모든 리포트 유형 목록은 아래 표를 참조하십시오.

  3. 모든 필수 필드를 작성하십시오 
  4. URI 템플릿이 오른쪽에 표시됩니다. 
  5. 복사 아이콘을 클릭하여 URI를 복사합니다.
  6. 브라우저에서 새 탭을 열고 URI를 붙여 넣습니다.
  7. <Enter> 키를 눌러 API 호출을 보냅니다. 
    리포트가 다운로드됩니다.
리포트 설명 업데이트 빈도
로데이터 리포트 (논오가닉)
인스톨 논오가닉 인스톨을 기록합니다. 사용자가 앱을 처음 열 때 레코드가 생성됩니다.
 실시간
인앱 이벤트 사용자가 수행한 이벤트를 기록합니다.
 실시간
앱 삭제 사용자가 앱을 삭제할 때 기록합니다.
 일별
리인스톨
 앱을 삭제한 후 UA 미디어 소스에 참여하고 리어트리뷰션 기간 동안 앱을 다시 인스한 사용자를 기록합니다. 실시간
로데이터 리포트(오가닉)
오가닉 인스톨
 사용자가 앱을 처음 열었을 때를 기록합니다.
 계속
오가닉 인앱 이벤트
 사용자가 수행한 이벤트에 대한 세부 정보를 기록합니다.
 계속
오가닉 앱 삭제
 앱을 삭제하는 사용자를 기록합니다.
 일별
오가닉 앱 리인스톨
 리인게이지먼트 기간 동안 리타게팅 미디어 소스로 인한 사용자의 광고 수익을 기록합니다.
 일별
광고 수익 로데이터
어트리뷰션된 광고 수익
 		미디어 소스로 어트리뷰트한 사용자의 광고 수익을 기록합니다. 일별
오가닉 광고 수익 미디어 소스에 어트리뷰트되지 않은 사용자의 광고 수익을 기록합니다. 일별
프로텍트360 프로드(fraud)
인스톨 사기로 식별되어 미디어 소스에 어트리뷰트되지 않은 인스톨을 기록합니다. 실시간
포스트 어트리뷰션 인스톨 사기 설치로 한 인해 전허 어트리뷰트되지 않은 인앱이벤트를 기록합니다. 실시간
인앱 이벤트 Protect360에서 사기로 식별된 인앱이벤트를 기록합니다. 일별
포스트 어트리뷰션 인앱 이벤트 인스톨 자체와 상관없이 미디어 소스에 어트리뷰트되거나 사기로 판단된 후 사기로 식별된 인스톨에 대한 인앱이벤트를 기록합니다. 일별
클릭 Protect360에 의해 차단된 사용자가 수행한 클릭을 기록합니다. 일별
차단된 인스톨 포스트백 인스톨이 차단된 미디어 소스로 전송된 포스트백 사본을 기록합니다. 실시간
포스트백
인스톨 포스트백 사용자가 앱을 처음 열 때 생성된 인스톨 이벤트를 기록합니다. 일별
인앱 이벤트 포스트백 미디어 소스로 전송된 인앱이벤트 포스트백을 기록합니다. 일별
리타게팅 인앱이벤트 포스트백 리인게이지먼트 기간 동안 사용자가 수행한 인앱이벤트를 기록합니다. 실시간
리타게팅 전환 포스트백 리인게이지먼트 기간 동안 사용자가 수행한 인앱이벤트를 기록합니다. 실시간

로데이터 Pull API 파라미터

URI 파라미터 로데이터

파라미터 설명
api_token API 인증 토큰. 예제 호출에서 이 부분은 <API TOKEN HERE>라고 표시됩니다. 
from
  • 날짜 범위는 시작및 마감 파라미터를 포함합니다. 날짜는 액티비티 날짜와 관련됩니다.
  • 형식: yyyy-mm-dd, yyyy-mm-dd hh:mm, 또는 yyyy-mm-dd hh:mm:ss 일러두기!:  여기에 보여준 것처럼 공백은 인코딩되어야 합니다. from=2020-04-01%2001:00:00 - 일반적으로 브라우저는 공간을 인코딩합니다. 
  • 예: 2010-01-01 또는 2010-01-01 20:15(시간 및 분 파라미터는 로데이터 리포트에서 사용 가능). 
활용 종료일. from으로 부터 시작해서 마치는 날.
로데이터 선택적 파라미터
파라미터 설명

media_source

media_source: 특정 미디어소스로 통화를 제한(필터링)하려면 다음과 같이 하십시오. media_source 및 category 파라미터 모두를 다음과 같이 설정합니다.

  • Facebook인 경우 category 및 media_source를 facebook으로 설정합니다.
  • Twitter인 경우 category 및 media_source를 twitter로 설정합니다.
  • 기타 모든 미디어소스에 대해서는 category를 표준으로, media_source를 미디어소스의 이름으로 설정합니다.
  • 예시
    • media_source=facebook&category=facebook
    • media_source=abc_example&category=standard
maximum_rows

단일 API 호출에 의해 반환된 최대 행 수입니다.

  • [기본값] 전송된 값이 없으면 최대 20만 행
  • 200000: 최대 20만 행 반환
  • 1000000: 최대 1백만 행 반환
  • 예: maximum_rows=1000000이면 최대 1백만 행을 허용합니다. 
event_name

인앱이벤트를 지정된 이벤트별로 필터합니다. 쉼표로 구분된 목록을 사용하여 다중 이벤트를 선택합니다.

예: event_name=af_purchase,ftd 
reattr

리타게팅 어트리뷰션 데이터를 설정합니다.

  • [기본값] 기본 설정인 false인 경우, 유저 유입 (UA) 캠페인 데이터가 반환됩니다.
  • 만약 파라미터가 true로 설정되었다면, 리타겟팅 어트리뷰션 데이터가 반환됩니다.
  • 예시:reattr=true
additional_fields

기본 필드 외에 추가 필드를 가져오기 위한 것입니다. 

예: additional_fields=device_donwload_time,deeplink_url
currency

수익 및 비용의 통화

  • [기본값] 파라미터가 전송되지 않으면, USD를 기반으로 데이터가 반환됩니다. 다시 말하면 아무것도 하지 않으면 결과는 USD로 반환됩니다.
  • 만약 currency=preferred 를  전송하면 앱 고유 통화가 사용됩니다.  즉 앱 설정에서 설정한 통화입니다.

예: 앱 고유 통화가 EUR이면  currency=preferred를 전송함으로써 EUR 값이 반환됩니다.
시간대

[기본값] UTC를 사용하여 데이터가 반환됩니다.

  •  앱 고유 시간대를 가져오고  이 섹션에서 표시된 시간대를 추가하여 통화하는 방법: 
  •  timezone=[숫자 값] 
  • 예시: 시간대 UTC+10:00인 경우timezone=+10:00을 사용합니다. 일러두기!:  +,- 및 : 는 인코딩해야 합니다. 예: +10:00는 %2B10%3A00으로 인코딩됩니다.
지역

데이터를 국가 코드로 필터링합니다.

제한: API 호출당 하나의 국가 코드 필터만 선택할 수 있습니다. 

예: geo=ZA

프로텍트360

Protect360 로데이터 안내서 참조

날짜 및 시간별 시간 범위

결과가 최대값을 초과할 경우 시간과 분을 사용하여 리포트를 분할합니다. 다음을 적용합니다.

  • 시작/마감: yyyy-mm-dd hh:mm 
  • 시작: 
    • 날짜만 = 선택한 날짜의 시작(00:00)부터
    • 날짜 및 시간 = 00:00을 포함하여 시작
  • 파라미터 마감: 
    • 날짜만 = 선택한 요일의 마지막(24:00)까지
    • 날짜 및 시간 = 표시된 시간까지, 그러나 이 시간을 포함하지 않음

예: 앱 소유자는 모든 소스에서 매일 1300K를 설치합니다. 1M 행 제한을 극복하기 위해 앱 소유자는 하루를 두 개의 12시간 URI 호출로 나눕니다. 옵션에 대해서는 다음 표를 참조하십시오. 

API 호출 시작  마감 
첫 번째 API 호출 

시작=yyyy-mm-dd

예:

  • 시작=2019-12-29
  • 이 날짜에 시작시간 00:00으로 시작

마감=yyyy-mm-dd 12:00

예:

  • 마감=2019-12-29 12:00
  • 12:00이 아니라 11:59:50까지 계속됨 

옵션 A: 두 번째 API 호출 

 

예: 

&from=2019-12-29 12:00&to=2019-12-29

  • 2019년 12월 29일 정오에 시작
  • 2019년 12월 29일 자정에 마감
  

시작 시간=yyyy-mm-dd 12:00

예:

  • 시작=2019-12-29 12:00
  • 12:00에서 시작하며 이 시간 포함

 

to=yyyy-mm-dd

예:

  • 마감=2019-12-29
  • 자정에 종료

 
옵션 B: 두 번째 API 호출

시작 시간=yyyy-mm-dd 12:00

예:

  • 시작=2019-12-29 12:00
  • 12:00에서 시작하며 이 시간 포함

마감=yyyy-mm-dd+1 00:00

+1 = 익일 00:00

예:

  • 마감=2019-12-30 00:00
  • 12월 30일에 시간이 경과하기 전을 의미합니다.

일러두기! 두 개의 결과가 같으므로 옵션 A 또는 B를 사용합니다. 

추가 필드

리포트 필드는 새 필드가 가져오기 및 수집 프로세스에 영향을 미치지 않도록 기본 필드 목록에 추가되지 않습니다. 기본이 아닌 필드를 가져오려면 additional_field 파라미터를 사용하십시오.

  • 필드는 한 번만 기재합니다.
  • 사용 가능한 필드 목록을 참조하십시오.
  • 일부 URI 예에는 추가 필드가 포함되어 있습니다. 필요한 경우 필드를 더 추가하십시오. 
  • Example: additional_fields=device_download_time,deeplink_url
  • 항상 아래 표에 기재된 필드에 대한 결과가 반환됩니다.

 예시

추가 필드를 가진 URI 호출 예:

https://hq1.appsflyer.com/api/raw-data/export/app/<APP ID HERE>/installs_report/v5?
        api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
        &additional_fields=device_download_time,deeplink_url

기본 Pull API 필드

기본 Pull API 필드
Attributed Touch Time
Install Time
Event Time
Event Name
이벤트 값
Event Revenue
Event Revenue Currency
Event Revenue USD
Event Source
Is Receipt Validated
파트너
Media Source (미디어 소스)
채널
키워드
캠페인
캠페인 ID
광고세트
광고세트 ID
Ad
광고 아이디
광고 타입
사이트 ID
하위 사이트 ID
Sub Param 1
Sub Param 2
Sub Param 3
Sub Param 4
Sub Param 5
비용 모델
비용 값
비용 통화
Contributor 1 Partner
Contributor 1 Media Source
Contributor 1 Campaign
Contributor 1 Touch Type
Contributor 1 Touch Time
Contributor 2 Partner
Contributor 2 Media Source
Contributor 2 Campaign
Contributor 2 Touch Type
Contributor 2 Touch Time
Contributor 3 Partner
Contributor 3 Media Source
Contributor 3 Campaign
Contributor 3 Touch Type
Contributor 3 Touch Time
Region
Country Code
state
City
Postal Code
dma
IP
wifi
operator
통신사
language
AppsFlyer ID
Advertising ID
IDFA
안드로이드 ID
Customer User ID
IMEI
IDFV
플랫폼
Device Type
OS Version
App Version
SDK Version
앱 ID
App Name
번들 ID
Is Retargeting
Retargeting Conversion Type
Attribution Lookback
Reengagement Window
Is Primary Attribution
User Agent
HTTP Referrer
Original URL

개발자를 위한 Pull API

스크립트를 사용한 Pull API 로데이터를 구현하려면 Pull API 집약형 데이터 기사를 읽어보십시오. 

추가 정보

API V4를 V5로 마이그레이션

로데이터: 2021년 12월 1일부터 V4 API는  소멸되어 플랫폼에서 삭제됩니다. 이날 이전에 V4 사용을 중지하고 V5로 마이그레이션해야 합니다. 

API V4를 V5로 마이그레이션하기

V4에서 V5로 마이그레이션할 때 V5에는 항상 반환되는 기본 필드 집합과 Pull API 호출에 명시적으로 추가해야 하는 선택적 추가 필드가 있다는 것을 고려하십시오. 필요한 필드를 가져오려면 API 호출을 조정하십시오. 앱스플라이어는 사용자 인터페이스의 일부 추가 필드로 구성된 템플릿을 제공합니다. 필요에 따라 템플릿을 편집해야 합니다. 사용자 인터페이스에서 API 템플릿 가져오기를 참조하십시오.

특성과 제한 사항

항목
항목 설명 
필수 API 토큰 유형 AppsFlyerAdmin_us-en.pngV2.0 토큰
광고 네트워크 액세스 아니오
에이전시 액세스 예
에이전시 투명성 예
앱 별 통화 예
앱 별 시간대 예
데이터 최신성
  • 개요 대시보드에 있는 데이터의 가용성과 동등합니다.
  • 몇 시간 지연을 가지고 업데이트된 리포트:
    • 오가닉 인앱 이벤트
  • 매일 업데이트된 리포트:
    • 앱 삭제
    • 포스트 어트리뷰션 인앱 이벤트
    • 광고 수익
과거 데이터 네.  리텐션 및 속도 제한 정책에 따릅니다. 
논오가닉 데이터 예
오가닉 데이터 예
콜 수 제한

로데이터에 대한 API 제한. 
사이즈 제한
  • API 호출은 최대 20만/1백만 행을 반환합니다.
  • 리포트에 정확히 20만/1백만 개의 행이 있는 경우, 초과되어 누락된 행이 있다고 가정하십시오.
  • 최대 행 수를 선택하려면 maximum_rows 파라미터를 사용하십시오.
  • 시간을 포함한 from/to 파라미터를 사용하여 API 호출을 여러번 발송하십시오.

API 오류 코드 및 트러블슈팅

오류 코드, 증상 및 솔루션
상태 메시지 코드 증상/메시지 해결 방안
    리포트에 선택한 시간 범위에 따라 예상된 데이터가 포함되어 있지 않거나 로데이터 리포트와 집약형 데이터 리포트 간에 불일치가 있습니다. 

timezone 파라미터를 설정했는지 확인하십시오. 설정하지 않으면 앱 표준시가 아닌 UTC를 사용하여 데이터가 전송됩니다. 
OK 200 빈 CSV 파일

addtional_fields가 두 번 이상 URI에 나타납니다.
OK

200

빈 CSV 파일

시작 날짜와 종료 날짜가 모두 yyyy-mm-dd 형식인지 확인하십시오.
Bad request

400

Raw Reports historical lookback is limited to 90 days.

to와 from을 사용하여, 날짜 범위를 90일 이하로 설정하십시오.
Bad request

400

Your API calls limit has been reached for report type

 -
Bad request 400

잘못된 제한 유형

 report_rows는 값 200000 또는 1000000을 가질 수 있습니다.
Unauthorized

401

Supplied API token is invalid 

 앱스플라이어 어드민 계정에게 현재 토큰을 요청하십시오.
Unauthorized

401

Account may be suspended.

대시보드에 로그인하여 계정 상태를 확인하십시오. 
Not found

404

 

토큰이 앱과 일치하지 않습니다. 앱스플라이어 어드민 계정에게 현재 토큰을 요청하십시오.