풀(Pull) API 종합 데이터

요약: URI를 사용하여 CSV 파일의 종합 리포트를 가져옵니다.

PullAPIAverage_us-en.png

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

풀 API 로데이터

풀 API 종합 데이터 특성

  • 보고서는 CSV 파일로 반환됩니다.
  • 데이터 최신성은 데이터 내려받기 페이지에서의 동일한 리포트와 같습니다.
  • 조회 기준 옵션은 데이터 내려받기 페이지와 동일합니다: 미디어 소스, 날짜 기간, 인앱 이벤트 이름. 
  • 풀 API의 추가 기능은 다음과 같습니다.
    • attributed touch type 으로 필터링 가능
    • 시간대 선택 가능 
  • 풀 API는 팀 멤버와 BI 개발자가 사용하기에 적합합니다.
    • 팀 멤버 URI를 브라우저에 붙여 넣음으로써 리포트를 받을 수 있습니다. URI 템플릿은 대시보드에서 확인할 수 있습니다. 
    • BI 개발자 URI를 스크립트에 임베드 함으로써 리포트를 받을 수 있습니다. 

URI 템플릿 예시 TemplateURL_us-en.jpg

카테고리 종합 (성과) UA 및 리타겟팅* 프로텍트360**
파트너 (미디어 소스)

파트너 - 날짜별

일별

지역

지역 - 날짜별

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

종합 리포트, LTV 기반

 관련 읽을거리:

용어

용어 설명
Pull API

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

API 호출(call) 또는 호출 

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

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

팀멤버를 위한 안내

URI 템플릿

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

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

시작하기 전에:
  • 앱스플라이어 어드민 계정에게 대시보드에서 확인한 풀 API 토큰을 전해달라고 요청하십시오.

대시보드에서 리포트를 다운로드하려면: 

  1. 좌측 메뉴에서 연동 > API 액세스로 갑니다.
    API 액세스 페이지가 열립니다. PullAPIPartnersReport_us-en.jpg
  2. 리포트 유형을 선택합니다. 예를 들어, 성과 리포트일별 파트너 리포트. 
    URI 템플릿이 표시됩니다. 
  3. URI를 클릭하여 복사합니다.
  4. 브라우저에서 새 탭을 열어, URI를 붙여 넣습니다.
  5. URI를 편집합니다:
    1. 토큰(token, key) 플레이스홀더를 앱스플라이어 어드민 계정에서 확인한 풀 API 토큰으로 바꿉니다.
      예시: 다음처럼 되도록 플레이스홀더를 교체합니다. &api_token=12345678-1234-1234-1234-123456789012 주의! 공백이나 구두점이 없습니다. 
    2. from/to 플레이스홀더를 날짜로 바꿉니다.
      예시: &from=2020-01-20&to=2020-01-31 주의! 공백이 없습니다. & 표시를 삭제하지 마십시오. 
  6. <Enter> 키를 눌러 API 호출을 보냅니다. 
    리포트가 다운로드됩니다.

종합 데이터 풀 API 파라미터

종합 리포트 URI 및 파라미터

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

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

  • 예시: media_source=facebook
attributed_touch_type

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

예시: attribution_touch_type=impression

currency

수익과 비용의 통화.

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

reattr

리타겟팅 어트리뷰션 데이터를 가져옵니다.

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

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

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

시간대 선택 관련 참고 사항

  • Joda-Time 시간대 형식은 서머 타임(daylight saving time)을 반영합니다.
  • Joda-Time 값은 앱 설정 페이지의 시간대 값과 동일해야만 합니다. 예를 들어, 앱의 시간대 설정이 Paris라면, 풀 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 보고서 용 선택적 파라미터
파라미터 설명
 pid

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

시간대

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

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

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

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

KPI

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

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

  • VTA KPI를 가져오려면, 예시에 설명된 대로 파라미터 attribute_touch_type=impression 을 풀 API 종합 리포트 URI에 추가하십시오.
  • 이 파라미터를 제공되는 모든 종합 리포트에 사용할 수 있습니다. 대시보드에서 URI를 복사하고, &attributed_touch_type=impression 를 부착하십시오.
  • 또한 &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&aattribution_touch_type=impression&media_source=example_ad_network

개발자를 위한 풀 API

구현 원칙

선행 조건:

팀멤버를 위한 풀 API 안내 항목을 익힙니다.

고려할 점:

  • 제공되는 각 보고서 유형에 대해 대시보드에 템플릿 URI가 있습니다.
  • 필요한 데이터를 얻도록 템플릿을 수정합니다. 예를 들어, 날짜 범위를 설정하고 파라미터를 사용해 필터링합니다.
  • 로데이터 및 종합 데이터 리포트의 파라미터는 서로 다릅니다. 리포트 섹션에 상세 설명되어 있습니다.
풀 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: 인증을 위한 풀 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

스크립트 예시

풀 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 V4와 V5의 차이점 

로데이터: API V4를 여전히 사용할 수 있습니다. 파일 형식과 헤더가 변경되지 않았습니다.

종합 데이터 (V5):

V5.0에서는 media_source=facebook 인 경우, 다음과 같은 추가 필드가 제공됩니다.

  • 캠페인 ID
  • Adset name
  • 광고세트 ID
  • Ad (Adgroup) Name
  • Ad (Adgroup) Id

특성과 제한 사항

항목
항목 상태 메시지 설명 
애드 네트워크 액세스  
에이전시 액세스  
에이전시 투명성  
앱 별 통화  
앱 별 시간대  
데이터 최신성 실시간  
과거 데이터  
논오가닉 데이터  
오가닉 데이터  
콜 수 제한

종합 데이터 및 로데이터 API 제한 사항. 

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

오직 앱스플라이어 어드민 계정만 풀 API 토큰을 확인할 수 있습니다.

API 오류 코드 및 트러블슈팅

오류 코드 및 해결 방안
상태 메시지 코드 증상/메시지 해결 방안
OK 200 빈 CSV 파일

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

OK

200

빈 CSV 파일

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

Bad request

400

Raw Reports historical lookback is limited to 90 days.

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

Bad request

400

Your API calls limit has been reached for report type

-
Unauthorized

401

Supplied API token is invalid 

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

401

Account may be suspended.

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

Not found

404

 

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

도움이 되었습니까?