Custom Exports API

👍

Try it!

Try out the Custom Exports API using your Branch data via the API reference here

概述

Benefits of Custom Exports API

• The Branch Custom Exports find and queue log records that match your search criteria for export. You can do so either via the Custom Exports section in your Branch Dashboard or via the API (this page).

API Limitations

*You will get the following response once you've hit the rate limit:

{
    "errors": [
        {
            "message": "Limit is exceeded for org-525983469347282987, retry after 3418 seconds",
            "error_code": 7
        }
    ]
}

Prerequisites & API Access

In order to use the Custom Exports API, you need to have completed the following:

1. Created a Branch Dashboard
2. Implemented the Branch SDK into your mobile app (iOS | Android)
   • Track events.
3. Opt into sharing 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 Changes Post iOS

Opt-ins will affect your final install count. We recommend using a different identifier (ex. IDFV) to de-dupe install events on your internal systems.

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

4. Logged into the Branch Dashboard with the Sensitive Data and Export Access Permission enabled.

提供代理商 API 访问权限

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

🚧

Data Purge

• Branch will purge last-attributed data after 60 days.

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

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

1. In the left-hand navigation, under Configure, 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 Sensitive Data box.
5. 可选：添加数据筛选项
   1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
6. 点击保存 。

🚧

Agency-Tagged 数据

如果您未启用 Only Show Agency-Tagged Data 数据筛选项，则代理商团队成员将能够导出与所有 campaign 关联的敏感数据。

认证

Calls to the Custom Export API require an access token parameter to be passed with each request. Access tokens are generated on a per-user basis and are permanent.

Learn how to retrieve your Access Token (a.k.a. an API Key).

API Usage

Create Export Request

POST /v2/logs?organization_id=ORG_ID
POST /v2/logs?app_id=APP_ID
Headers:
Access-Token: API_KEY
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers:

Request Body Parameters:

Response Body Parameters:

Example Request/Response:

curl -X POST 'https://api2.branch.io/v2/logs?app_id=123456700098765432'
    -H "Content-Type: application/json"
    -H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
    -d '{"report_type": "eo_open",
            "limit": 100,
            "fields": ["timestamp","name"],
            "start_date": "2019-12-09T00:00:00Z",
            "end_date": "2019-12-09T01:59:59Z",
            "filter": ["gt","last_attributed_touch_timestamp", 1604015756]
            }'

{"handle":"1612dbb3-85ef-49f8-b1c5-5818c163600c","export_job_status_url":"https://api2.branch.io/v2/logs/1612dbb3-85ef-49f8-b1c5-5818c163600c?app_id=123456700098765432"}

Response Codes:

Get Export Request

GET /v2/logs/JOB_ID
Headers:
Access-Token: API_KEY
Host: api2.branch.io

Request Headers:

Response Path Parameters

Request Query Parameters:

Response Body Parameters

Example Request/Response:

curl -X GET https://api2.branch.io/v2/logs/<YOUR_HANDLE>\?app_id\=<YOUR_BRANCH_APP_ID>
  -H "Content-Type: application/json" 
  -H "Access-Token:<YOUR_ACCESS_TOKEN>"

{"code":200,"lines_exported":2000000,"status":"complete","response_url":"https://branch-exports-web.s3.amazonaws.com/732662944269095814-eo_open-2019-12-10-2019-12-10-1612dbb3-85ef-49f8-b1c5-5818c163600c-bUlN2lwyTE10qIVH.csv?Signature=YOUR_ACCESS_TOKEN_HERE&AWSAccessKeyId=YOUR_ACCESS_TOKEN_HERE&Expires=1577305615"}

Response Codes:

Status Values:

附录

Available EO Fields

Available SKAdNetwork Message Fields

🚧

知识产权差异

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

Available Topics

🚧

被屏蔽的主题

Branch 允许从请求之日起最多导出60天的被阻止主题。

Cthulhu 筛选说明

Cthulhu 是用 JSON 编写的前缀表示法语法，用于指定记录（通常是基于列的记录）上的筛选项。

目的
轻松解析成抽象语法树。

词汇表
any - any valid json basic value (number, string)
... - previous item in a list can repeat as many times as necessary