Pull API 집약형 데이터 사용

요약: URL을 사용하여 CSV 파일에서 앱스플라이어 집약형 리포트를 얻습니다.

PullAPIAverage_us-en.png

  Pull API 로데이터를 찾고 계십니까?

Pull API 로데이터

Pull API 종합 데이터 특성

  • 보고서는 CSV 파일로 반환됩니다.
  • 데이터 최신성은 데이터 내보내기 페이지 및 개요 대시보드 페이지에서 동일한 리포트와 같습니다. 비용은 몇 시간 지연으로 업데이트될 수 있으며 비용 데이터를 제공하는 파트너에 따라 비용이 달라질 수 있습니다. 
  • 사용 가능한 옵션별 필터: 미디어소스 및 날짜 범위.
  • Pull API의 추가 기능은 다음과 같습니다.
    • 어트리뷰션 터치 유형으로 필터링 가능
    • 시간대 선택 가능 
  • Pull API는 계정 사용자와 BI 개발자가 사용하기에 적합합니다.
    • 계정 사용자는 URL을 브라우저에 붙여 넣음으로써 리포트를 받을 수 있습니다. URI 템플릿은 대시보드에서 확인할 수 있습니다.  연동 > API 액세스로 이동합니다.
    • BI 개발자 URI를 스크립트에 임베드 함으로써 리포트를 받을 수 있습니다. 

URI 템플릿 예시 TemplateURL_us-en.jpg

카테고리  UA 리타게팅* Protect360
파트너 (미디어 소스)

파트너 - 날짜별

일별

지역

지역별 날짜별 리포트

* 리타겟팅 리포트의 경우, URI에 &reattr=true 를 추가하십시오.

Pull API를 통해 사용 가능한 집약형 성과 리포트

 관련 읽을거리:

용어

용어 설명
Pull API

URI를 사용하여 CSV 리포트를 다운로드 하는 솔루션.

API 호출(call) 또는 호출 

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

URI
  • 리포트 사양을 포함하는 웹 주소(URL)와 유사한 통합 리소스 식별자.
  • URI 템플릿은 대시보드의 API 액세스 메뉴에서 확인할 수 있습니다.

계정 사용자용 안내서

URI 템플릿

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

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 및 파라미터

종합 URI 필수 파라미터 
파라미터 설명
api_token V1.0 API 토큰. 예제 호출에서 이 부분은 <API TOKEN HERE>라고 표시됩니다. 
from
  • 날짜 기간 범위는 from및 to 파라미터로 구성됩니다. 해당 기간은 LTV (인스톨) 기준 날짜 범위입니다.
  • 형식: yyyy-mm-dd, 
  • 예시: 2010-01-01 또는 2010-01-01
활용 종료일. from으로 부터 시작해서 마치는 날.
종합 데이터의 선택적 필터와 표시 파라미터 (프로텍트360 제외)
파라미터 설명
media_source

특정 미디어 소스로 제한 (필터)하는데 사용합니다.

  • 예시: media_source=facebook
attribution_touch_type

이 파라미터를 다음 예시처럼 설정하여 뷰-쓰루 어트리뷰션 (view-through attribution, VTA) KPI를 확인합니다. 

예시: attribution_touch_type=impression

currency

수익과 비용의 통화.

Pull API 종합 리포트는 항상 앱 별 통화를 사용합니다. 

reattr

리타게팅 전환 데이터 얻기.

  • [기본값] 기본 설정인 false인 경우, 유저 유입 (UA) 캠페인 데이터가 반환됩니다.
  • 참인 경우 리타게팅 전환이 반환됩니다.
  • 예시:reattr=true
시간대

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

  • 템플릿 URI는 timezone 파라미터가 앱 별로 설정된 시간대값으로 설정되어 채워집니다. 
  • [기본값] 파라미터가 전송되지 않으면, UTC를 기반으로 데이터가 반환됩니다.
  • 만약timezone=[Joda-Time]으로 보내면, 앱별 시간대를 사용하여 데이터가 반환됩니다.

시간대 선택 관련 참고 사항

  • Joda-Time 시간대 형식은 서머 타임(daylight saving time)을 반영합니다.
  • Joda-Time 값은 앱 설정 페이지의 시간대 값과 동일해야만 합니다. 예를 들어, 앱의 시간대 설정이 Paris라면, Pull API URL의 시간대 값도 timezone=Europe%2fParis 이어야 합니다.
  • 선택한 시간대로 데이터를 가져오는 것은 앱 설정에서 시간대를 설정한 날짜 다음부터만 사용할 수 있습니다. 시간대 설정 변경 이전의 데이터는 UTC 시간대를 사용합니다. 

구글 애즈로 필터한 리포트

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=googleadwords_int

페이스북으로 필터한 리포트

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=facebook
Protect360 보고서 용 선택적 파라미터
파라미터 설명
URI
  • 대시보드에서 Protect360 URI 얻기.
  • URL을 여기에서 설명한 대로 수정합니다. 
pid

리포트를 특정 미디어 소스로 필터하려면, pid 파라미터를 사용하십시오. 예를 들어, abc_net의 데이터를 얻으려면 pid=abc_net 으로 설정합니다.

시간대

데이터를 반환 시, 사용되는 시간대를 선택합니다.

만약 timezone 이 전송되지 않으면, 데이터는 UTC를 기반으로 반환됩니다.

템플릿은 timezone 파라미터를 포함합니다. 

예시: timezone=preferred앱 별로 설정된 시간대를 사용하여 데이터를 가져옵니다.

KPI

 프로텍트360 파라미터는 Pull API 및 마스터 API와 동일합니다. 

뷰-쓰루 어트리뷰션 (VTA) KPI

  • VTA KPI를 가져오려면, 예시에 설명된 대로 파라미터 attribute_touch_type=impression 을 Pull API 종합 리포트 URI에 추가하십시오.
  • 이 파라미터를 제공되는 모든 종합 리포트에 사용할 수 있습니다. 사용자 인터페이스에서 URL을 복사하여 파라미터에 붙이십시오.
  • 또한 &media_source  파라미터를 추가하여, 다음 예시에 설명된 것처럼, 리포트를 특정 미디어 소스로만 필터할 수도 있습니다.
  • 클릭 수, 노출 수 및 비용 API와 같은 일부 VTA KPI에는 해당하는 값이 없고, 대신 N/A 값이 표시됩니다. 
URI 예시
VTA 만 https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression

VTA와 미디어 소스

https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network

개발자를 위한 Pull API

구현 원칙

선행 조건:

계정 사용자를 위한 Pull API 안내서를 숙지하십시오.

고려할 점:

  • 제공되는 각 리포트 유형에 대해 dev hub에 템플릿 URI가 있습니다. 왼쪽 메뉴에서 리포트 유형을 선택합니다.
  • 필요한 데이터를 얻도록 템플릿을 수정합니다. 예를 들어, 날짜 범위를 설정하고 파라미터를 사용해 필터링합니다.
  • 로데이터 및 종합 데이터 리포트의 파라미터는 서로 다릅니다. 리포트 섹션에 상세 설명되어 있습니다.
Pull API 기본 사항
경로

https://hq.appsflyer.com/export/app_id/report_type/v5

경로 파라미터

app_id

  • 앱스플라이어에서 확인되는 앱 식별자입니다.
  • 앱스플라이어에서 찾은대로 정확하게 앱 ID를 입력하십시오.
  • iOS 앱은 접두사 id를 붙입니다.

report_type 

  • 리포트 유형을 정의합니다. 리포트 및 연관된 URI 목록은 대시보드에 있습니다. 좌측 메뉴에서 연동 > API 액세스 로 갑니다.
HTTP 메서드

GET

필수 쿼리 파라미터
파라미터 설명
URI 예시

GET 'https://hq.appsflyer.com/export/app_id/installs_report/v5? from=2020-01-01?&to=2020-01-10&api_token=api_token&currency=preferred

api_token

api_token: 인증을 위한 Pull API 토큰

  • 대시보드에서 API 토큰 확인하기
  • 앱스플라이어 어드민 계정을 변경하면 토큰이 변경됩니다. 반드시 새 토큰으로 스크립트를 업데이트 해야만합니다. 
  • api_token=
다른 파라미터

파라미터는 아래 상황에 따라 달라집니다. 

 

URI 호출 예시에 추가 파라미터가 포함되어 있습니다. 

https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
        api_token={Account owner API key should be used}&from=yyyy-mm-dd
&to=yyyy-mm-dd&additional_fields=keyword_id,store_reinstall,
deeplink_url,oaid,install_app_store,contributor1_match_type,
contributor2_match_type,contributor3_match_type,match_type

스크립트 예시

Pull API를 스크립트에 통합하여 데이터를 가져옵니다.

  • 필요에 따라, 보고서 유형, 날짜 범위 및 필터 측면에서 스크립트를 편집하십시오. 
  • 아래 예시는 인스톨 보고서 기준입니다.
JavaNode JSPythonC#PHP
import okhttp3.*;

import java.io.BufferedWriter;
import java.io.FileWriter;

import java.util.concurrent.TimeUnit;

public class PullApi {
  public static void main(String[] args){

    String appID = "<APP_ID>";
    String reportType = "<REPORT_TYPE>";
    String apiToken = "<API_TOKEN>";
    String from = "<FROM_DATE>";
    String to = "<TO_DATE>";
    String requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;

    OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)

        .build();

    Request request = new Request.Builder()
        .url(requestUrl)
        .addHeader("Accept", "text/csv")
        .build();

    try {
      Response response = client.newCall(request).execute();

      if(response.code() != 200) {
        if(response.code() == 404) {
          System.out.println("There is a problem with the request URL. Please make sure it is correct");
        }
        else {
          assert response.body() != null;
          System.out.println("There was a problem retrieving the data: " + response.body().string());
        }
      } else {
        assert response.body() != null;
        String data = response.body().string();
        BufferedWriter writer;

        writer = new BufferedWriter(new FileWriter(appID + "-" + reportType + "-" + from + "-to-" + to + ".csv"));
        writer.write("");
        writer.write(data);
        writer.close();
      }
      System.exit(0);
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(1);
    }
  }
}

추가 정보

특성과 제한 사항

항목
항목 설명 
필수 API 토큰 유형 AppsFlyerAdmin_us-en.pngV1.0 토큰
광고 네트워크 액세스 N
에이전시 액세스 Y
에이전시 투명성 Y
앱 별 통화 Y
앱 별 시간대 Y
비용 비용 데이터는 UA 캠페인용입니다. 캠페인(인스톨이 없는 캠페인)을 리타게팅하거나 비활성화하기 위한 것이 아닙니다.
데이터 최신성 계속
과거 데이터 Y
논오가닉 데이터 Y
오가닉 데이터 Y
콜 수 제한

제약 사항

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

일러두기! 로데이터에 대한 Pull API는 백만 행을 지원합니다. 집약형 데이터 리포트는 20만 행으로 제한됩니다. 

캠페인 이름 변경 Pull API 리포트는 캠페인 이름 변경 기능을 지원하지 않습니다.

API 오류 코드 및 트러블슈팅

오류 코드 및 해결 방안
상태 메시지 코드 증상/메시지 해결 방안
OK 200 빈 CSV 파일
  • addtional_fields가 두 번 이상 URI에 나타납니다.
  • 시작 날짜와 종료 날짜가 모두 yyyy-mm-dd 형식인지 확인하십시오.
OK

200

 

URL에서 API 토큰을 찾을 수 없습니다.

Bad request

400

원시 리포트의 역사적 룩백은 90일로 제한됩니다.

tofrom을 사용하여, 날짜 범위를 90일 이하로 설정하십시오.

Bad request

400

주어진 보고서 유형에 대해 API 호출 제한에 도달했습니다.

-
Unauthorized

401

Supplied API token is invalid 

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

401

계정이 일시 중단될 수 있습니다.

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

Not found

404

앱스플라이어 404 오류 메시지 페이지가 표시됩니다.

  • 앱 ID가 올바른지 확인하십시오. iOS 앱 이름은 id로 시작해야 합니다.
  • 토큰이 앱과 일치하지 않습니다. 올바른 토큰을 사용하십니까? 
도움이 되었습니까?