요약: URI를 사용하여 CSV 파일의 종합 리포트를 가져옵니다.
풀 API 로데이터를 찾고 계십니까?
풀 API 종합 데이터 특성
- 보고서는 CSV 파일로 반환됩니다.
- 데이터 최신성은 데이터 내려받기 페이지에서의 동일한 리포트와 같습니다.
- 조회 기준 옵션은 데이터 내려받기 페이지와 동일합니다: 미디어 소스, 날짜 기간, 인앱 이벤트 이름.
- 풀 API의 추가 기능은 다음과 같습니다.
- attributed touch type 으로 필터링 가능
- 시간대 선택 가능
- 풀 API는 팀 멤버와 BI 개발자가 사용하기에 적합합니다.
카테고리 | 종합 (성과) UA 및 리타겟팅* | 프로텍트360** |
---|---|---|
파트너 (미디어 소스) | ✓ | ✓ |
파트너 - 날짜별 |
✓ | ✓ |
일별 |
✓ | ✓ |
지역 |
✓ | ✓ |
지역 - 날짜별 |
✓ | ✓ |
* 리타겟팅 리포트의 경우, URI에 |
관련 읽을거리:
용어
용어 | 설명 |
---|---|
Pull API |
URI를 사용하여 CSV 리포트를 다운로드 하는 솔루션. |
API 호출(call) 또는 호출 |
브라우저 주소창에 붙여 넣거나 스크립트를 사용하여 URI를 앱스플라이어에 전송. |
URI |
|
팀멤버를 위한 안내
URI 템플릿
- 대시보드에서 확인되는 URI 템플릿은 앱 ID와 보고서 유형 값이 채워져 있습니다.
- 해당 URI 템플릿은 API 토큰과 기간의 시작과 끝 날짜를 편집할 수 있도록 플레이스홀더를 가지고 있습니다.
- URI에서 물음표 (?) 오른쪽 부분은 파라미터를 포함합니다. 각 파라미터는 앤드 기호 (&)로 시작합니다. 파라미터는 조회 기준을 설정하고, 포함할 추가 필드, 통화 및 시간대를 지정하는데 사용됩니다. 예를 들어, 종합 리포트에서 특정 미디어 소스로 조회 기준을 설정하려면, media_source 파라미터를 사용하십시오:
&media_source=facebook
- 풀 API에 대해 더 살펴보려면, 이어지는 안내 설명을 참고하십시오.
풀 API 리포트 내려받기 설명서
시작하기 전에:- 앱스플라이어 어드민 계정에게 대시보드에서 확인한 풀 API 토큰을 전해달라고 요청하십시오.
대시보드에서 리포트를 다운로드하려면:
-
좌측 메뉴에서 연동 > API 액세스로 갑니다.
API 액세스 페이지가 열립니다. - 리포트 유형을 선택합니다. 예를 들어, 성과 리포트 > 일별 파트너 리포트.
URI 템플릿이 표시됩니다. - URI를 클릭하여 복사합니다.
- 브라우저에서 새 탭을 열어, URI를 붙여 넣습니다.
- URI를 편집합니다:
- 토큰(token, key) 플레이스홀더를 앱스플라이어 어드민 계정에서 확인한 풀 API 토큰으로 바꿉니다.
예시: 다음처럼 되도록 플레이스홀더를 교체합니다.&api_token=12345678-1234-1234-1234-123456789012
주의! 공백이나 구두점이 없습니다. - from/to 플레이스홀더를 날짜로 바꿉니다.
예시:&from=2020-01-20&to=2020-01-31
주의! 공백이 없습니다. & 표시를 삭제하지 마십시오.
- 토큰(token, key) 플레이스홀더를 앱스플라이어 어드민 계정에서 확인한 풀 API 토큰으로 바꿉니다.
- <Enter> 키를 눌러 API 호출을 보냅니다.
리포트가 다운로드됩니다.
종합 데이터 풀 API 파라미터
종합 리포트 URI 및 파라미터
파라미터 | 설명 |
---|---|
api_token | API 인증 토큰. 예제 호출에서 이 부분은 <API TOKEN HERE> 라고 표시됩니다. |
from |
|
활용 |
종료일. from 으로 부터 시작해서 마치는 날.
|
파라미터 | 설명 |
---|---|
media_source |
특정 미디어 소스로 제한 (필터)하는데 사용합니다.
|
attributed_touch_type |
이 파라미터를 다음 예시처럼 설정하여 뷰-쓰루 어트리뷰션 (view-through attribution, VTA) KPI를 확인합니다. 예시: |
currency |
수익과 비용의 통화. 풀 API 종합 리포트는 항상 앱 별 통화를 사용합니다. |
reattr |
리타겟팅 어트리뷰션 데이터를 가져옵니다.
|
시간대 |
[기본값] 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
파라미터 | 설명 |
---|---|
pid |
리포트를 특정 미디어 소스로 필터하려면, |
시간대 |
데이터를 반환 시, 사용되는 시간대를 선택합니다. 만약 timezone 이 전송되지 않으면, 데이터는 UTC를 기반으로 반환됩니다. 템플릿은 timezone 파라미터를 포함합니다. 예시: |
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가 있습니다.
- 필요한 데이터를 얻도록 템플릿을 수정합니다. 예를 들어, 날짜 범위를 설정하고 파라미터를 사용해 필터링합니다.
- 로데이터 및 종합 데이터 리포트의 파라미터는 서로 다릅니다. 리포트 섹션에 상세 설명되어 있습니다.
경로 |
|
경로 파라미터 |
|
HTTP 메소드 |
|
파라미터 | 설명 |
---|---|
URI 예시 |
|
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를 스크립트에 통합하여 데이터를 가져옵니다.
- 필요에 따라, 보고서 유형, 날짜 범위 및 필터 측면에서 스크립트를 편집하십시오.
- 아래 예시는 인스톨 보고서 기준입니다.
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);
}
}
}
request = require('request');
const fs = require('fs');
const appID = '<APP_ID>';
const reportType = '<REPORT_TYPE>';
const apiToken = '<API_TOKEN>';
const from = '<FROM_DATA>';
const to = '<T0_DATE>';
const requestUrl = `https://hq.appsflyer.com/export/${appID}/${reportType}/v5?api_token=${apiToken}&from=${from}&to=${to}`;
request(requestUrl, (error, response, body) => {
if (error) {
console.log('There was a problem retrieving data:', error);
}
else if (response.statusCode != 200) {
if (response.statusCode === 404) {
console.log('There is a problem with the request URL. Make sure that it is correct');
} else {
console.log('There was a problem retrieving data:', response.body);
}
} else {
fs.writeFile(`${appID}-${reportType}-${from}-to-${to}.csv`, response.body, (err) => {
if (err) {
console.log('There was a problem writing to file: ', err);
} else {
console.log('File was saved');
}
});
}
});
import requests
app_id = '<APP_ID>'
report_type = '<REPORT_TYPE>'
params = {
'api_token': '<API_TOKEN>',
'from': 'FROM_DATE',
'to': 'TO_DATE'
}
request_url = 'https://hq.appsflyer.com/export/{}/{}/v5'.format(app_id, report_type)
res = requests.request('GET', request_url, params=params)
if res.status_code != 200:
if res.status_code == 404:
print('There is a problem with the request URL. Make sure that it is correct')
else:
print('There was a problem retrieving data: ', res.text)
else:
f = open('{}-{}-{}-to-{}.csv'.format(app_id, report_type, params['from'], params['to']), 'w', newline='', encoding="utf-8")
f.write(res.text)
f.close()
using System;
using RestSharp;
using System.Text;
using System.Net;
using System.IO;
namespace Pull_API
{
class PullAPi
{
static void Main(string[] args)
{
var appID = "<APP_ID>";
var reportType = "<REPORT_TYPE>";
var apiToken = "<API_TOKEN>";
var from = "<FROM_DATE>";
var to = "<TO_DATE>";
var requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;
var client = new RestClient(requestUrl);
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/csv; charset=UTF-8");
IRestResponse response = client.Execute(request);
HttpStatusCode statusCode = response.StatusCode;
int numericStatusCode = (int)statusCode;
if(numericStatusCode != 200){
if(numericStatusCode == 404){
Console.WriteLine("There is a problem with the request URL. Make sure that it is correct.");
} else {
Console.WriteLine("There was a problem retrieving data: " + response.Content);
}
} else {
System.IO.File.WriteAllText(@"" + appID + "-" + reportType + "-" + from + "-to-" + to + ".csv", response.Content);
Console.WriteLine("Data retrieved succesfully");
}
}
}
}
<?
$appID = '<APP_ID>';
$reportType = '<REPORT_TYPE>';
$apiToken = '<API_TOKEN>';
$from = '<FROM_DATE>';
$to = '<TO_DATE>';
$query = http_build_query([
'api_token' => $apiToken,
'from' => $from,
'to' => $to
]);
$requestUrl = 'https://hq.appsflyer.com/export/' . $appID . '/' . $reportType . '/v5?'.$query;
$report = $appID . '-' . $report . '-' . $from . '-to-' . $to;
$curl = curl_init($requestUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_ENCODING, "");
curl_setopt($curl, CURLOPT_NOSIGNAL, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_FAILONERROR, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 100);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
"cache-control: no-cache",
"Accept: text/csv; charset=UTF-8"
));
$response = curl_exec($curl);
$info = curl_getinfo($curl);
$err = curl_error($curl);
curl_close($curl);
var_dump($response);
if ($err) {
echo $info['http_code'];
echo "cURL Error #: " . $err . '. ';
if ($info['http_code'] == 404) {
echo 'There is a problem with the request URL. Make sure that it is correct';
}
if ($info['http_code'] == 401) {
echo 'There was a problem retrieving data: authentication failed.';
}
echo PHP_EOL;
} else {
$fp = fopen($report, 'w+');
fwrite($fp, $response);
fclose($fp);
echo $response;
}
?>
추가 정보
풀 API V4와 V5의 차이점
로데이터: API V4를 여전히 사용할 수 있습니다. 파일 형식과 헤더가 변경되지 않았습니다.
종합 데이터 (V5):
V5.0에서는 media_source=facebook 인 경우, 다음과 같은 추가 필드가 제공됩니다.
- 캠페인 ID
- Adset name
- 광고세트 ID
- Ad (Adgroup) Name
- Ad (Adgroup) Id
특성과 제한 사항
항목 | 상태 메시지 | 설명 |
---|---|---|
애드 네트워크 액세스 | ✓ | |
에이전시 액세스 | ✓ | |
에이전시 투명성 | ✓ | |
앱 별 통화 | ✓ | |
앱 별 시간대 | ✓ | |
데이터 최신성 | 실시간 | |
과거 데이터 | ✓ | |
논오가닉 데이터 | ✓ | |
오가닉 데이터 | ✓ | |
콜 수 제한 | ✓ | |
사이즈 제한 | 예 |
|
팀 멤버의 접근 권한 | ✓ |
오직 앱스플라이어 어드민 계정만 풀 API 토큰을 확인할 수 있습니다. |
API 오류 코드 및 트러블슈팅
상태 메시지 | 코드 | 증상/메시지 | 해결 방안 |
---|---|---|---|
OK | 200 | 빈 CSV 파일 |
|
OK |
200 |
빈 CSV 파일 |
시작 날짜와 종료 날짜가 모두 yyyy-mm-dd 형식인지 확인하십시오. |
Bad request |
400 |
Raw Reports historical lookback is limited to 90 days. |
|
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 |
|
토큰이 앱과 일치하지 않습니다. 앱스플라이어 어드민 계정에게 현재 토큰을 요청하십시오. |