Cohort(同期群)输出和 API

概述

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

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

认证方式

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密钥/访问令牌,您必须有权访问帐户的组织级别。此功能在应用程序级别不存在。

速率限制

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

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

API访问

为了访问同期群导出,用户将需要同时具有Aggregate DataExport 访问权限。

图像图像

For more details on how to give a user the required access, please follow Granting a User Export Access.

提供代理商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

没有

The maximum number of results to return.
Default: 50000
Min: 50000
Max: 50000 (unless a higher limit is specified)

整数

format

没有

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

csv / json

请求体参数:

参数

需要

定义

start_date

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

YYYY-MM-DD

end_date

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

YYYY-MM-DD

维度

没有

An array representing dimension(s) to group by.
Limit is 11.

See Dimensions for complete list

data_source

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

2个可能值之一:

  • install_cohort
  • reengagement_cohort

filters

没有

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

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

ordered

没有

Order of response based on ordered_by value.
Default: descending.

升序或降序

ordered_by

没有

用于排序的维度

Dimension name. See Dimensions for complete list.

unique

没有

Whether or not to return unique values.
Default: false

True, false

指标

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

Measure name. See Measures for complete list.

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>

更新9 天前


Cohort(同期群)输出和 API


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

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