使用Pull API拉取汇总数据

概要:本文重点讲解了如何使用URI来拉取CSV格式的AppsFlyer汇总报告。

PullAPIAverage_us-en.png

 相关参考——Pull API原始数据

Pull API 原始数据报告

Pull API汇总数据特点

  • 返回的报告是CSV格式的。
  • 数据更新频率:与Export Data(导出数据)页面的报告一致。
  • 可用的筛选条件:媒体渠道和日期范围
  • Pull API的其他功能包括:
    • 可以按归因触点类型筛选结果
    • 提供不同的时区选项
  • Pull API适用于账户用户以及BI开发人员。
    • 账户用户将URI复制粘贴到浏览器中,就能获取报告。请从后台进入对接 > API数据接口,查看URI模板。
    • BI开发人员在脚本中嵌入URI后就能拉取报告。

URI模板示例TemplateURL_us-en.jpg

类别  UA(用户获取) 再营销* Protect360
分渠道报告

分渠道每日报告

每日报告

分国家/地区报告

分国家/地区每日报告

*如要拉取再营销报告,请在URI中添加&reattr=true这个参数。

可通过Pull API拉取的汇总效果报告

 扩展阅读:

概念定义

术语 描述
Pull API

通过URI下载CSV报告的解决方案。

调用/API调用

将URI复制粘贴到浏览器地址栏或通过脚本向AppsFlyer发送URI。

URI
  • Uniform resource identifier(统一资源标识符)类似于网页地址(URL),其中包含报告规格。
  • 请在面板的API页面中查看URI模板。

使用指南

URI模板简介

  • 面板中的URI模板中带有应用ID和报告类型参数。
  • 模板中留出了API V1.0令牌以及日期范围的位置,这两个字段是需要您编辑的。
  • URI中问号(?)右侧的部分是各种参数,每个参数都以&开始。您可以使用这些参数来设置筛选条件、添加特定的字段(如货币币种和时区),比如您可以通过media_source(媒体渠道)参数在汇总报告中筛选某一个媒体渠道的结果,如&media_source=facebook
  • 请完成以下入门教程,更熟练地掌握Pull API这个工具。

请完成以下Pull API报告入门流程:

前期准备:

从面板下载报告:

  1. 从后台进入对接 > API数据接口。
    打开API数据接口页面。
  2. 选择报告类型。如效果报告 > 分渠道每日报告
    界面会显示URI模板。
  3. 点击复制该URI。
  4. 在浏览器中打开一个新的标签页,然后将URI粘贴到地址栏中。
  5. 编辑URI:
    1. 在预留位置中填入由管理员提供的Pull API令牌。
      示例:在预留位置中填入令牌后相关字段应该是这样的&api_token=12345678-1234-1234-1234-123456789012 请注意:这里面不能有空格或其他的标点符号。
    2. from/to的日期范围预留位置中填入日期。
      示例:&from=2020-01-20&to=2020-01-31 请注意:不能带有空格,且不能删除&号。
  6. 按下回车键,发送API调用。
    开始下载报告。您可以使用其他参数来设置自定义报告,如查看某一个渠道的再营销数据等。下一个章节中列出了所有的可用参数。

汇总数据Pull API的参数

汇总报告URI和参数

汇总URI中必须配置的参数
参数 描述
api_token V1.0 API令牌,在调用示例中显示为:<API TOKEN HERE>。
from
  • 日期范围包含一个fromto参数,该范围是LTV维度的(即激活日期)。
  • 格式:yyyy-mm-dd
  • 如:2010-01-01
to 结束日期,与from相对
汇总数据中除Protect360报告之外的其他筛选条件和显示参数
参数 描述
media_source

用于按具体的媒体渠道筛选结果。

  • 示例:media_source=facebook
attribution_touch_type

请根据示例来设置该参数,从而拉取浏览型归因(VTA)指标。

示例:attribution_touch_type=impression

currency

收入和成本的货币币种。

汇总Pull API报告按应用层级的指定货币显示相关值。

reattr

用于拉取再营销转化数据。

  • 【默认】如果该参数为false,就会拉取到用户获取(UA)的投放数据。
  • 如果该参数的值为true,就会拉取到再营销转化数据。
  • 示例reattr=true
timezone

【默认】数据以UTC时间显示。

  • URI模板中的时区参数以应用层级的指定时区填充。
  • 【默认】如果不发送该参数,报告会按UTC时间显示数据。
  • 如果您发送timezone=[Joda-Time],那么报告会以应用层级指定的时区来显示。

选择时区时的注意事项

  • Joda-Time时区格式会自动根据夏令时进行调整。
  • Joda-Time的值必须与应用设置页面的值完全一致。比如,如果时区设为巴黎,那么Pull API URI中的时区值必须是timezone=Europe%2fParis
  • 时区设置完成后产生的数据会根据指定时区来显示,但在设置时区前产生的数据仍以UTC时间显示。

在报告中仅查看Google Ads的数据

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

在报告中仅查看Facebook的数据

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。
  • 请根据此处的说明来修改URI。
PID

您可以使用pid参数来筛选某个媒体渠道的数据。假设您仅需要拉取abc_net的数据,就使用pid=abc_net

timezone

选择您所使用的时区来显示数据。

如果不发送timezone参数,那么报告会以UTC时间来显示数据。

URI模板中包含了timezone参数。

示例:timezone=preferred表示在报告中根据应用层级的指定时区来显示数据。

KPI关键绩效指标

Protect360参数在Pull API和Master API中是一样的。

浏览型归因(VTA)的KPI

  • 请在Pull API汇总报告URI中添加参数attribution_touch_type=impression,来拉取VTA指标。具体请见下表示例。
  • 该参数可用于任何汇总报告。只需从面板中复制URI,然后在其中加入该参数即可。
  • 您可以通过添加&media_source参数来拉取某个渠道的报告,具体请见下表示例。
  • 点击、展示、成本等部分VTA指标没有对应的值,因此在报告中显示为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

其中需要注意以下几点

  • 您可以在面板中找到每一种报告类型的URI模板,只需从后台进入对接 > API数据接口即可查看。
  • 您可以通过修改模板来调整拉取到的数据,比如设定日期范围并根据参数筛选结果。
  • 原始数据报告和汇总数据报告的参数有所不同,具体请见报告部分。
Pull API基础知识
路径

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

路径参数

app_id

  • 即AppsFlyer后台显示的应用标识符。
  • 请将此应用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令牌

其他参数

各类报告的可用参数有所不同,具体请参见以下文档:

 示例

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时间范围中指定某一天的具体时间。

请注意:Pull API的原始数据报告最多可包含100万行数据,汇总数据报告最多可包含20万行数据。

广告系列名称变更 Pull API报告不支持广告系列名称变更

API错误代码及疑难解答

错误代码及解决方案
状态 代码 问题表现/报错 解决方案
OK 200 CSV文件为空
  • URI中addtional_fields出现了一次以上
  • 请确保“from”和“to”的日期都是yyyy-mm-dd格式
OK

200

 

URI中没有API令牌

Bad request
(请求无效)

400

Raw Reports historical lookback is limited to 90 days
(不能查看超过90天以前的原始数据报告)

tofrom的时间范围调整到3个月以下

Bad request
(请求无效)

400

Your API calls limit has been reached for the given report type
(您的API调用频次已达到所选报告类型的上限)

-
Unauthorized
(无权限)

401

Supplied API token is invalid 
(您提供的API令牌无效)

向管理员申请现行令牌。
Unauthorized
(无权限)

401

Account may be suspended
(账户可能已关停)

请登入面板并查看账户状态。

Not found
(不存在)

404

弹出AppsFlyer404报错页面

  • 请确保应用ID正确无误。iOS应用的ID必须以id为前缀。
  • 令牌与应用不匹配,请确保您所使用的令牌正确无误。
这篇文章有帮助吗?