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.

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 的访问权限，请执行以下操作：

In the left-hand navigation, under Setup & Testing, click on Account Settings.
On the Account Settings page, click on the Agencies tab.
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.
In the Edit Agency Team Member modal:
1. Under Access Level, check the Export box.
2. Under Permissions, check the Aggregate Data box.
可选：添加数据筛选项
1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
点击保存。

🚧
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	Fields followed by the direction (asc or desc). Results can be sorted with multiple fields and directions. Optional parameter
group	Array	N	对所选字段返回的项目进行分组。
timestamp	String	N	Set to breakdown stats by timestamp. Choices include: hour, datehour, date, week, month. Optional parameter.
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
  }
]

TUNE Aggregate Exports & API

概述

📘
仅适用于前 TUNE 客户

🚧
iOS 14.5 发布之后 data 的变化

认证

🚧
需要 Organization Level 访问权限

频率和数据限制

导出权限设置

第三方访问

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

🚧
Agency-Tagged 数据

可用的主题导出

📘
注意事项

🚧
知识产权差异

可用字段

🚧
停用字段

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

建立导出申请

样品导出要求

样品导出响应

构建下载导出请求

样品报告状态请求

样本报告状态响应

样本下载报告

样品报告

筛选项

概述

📘仅适用于前 TUNE 客户

🚧iOS 14.5 发布之后 data 的变化

认证

🚧需要 Organization Level 访问权限

频率和数据限制

导出权限设置

第三方访问

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

🚧Agency-Tagged 数据

可用的主题导出

📘注意事项

🚧知识产权差异

可用字段

🚧停用字段

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

建立导出申请

样品导出要求

样品导出响应

构建下载导出请求

样品报告状态请求

样本报告状态响应

样本下载报告

样品报告

📘
仅适用于前 TUNE 客户

🚧
iOS 14.5 发布之后 data 的变化

🚧
需要 Organization Level 访问权限

🚧
Agency-Tagged 数据

📘
注意事项

🚧
知识产权差异

🚧
停用字段