开发人员中心

同期群导出

概述

Branch同期群导出允许您以编程方式查询和导出Cohort 分析。

  • API返回的最大记录数：50,000。
    • 我们可以基于app_id / org_id定义动态记录限制。
  • 最大回溯月数：24
  • 最多维度数：11
  • 最多指标数：5
  • 一次最多可以查询的天数：90

认证方式

对同类群组导出的调用要求每个请求都传递一个_api 键查询字符串参数。 API密钥是基于每个用户生成的，并且是永久的。

了解如何检索您的API密钥（又名Access Token ）

需要组织级别的访问权限

为了检索或重置您的API密钥/访问令牌，您必须有权访问帐户的组织级别。此功能在应用程序级别不存在。

速率限制

同期群导出包含以下费率限制：

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

API访问

为了访问同期群导出，用户将需要同时具有Aggregate Data 和Export 访问权限。

图像

有关如何授予用户所需访问权限的更多详细信息，请遵循授予用户导出访问权限 。

提供代理商API访问权限

如果您与经营广告活动的代理商合作，并希望授予他们导出后续数据的权限，则可以向他们提供对同期群导出的访问权限。

为代理商团队成员提供访问同期群导出的权限：

  1. 在左侧导航栏中的Setup & Testing下，点击Account Settings 。
  2. 在Account Settings 页面上，点击Agencies 选项卡。
  3. 展开有问题的代理商，找到您要授予访问权限的代理商团队成员，将鼠标悬停在Actions 列中的按钮上，然后点击Edit 。
  4. 在Edit Agency Team Member 中：
    1. 在Access Level ，选中Export 框。
    2. 在Permissions ，选中Aggregate Data 框。
  5. 可选：添加数据过滤器
    1. 在Data Filters ，将所有必要的数据过滤器切换为蓝色。导出的数据将被相应地过滤。
  6. 点击Save。

图像

代理商标签的数据

如果您未启用“仅显示带有代理商标签的数据”数据过滤器，则代理商团队成员将能够导出与您所有广告系列相关联的汇总数据，无论它们是否与它们关联。

出口要求 

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

请求

HTTP 请求头：

参数
需要
定义

Access-Token

是

封装了组织用户权限的键。

URL查询参数：

参数
需要
定义
值

Organization_id

是

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

limit

没有

返回的最大结果数。


默认值：50000


最低：50000


最大值：50000（除非指定了更高的限制）

整数

format

没有

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

csv / json

请求体参数：

参数
需要
定义
值

start_date

是

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

YYYY-MM-DD

end_date

是

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

YYYY-MM-DD

维度

没有

表示要分组的维度的数组。


限制为11。

完整列表请参见维度列表

data_source

是

代表同期群组类型的字符串值。

2个可能值之一：



  • install_cohort

  • reengagement_cohort

filters

没有

定义过滤器以匹配或禁止某些值的对象。

对象。键与尺寸相同。值是要与维度匹配的值的数组。

ordered

没有

基于ordered_by值的响应顺序。


默认值：降序。

升序或降序

ordered_by

没有

用于排序的维度

维度名称。有关完整列表，请参见维度列表 。

unique

没有

是否返回唯一值。


默认值：false

True, false

指标

是

返回的同期群指标，最多3个。

指标名称。有关完整列表，请参见指标列表 。

granularity_band_count

是

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

整数。

cumulative

e

如果为true，则累积求和，是所有先前值的总和。默认值：false

true/false

per_user

没有

如果为true，则将每个band值除以用户计数。默认值：false。

true/false

granularity

没有

每个波段值将代表的时间粒度。默认值：天

day, week, or month.

请求示例：

curl -X POST 'http://api2.branch.io/v2/analytics?organization_id=<organization_id>&limit=50000&format=json' -H 'Access-Token:<branch_access_token>' -H 'content-type:application/json' -d '{
        "start_date": "2019-09-23",
        "end_date": "2019-09-24",
        "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"
}'

返回体

参数
定义
值

job_id

用于检索作业状态和数据的唯一标识符

唯一的UUID

code

代表导出请求结果的HTTP代码。

2xx / 4xx / 5xx。

status_url

卷曲以检索作业状态和数据的网址。

见下文

error_message

如果导出调用失败，则会出现错误消息

错误信息

Status_url值：

https://api2.branch.io/v2/analytics/<job_id>

导出状态查询

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

请求

HTTP 请求头：

参数
需要
定义
值

Access-Token

是

封装了组织用户权限的键。

URL查询参数：

参数
需要
定义

Organization_id

是

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

路径参数：

参数
需要
定义

job_id

是

作业的唯一标识符

请求示例：

curl 'http://api2.branch.io/v2/analytics/<job_id>?organization_id=<organization_id>' -H 'Access-Token:<branch_access_token>'

返回体

参数
定义
值

状态

他们的状态查询。

排队，正在运行，完成，错误

code

代表状态请求结果的HTTP代码。

1xx / 2xx / 4xx / 5xx。注意：1xx将表示“已排队”或“正在运行”状态。

response_url

S3网址，用于下载响应数据。

S3网址

error_message

查询失败时的错误消息

失败原因对应的错误信息

附录

过滤器

过滤器基于顶级的AND。每个维度可以有多个"或"的过滤器例如{ " user_data_os " ：[ " IOS " ， " ANDROID " ]}。

维度

用于维度和过滤器筛选。对于所有维度，请使用通用事件本体名称（下面以红色突出显示）。

安装同期群组

{
  "install_activity_attributed": "attributed",
  "install_activity_event_name": "event name",
  "install_activity_touch_type": "type",
  "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_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"
}

再参与同期群

{
  "reengagement_activity_attributed": "attributed",
  "reengagement_activity_event_name": "event name",
  "reengagement_activity_touch_type": "type",
  "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_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"
}

User

{
  "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"
}

指标

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

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

会有以下几列: measure, metric, per_user, cumulative, user, cost, <dimensions>, <granularity bands>

示例：

[https://drive.google.com/file/d/1CDVfwoh5eetDQ79MpU7ZAKxSPah8A2F-/view?usp=sharing](https://drive.google.com/file/d/1CDVfwoh5eetDQ79MpU7ZAKxSPah8A2F-/view?usp=sharing)

文件名{#filename}

包含以下字段：start_date，end_date，data_source，granularity，job_id，以及一个随机的 16 位字符串。

示例：

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

3个月前更新

同期群导出

建议的编辑仅限于API参考页

您只能建议对Markdown正文内容进行修改，而不能建议对API规范进行修改。