TUNE Aggregate Exports & API

概述

📘

仅适用于前 TUNE 客户

This feature is currently only available for ex-TUNE clients and replicates the TUNE endpoints available via https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export

Branch Aggregate Exports 可查找并排列符合您搜索条件的聚合数据。与自定义导出不同,自定义导出包含与您的移动应用相关的每个归因的单独日志,汇总导出包括您想要查看的数据的自定义可视化视图。

🚧

iOS 14.5 发布之后 data 的变化

Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in

用户是否选择加入将影响您的最终安装数量。我们建议只要您允许选择加入,就一直延迟提取汇总 data。

For additional information on changes post iOS 14.5, visit our FAQ Pages

认证

调用 Aggregate Export API 要求将 api_key query string 参数与每个请求一起传递。 API Key 是基于每个用户生成的,并且是永久的。

Learn how to retrieve your API key (a.k.a. Access Token

🚧

需要 Organization Level 访问权限

为了获得或重置您的 API Key/访问 Token,您必须有权访问帐户的组织级别。此功能在应用级别不存在。

频率和数据限制

频率限制

频率限制取决于您发出请求的 endpoint。

为了创建和检查导出状态,频率限制为:

  • 每秒2个请求
  • 每分钟10个请求
  • 每小时1000

数据限制

  • 限制在同步 endpoint 上最多5千行
  • 异步 endpoin 上最多限制为1万行
  • 可以在导出日期之前的180天内查询。
    • 如果需要更多记录,请以较短的时间间隔进行多次请求,以将必要的数据放入“批次”中。
  • 一个维度最多只能检索40,000个唯一值 (例如,Campaign,广告名称等)

Date range limits

  • For data older than 7 days, all data is rolled up by day, according to your app's timezone. For the most recent 7 days, it is possible to query intra-day data.

导出权限设置

In order to access Aggregate Exports, a user will need to have both Aggregate Data andExport access.

1248

For more details on how to give a user the required access, please read Default Access Levels, Users Roles & Permissions.

第三方访问

任何有权访问帐户的 API key 的用户都将能够访问 Branch 的 Custom Export API(从而可以访问未经筛选的日志级数据)。因此,我们建议您不要在邀请过程中向第三方提供查看 API key 所需的权限。

提供代理商/合作伙伴 API 访问权限

如果您与运行广告 campaign 的代理商合作,并希望授予他们导出后续数据的权限,则可以向他们提供对 Custom Export API 的访问权限。

为代理商团队成员提供对 Custom Export API 的访问权限,请执行以下操作:

  1. In the left-hand navigation, under Setup & Testing, click on Account Settings.
  2. On the Account Settings page, click on the Agencies tab.
  3. Expand the agency in question, find the agency team member you want to give access to, hover on the button in the Actions column and click Edit.
  4. In the Edit Agency Team Member modal:
    1. Under Access Level, check the Export box.
    2. Under Permissions, check the Aggregate Data box.
  5. 可选:添加数据筛选项
    1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
  6. 点击保存
1242

🚧

Agency-Tagged 数据

如果您未启用 Only Show Agency-Tagged Data 筛选,则代理商团队成员将能够导出与所有 campaign 关联的汇总数据,无论它们是否与之关联。

可用的主题导出

可通过 Aggregate Export API 获得以下日志主题:

  • Clicks
  • 事件
  • Impressions(展示)
  • Installs
  • Open
  • 收入(美元)

📘

注意事项

Branch 不支持导出不常用的更新以及回传 TUNE 主题。

🚧

知识产权差异

对于无法将 IP 解析到某个位置的事件,只有很少一部分事件无法使用国家和城市等地理数据。

可用字段

Tune Field

TUNE 可读

ad_network_id

广告平台 ID

ad_network.name

广告平台名称

advertiser_id

广告主 ID

advertiser.name

广告主名称

advertiser_sub_ad.name

我的广告名称

advertiser_sub_ad.ref

我的广告参考

advertiser_sub_adgroup.name

My AdGroup Name

advertiser_sub_adgroup.ref

My AdGroup Ref

advertiser_sub_campaign.name

我的 Campaign 名称

advertiser_sub_campaign.ref

我的 Campaign 参考

advertiser_sub_keyword.name

我的关键字名称

advertiser_sub_keyword.ref

我的关键字参考

advertiser_sub_placement.name

我的 Placement 名称

advertiser_sub_placement.ref

我的 Placement 参考

advertiser_sub_publisher.name

我的发行商名称

advertiser_sub_publisher.ref

我的发行商参考

advertiser_sub_site.name

我的网站名称

advertiser_sub_site.ref

我的网站参考

country.code

国家代码

device_type

设备类型

publisher_sub_ad.name

发行商子广告名称

publisher_sub_ad.ref

发行商子广告参考

publisher_sub_adgroup.name`

Publisher Sub AdGroup Name

publisher_sub_adgroup.ref

Publisher Sub AdGroup Ref

publisher_sub_campaign.name`

发行商子 Campaign 名称

publisher_sub_campaign.ref

发行商子 Campaign 参考

publisher_sub_keyword.name

发行商子关键字名称

publisher_sub_placement.name

发行商子 Placement 名称

publisher_sub_publisher.name

发行商子发行名称

publisher_sub_site.name

发行商子网址名称

site_id

网址 ID

timestamp

timestamp

wurfl_device_os

设备操作系统

wurfl_model_name

型号名称

attributed

Attributed

🚧

停用字段

有些字段对我们的客户来说价值非常有限,因此已经停用。通过 Custom Export API将无法使用停用的字段。如果您有任何疑问或疑虑,请与您的客户成功经理或我们的支持团队合作。

包括相关数据对象中的字段

相关对象不再使用句点(。)访问该对象上的属性。字段名称将仅使用下划线(_)。

例如, site_event.id will now be exported as site_event_id

建立导出申请

查找并排列所有符合搜索条件的记录以进行导出;返回将在下载导出请求中使用的 “handle”。

建立导出申请

类型

必要项

描述

api_key

String

Y

Your API Key

start_date

Date

Y

The beginning datetime for the requested results, provided in ISO-8601 format.

不带偏差的日期(即时区)默认为给时区参数提供的值。如果未指定时区参数,则日期时区默认为 UTC。日期必须在最近的120天内。例如: 2016-01-01T00:00:00Z

end_date

Date

Y

The end datetime for the requested results, provided in ISO-8601 format.

不带偏差的日期(即时区)默认为给时区参数提供的值。如果未指定时区参数,则日期时区默认为 UTC。例如: 2016-01-01T23:59:59Z

filter

Filter

N

根据字段和布尔值运算符 (boolean operators) 针对 Actuals endpoint 的字段进行筛选。例如: &filter=(mat_id="3bc15517-92d5-4b7f-9837-e9a30d6fb9b8")+AND+("site_event_id"=1844998705)

fields

Comma Separated List

Y

List of comma-separated fields from the LogInstalls model desired in results. Defaults to display all fields

limit | Integer

Y

Limit the number of items returned per request. Maximum allowed value is 2 million. If more than 2 million records are required, please make multiple requests with smaller time intervals to pull the data needed in “batches”;

sort

Sort

N

字段后跟方向(asc 或 desc)。结果可以按多个字段和方向排序。

可选参数

group

Array

N

对所选字段返回的项目进行分组。

timestamp

String

N

设置按 timestamp 分类的统计信息。选项包括:小时,日期,日期,星期,月份。

可选参数。

format

Nullable String

N

响应格式;可以是 JSON 或 CSV。如果未选择,则默认为 CSV。

response_timezone

时区

N

传达结果日期的时区;默认为您帐户中设置的时区。

样品导出要求

https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export.json?api_key=4c5b6461026cb0caff3c66bef881b4af&start_date=2018-08-01+00%3A00%3A00&end_date=2018-08-18+00%3A00%3A00&fields[]=opens&fields[]=installs&fields[]=events&fields[]=publisher_sub_adgroup_id&fields[]=publisher_sub_campaign_id&timestamp=date&format=json

样品导出响应

{
  "status_code": 200,
  "response_size": "334",
  "throttle": {
    "decision": "Permit",
    "decision_authority": "Endpoint",
    "decision_state": "Always Permit",
    "object_key": "/advertiser/stats/actuals/export",
    "virtual_record": false,
    "next_reset": "N/A",
    "count_remaining": 0,
    "limit": 0,
    "interval": 0
  },
  "data": {
    "job_id": "5a494d8b-e5f9-4561-b71d-5c5ee4ed087d"
  }
}

构建下载导出请求

查找并导出请求的队列(按 handle 排列),并提供 URL 位置以供下载。

参数

类型

必要项

描述

advertiser_id

String

Y

Your TUNE Advertiser ID

api_key

String

Y

Your API Key

handle

String

Y

The ID returned by the log export queue.

样品报告状态请求

https://api.mobileapptracking.com/v2/export/download.json?api_key=REMOVED&job_id=5a494d8b-e5f9-4561-b71d-5c5ee4ed087d

样本报告状态响应

{"status_code":200,"response_size":"437","data":{"status":"complete","percent_complete":100,"data":{"format":"json","url":"https:\/\/s3.amazonaws.com\/hasdevfiles\/9da89700-ee8e-42f1-932f-7b9459a614dd.json?response-content-disposition=attachment%3B%20filename%3D%229da89700-ee8e-42f1-932f-7b9459a614dd.json%22&AWSAccessKeyId=AKIAIHT2RGXNQAIUT7ZA&Expires=1547654522&Signature=mfXJ7fGZeZZ%2FYPnEHssGopvdpxk%3D"},"report_schedule_id":null}}

样本下载报告

curl 'https://s3.amazonaws.com/hasdevfiles/3bce2890-97c8-44e0-985b-9c5505b7ec4a.json?response-content-disposition=attachment%3B%20filename%3D%223bce2890-97c8-44e0-985b-9c5505b7ec4a.json%22&AWSAccessKeyId=AKIAIHT2RGXNQAIUT7ZA&Expires=1535997897&Signature=v9WhAulFDVmfaR%2FzAg3uvh8DVAc%3D'

样品报告

[
  {
    "publisher_sub_campaign_id": "975222707",
    "publisher_sub_adgroup_id": "666119300",
    "installs": 0,
    "opens": 0,
    "events": 0
  },
  ...
  {
    "publisher_sub_campaign_id": "0",
    "publisher_sub_adgroup_id": "0",
    "installs": 12,
    "opens": 13,
    "events": 31
  }
]