开发者中心

Cohort（同期群）输出和 API

概述

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

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

认证方式

调用同类群组导出时，需要在每个请求中传递api_key查询字符串参数。 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标头：

HTTP标头参数

Access-Token | yes

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

URL查询参数：

URL查询参数

organization_id | yes

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

limit | no | integer

要返回的最大结果数。

默认值：50000

最低：50000

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

format | no | csv/json

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

身体参数：

身体参数

start_date | yes | YYYY-MM-DD

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

end_date | yes | YYYY-MM-DD

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

dimensions | no | See Dimensions for complete list

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

限制为11。

data_source | yes | One of 2 possible values:

  • install_cohort
  • 再次参与

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

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

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

ordered | no | descending or ascending.

基于ordered_by值的响应顺序。

默认值：降序。

ordered_by | no | Dimension name. See Dimensions for complete list..

用于排序的维度

unique | no | True, false

是否返回唯一值。

默认值：false

measures | yes | Measure name. See Measures for complete list.

队列测量返回。限制为3。

granularity_band_count | yes | Integer.

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

cumulative | no | true/false.

如果为true，则跨频带求和，以便给定的频带值是所有先前值加频带值的总和。默认值：false。

per_user | no | true/false.

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

granularity | no | 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 | Unique UUID

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

code | 2xx/4xx/5xx.

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

status_url | See below.

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

error_message | Error message

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

Status_url值：

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

导出下载状态

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

请求

HTTP标头：

HTTP标头参数

Access-Token | yes

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

URL查询参数：

URL查询参数

organization_id | yes

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

路径参数：

路径参数

job_id | yes

工作的唯一标识符

请求示例：

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

响应

响应参数

status | QUEUED, RUNNING, FINISHED, ERROR

他们查询的状态。

code | 1xx/2xx/4xx/5xx. Note: a 1xx will denote a QUEUED or RUNNING status.

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

response_url | S3 url.

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

error_message | error message corresponding to failure reason

查询失败时的错误消息

附录

筛选器

过滤器基于顶级的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_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

列：度量，度量，每用户，累积，用户，成本， <dimensions> ， <granularity bands>

示例：

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

文件名{#filename}

开始日期，结束日期，数据源，粒度，作业ID，随机16个字符串

示例：

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

24 天前更新

Cohort（同期群）输出和 API

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

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