👍

Try it!

Try out the Cohort Export API using your Branch data via the API reference here

概述

Benefits of Cohort Exports API

The Branch Cohort Exports allows you to programmatically query and export Cohort analytics.

API Limitations

Limitation

细节

Max number of records returned by API

50,000

我们可以基于 app_id / org_id 定义动态记录限制。

Export Window

Rolling 2 year window

Max number of dimensions

11

Max number of measures

5

Max number of days that can be queried at a time

90

频率限制

  • 每秒2个请求
  • 每分钟5个请求
  • 每小时150个请求

Prerequisites & API Access

先决条件

In order to access the Cohort Exports, a user will need to have both Aggregate Data and Export access.

提供代理商 API 访问权限

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

为代理商团队成员提供访问 Cohort Exports 的权限:

  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. 点击保存
12461246

🚧

Agency-Tagged 数据

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

认证

Calls to the Cohort Exports require an api_key query string parameter to be passed with each request. API Keys are generated on a per-user basis and are permanent.

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

🚧

API Key/Access Token

In order to retrieve or reset your API Key/Access Token, you must have access to the Organizational Level of the Branch account. This functionality is not present at the App Level

API Usage

Cohort Export Request

POST https://api2.branch.io/v2/analytics
Content-Type: application/json
Host: api2.branch.io

Request Headers:

标头

描述

必要项

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Content-Type

application/json

app_id

Application ID

Request Query Parameters:

参数

描述

必要项

organization_id or app_id

Unique identifier for the organization of requested data.

limit

要返回的最大结果数。

  • Default: 100
  • Min: 1
  • Max: 50000 (unless a higher limit is specified)

format

返回数据的格式。默认为 csv。

Request Body Parameters:

参数

类型

描述

必要项

start_date

Date

间隔时间范围的开始,表示为 ISO-8601 完成日期。

end_date

Date

间隔时间范围的结束表示为 ISO-8601 完成日期。

维度

Array of Strings

An array representing dimension(s) to group by. See Dimensions for a complete list.

限制为11。

data_source

String

A string value representing the cohort type, one of two possible values:

  • "install_cohort"
  • "reengagement_cohort"

筛选

Array of Strings

Keys are the same as dimensions. Values are an array of values to match for the dimension.

An object-defining filters to match or disallow certain values.

ordered

String

基于 ordered_by 值的响应顺序。

  • "ascending"
  • "descending"

Default: "descending"

ordered_by

String

The dimension name used for sorting, see Dimensions for a complete list.

指标

String

The cohort measures names to return. See Measures for a complete list.
Limit is 3

granularity_band_count

Integer

自Cohort(同期群)事件以来返回给用户的时间单位数。

cumalative

Boolean

If true, sum across bands so that a given band value is the sum of all preceding values plus the band value.
Default: false

per_user

Boolean

If true, divide each band value by the user count. Default: false

granularity

String

The time granularity that each band value will represent.
Default: "day"

enable_install_recalculation

Boolean

If true, then Branch will de-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads (result from iOS 14.5 privacy changes).

Response Body Parameters:

参数

描述

job_id

Unique identifier used to retrieve job status and data.

code

HTTP code, 2xx/4xx/5xx that represents the outcome of the status request.

status_url

Url to curl to retrieve job status and data (see Export Download Status request below).

error_message

查询失败时的错误消息

Example Request/Response:

curl -X POST 'https://api2.branch.io/v2/analytics?app_id=xxxxxxxxxxx&limit=50000&format=json' -H 'Access-Token:api_app_xxxxxxxxxxxxxxxxxxxxxxxxx' -H 'content-type:application/json' -d '{
        "start_date": "2022-05-30",
        "end_date": "2022-05-31",
        "dimensions": ["install_activity_touch_data_tilde_campaign"],
        "data_source": "install_cohort",
        "filters": {
            "install_activity_touch_data_tilde_campaign": ["A4G"]
        },
        "ordered": "descending",
        "ordered_by": "install_activity_touch_data_tilde_campaign",
        "measures": ["OPEN"],
        "granularity_band_count": 7,
        "cumulative": false,
        "per_user": false,
        "granularity": "day",
        "enable_intall_recalculation": true
}'
{
    "code" : 200,
  "job_id" : "7636f4ab-34d1-47d1-a9c9-xxxxxxxx",
  "status_url" : "https://api2.branch.io/v2/analytics/xxxxxxxxx"
}

导出下载状态

GET /v2/analytics/<job_id>
Host: api2.branch.io

Request Headers:

标头

描述

必要项

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Response Path Parameters

参数

描述

必要项

job_id

job 唯一身份标识

Request Query Parameters:

参数

描述

必要项

organization_id or app_id

用于组织所请求数据的唯一身份标识。

Response Body Parameters:

参数

描述

code

Response Code, 1xx/2xx/4xx/5xx.
Note: a 1xx will denote a QUEUED or RUNNING status.

HTTP code represents the outcome of the status request.

status

查询的状态。

  • QUEUED
  • RUNNING
  • FINISHED
  • ERROR

response_url

S3 url,用于下载响应数据。

error_message

Error message corresponding to failure reason if the query failed.

Example Request/Response:

curl 'https://api2.branch.io/v2/analytics/<job_id>?organization_id=<organization_id>' -H 'Access-Token:<branch_access_token>'
{
  "code" : 200,
  "status" : "FINISHED",
  "response_url" : "https://branch-exports.s3.amazonaws.com/partner-query/2022-05-30-2022-05-31-install_cohort-day-7636f4ab-34d1-47d1-a9c9-7cbe364953ec-xxxxxxxxxxx.json?Signature=D0zi5Jkhl073ixxxxxxxxxxxxAccessKeyId=xxxxxxxxxxxxx&Expires=1655145468"
}

附录

筛选项

在基本层按 AND 进行筛选。每个维度可以具有多个 “or” 筛选项,例如 {“user_data_os”:[“ IOS”,“ ANDROID”]}。

维度

用于维度和筛选。对于所有维度,请使用通用事件本体名称(下面以红色高亮提示)。

Install Cohort

{
  "install_activity_attributed": "attributed",
  "install_activity_event_name": "event name",
  "install_activity_touch_type": "type",
  "install_activity_touch_data_tilde_campaign_id": "campaign id",
  "install_activity_touch_data_tilde_campaign": "campaign",
  "install_activity_touch_data_tilde_channel": "channel",
  "install_activity_touch_data_tilde_feature": "feature",
  "install_activity_touch_data_tilde_stage": "stage",
  "install_activity_touch_data_tilde_tags": "tags",
  "install_activity_touch_data_tilde_advertising_partner_name": "ad partner",
  "install_activity_touch_data_dollar_3p": "ad partner (3p)",
  "install_activity_touch_data_tilde_secondary_publisher": "secondary publisher",
  "install_activity_touch_data_tilde_creative_name": "creative name",
  "install_activity_touch_data_tilde_ad_id": "ad id",
  "install_activity_touch_data_tilde_ad_set_id": "ad set id",
  "install_activity_touch_data_tilde_ad_set_name": "ad set name",
  "install_activity_touch_data_tilde_ad_name": "ad name",
  "install_activity_touch_data_tilde_keyword": "keyword",
  "install_activity_touch_data_tilde_journey_name": "journey name",
  "install_activity_touch_data_tilde_view_name": "view name",
  "install_activity_touch_data_plus_referring_domain": "referring domain",
  "install_activity_touch_data_plus_via_features": "Branch feature",
  "install_activity_touch_data_plus_web_format": "web format",
  "install_activity_data_os": "os",
  "install_activity_data_environment": "environment",
  "install_activity_data_platform": "platform",
  "install_activity_data_country_code": "country",
  "install_activity_data_has_app": "has app",
  "install_activity_data_has_clicked_email": "has clicked email",
  "install_activity_data_has_clicked_ad": "has clicked ad",
  "install_activity_timezone_adjusted_day": "date",
  "install_activity_touch_data_tilde_placement": "placement",
  "install_activity_data_device_type": "device type",
  "install_activity_touch_data_tilde_sub_site_name": "sub site name",
  "install_activity_data_brand": "brand",
  "install_activity_data_geo_country_en": "geo country",
  "install_activity_data_model": "model",
  "install_activity_data_geo_region_en": "region",
  "install_activity_touch_data_tilde_customer_secondary_publisher": "customer secondary publisher",
  "install_activity_touch_data_tilde_customer_placement": "customer placement",
  "install_activity_touch_data_tilde_customer_sub_site_name": "customer sub site name",
  "install_activity_touch_data_tilde_customer_campaign": "customer campaign",
  "install_activity_touch_data_tilde_customer_ad_set_name": "customer ad set name",
  "install_activity_touch_data_tilde_customer_ad_name": "customer ad name",
  "install_activity_touch_data_tilde_customer_keyword": "customer keyword",
  "install_activity_touch_data_tilde_agency_id": "agency id",
  "install_activity_touch_data_tilde_agency": "agency name",
  "customer_event_alias": "customer event alias"
}

Reengagement Cohort

{
  "reengagement_activity_attributed": "attributed",
  "reengagement_activity_event_name": "event name",
  "reengagement_activity_touch_type": "type",
  "reengagement_activity_touch_data_tilde_campaign_id", "campaign id",
  "reengagement_activity_touch_data_tilde_campaign": "campaign",
  "reengagement_activity_touch_data_tilde_channel": "channel",
  "reengagement_activity_touch_data_tilde_feature": "feature",
  "reengagement_activity_touch_data_tilde_stage": "stage",
  "reengagement_activity_touch_data_tilde_tags": "tags",
  "reengagement_activity_touch_data_tilde_advertising_partner_name": "ad partner",
  "reengagement_activity_touch_data_dollar_3p": "ad partner (3p)",
  "reengagement_activity_touch_data_tilde_secondary_publisher": "secondary publisher",
  "reengagement_activity_touch_data_tilde_creative_name": "creative name",
  "reengagement_activity_touch_data_tilde_ad_id": "ad id",
  "reengagement_activity_touch_data_tilde_ad_set_id": "ad set id",
  "reengagement_activity_touch_data_tilde_ad_set_name": "ad set name",
  "reengagement_activity_touch_data_tilde_ad_name": "ad name",
  "reengagement_activity_touch_data_tilde_keyword": "keyword",
  "reengagement_activity_touch_data_tilde_journey_name": "journey name",
  "reengagement_activity_touch_data_tilde_view_name": "view name",
  "reengagement_activity_touch_data_plus_referring_domain": "referring domain",
  "reengagement_activity_touch_data_plus_via_features": "Branch feature",
  "reengagement_activity_touch_data_plus_web_format": "web format",
  "reengagement_activity_data_os": "os",
  "reengagement_activity_data_environment": "environment",
  "reengagement_activity_data_platform": "platform",
  "reengagement_activity_data_country_code": "country",
  "reengagement_activity_data_has_app": "has app",
  "reengagement_activity_data_has_clicked_email": "has clicked email",
  "reengagement_activity_data_has_clicked_ad": "has clicked ad",
  "reengagement_activity_timezone_adjusted_day": "date",
  "reengagement_activity_touch_data_tilde_placement": "placement",
  "reengagement_activity_data_device_type": "device type",
  "reengagement_activity_touch_data_tilde_sub_site_name": "sub site name",
  "reengagement_activity_data_brand": "brand",
  "reengagement_activity_data_geo_country_en": "geo country",
  "reengagement_activity_data_model": "model",
  "reengagement_activity_data_geo_region_en": "region",
  "reengagement_activity_touch_data_tilde_customer_secondary_publisher": "customer secondary publisher",
  "reengagement_activity_touch_data_tilde_customer_placement": "customer placement",
  "reengagement_activity_touch_data_tilde_customer_sub_site_name": "customer sub site name",
  "reengagement_activity_touch_data_tilde_customer_campaign": "customer campaign",
  "reengagement_activity_touch_data_tilde_customer_ad_set_name": "customer ad set name",
  "reengagement_activity_touch_data_tilde_customer_ad_name": "customer ad name",
  "reengagement_activity_touch_data_tilde_customer_keyword": "customer keyword",
  "reengagement_activity_touch_data_tilde_agency_id": "agency id",
  "reengagement_activity_touch_data_tilde_agency": "agency name",
  "customer_event_alias": "customer event alias"
}

用户

{
  "user_data_platform": "platform (conversion event)",
  "user_data_environment": "environment (conversion event)",
  "user_data_geo_country_code": "country (conversion event)",
  "user_data_os": "os (conversion event)",
  "user_data_has_app": "has app (conversion event)",
  "user_data_standard_events_completed": "standard events completed (conversion event)",
  "user_data_custom_events_completed": "custom events completed (conversion event)",
  "user_data_has_clicked_ad": "has clicked ad (conversion event)",
  "user_data_has_clicked_email": "has clicked email (conversion event)",
  "user_data_brand": "brand (conversion event)",
  "user_data_device_type": "device type (conversion event)",
  "user_data_model": "model (conversion event)"
}

其他

{
    "app_id": "app id",
    "customer_event_alias": "customer event alias"
}

指标

支持以下指标列表以及所有其他自定义事件名称。

OPEN
users
Retention
ARPPU
LTV
ARPU
revenue
PURCHASE
ADD_TO_CART
ADD_TO_WISHLIST
VIEW_CART
INITIATE_PURCHASE
ADD_PAYMENT_INFO
SPENG_CREDITS
RESERVE
CLICK_AD
VIEW_AD
SEARCH
VIEW_ITEM
VIEW_ITEMS
RATE
SHARE
COMPLETE_REGISTRATION
COMPLETE_TUTORIAL
ACHIEVE_LEVEL
UNLOCK_ACHIEVEMENT
INVITE
LOGIN
SUBSCRIBE
START_TRIAL
cost
GROSS_PROFIT
ROI
ROAS
eCPA

导出格式

JSON

[
   {
      "users":200,
      "cost":"1234.45",
      "metric":"revenue",
      "measure":"ARPPU",
      "per_user":false,
      "cumulative":false,
      "data":{
         "day0":"1234.45",
         "day1":"2345.56",
         "day2":"1230.34",
         "day3":"9485.23"
      },
      "user_data_platform":"ANDROID_APP",
      "install_activity_data_tilde_advertising_partner_name":"Taptica"
   },
   {
      "users":200,
      "cost":"1234.45",
      "metric":"total_count",
      "measure":"OPEN",
      "per_user":false,
      "cumulative":false,
      "data":{
         "day0":45,
         "day1":23,
         "day2":412,
         "day3":230
      },
      "user_data_platform":"ANDROID_APP",
      "install_activity_data_tilde_advertising_partner_name":"Taptica"
   }
]

CSV

Columns are generated when exporting to CSV:
measure, metric, per_user, cumulative, user, cost, <dimensions><granularity bands>

measure,metric,per_user,cumulative,users,last_attributed_touch_data_tilde_advertising_partner,day0,day1,day2
OPEN,total_count,false,false,2099,Taptica,407,0,0
ARPPU,revenue,true,false,2099,Taptica,521.0672786,15.25,25.5
ARPPU,revenue,false,false,1835,Applovin,616.900742,10.25314465,24.09589041
OPEN,total_count,false,false,1835,Applovin,475,0,0
OPEN,total_count,true,false,1760,A4G,303,0,0
ARPPU,revenue,true,false,1760,A4G,909.0080882,14.80434783,39.46875
OPEN,total_count,false,false,401,Twitter,65,0,0
ARPPU,revenue,true,false,401,Twitter,1211.638854,16.94444444,25.5
ARPPU,revenue,true,false,369,Snap,898.039303,5,0
OPEN,total_count,false,false,369,Snap,55,0,0
ARPPU,revenue,true,false,348,Facebook,1329.544306,0,0
OPEN,total_count,false,false,348,Facebook,52,0,0
OPEN,total_count,false,false,177,Apple Search Ads,1045,0,0
ARPPU,revenue,true,false,177,Apple Search Ads,60.32139244,0,0

The above example can be viewed/downloaded: Cohort API CSV Example

Filename Format

The filename naming convention used is as follows:
start_date-end_date-data_source-granularity-job_id-random 16 character string

示例:

2019-09-23-2019-09-25-install_cohort-day-6dad4289-0cab-49cb-bfab-1be70c2b6933-edeSKgkDSkrsHGdr.<json | csv>