👍

Try it!

Try out the Aggregate API using your Branch data via the API Reference here.

概述

The Branch Aggregate API allows you to programmatically query and export aggregate analytics.

Benefits of Branch Aggregate API

  • Give access to agencies and ad networks to pull aggregate data themselves.
    • Agencies and ad networks will only receive filtered data that they've been granted access to via user permissions.
  • Support for Facebook Marketing Partners (FMP) to have some visibility through aggregate data.

API Limitations

Limitation

细节

Max number of records returned by API

50,000
Branch may define dynamic record limits based on App/Org ID

Export Window

Rolling 2 year window

Max number of dimensions

11 Dimensions

Max number of measures

5 Measures

Max number of days that can be queried at a time

7天

频率限制

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

Prerequisites & API Access

In order to use the Branch Aggregate API, you need to have completed the following:

  1. Created a Branch Dashboard
  2. Enabled Universal Ads and are already running ad campaigns for your Branch account.
  3. Implemented the Branch SDK into your mobile app (iOS | Android)
  4. Logged into the Branch Dashboard with the Aggregate Data Permission enabled.

提供代理商 API 访问权限

If you work with an agency that runs your advertising campaigns and want to give them access to export the subsequent data, you can provide them with access to the Branch Aggregate data.

To provide an agency team member with access to the Aggregate 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
12461246

🚧

Agency-Tagged 数据

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

认证

Calls to the Branch Aggregate API require an api_key query string parameter to be passed with each request. API Keys are generated on per-user bases and are permanent.

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

NOTE: 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

导出要求

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

Request Headers:

标头

描述

必要项

Access-Token

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

Request Query Parameters:

参数

描述

必要项

organization_id or app_id

Unique identifier for app/organization of requested data.

limit

要返回的最大结果数。

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

format

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

Request Body Parameters:

参数

描述

必要项

start_date

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

end_date

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

data_source

A string value representing the data source.

See Topics for complete list.

维度

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

限制为11。

See Dimensions for complete list.

NOTE: If you are querying skadnetwork-valid-messages, be sure to set aggregation to total_count

筛选

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

定义筛选以匹配或禁止某些值的对象。

granularity

  • "day"
  • "week"
  • "month"

The time granularity that each band value will represent.

Default: day

aggregation

  • "unique_count"
  • "total_count"
  • "revenue"
  • "cost"
  • "cost-in-local-currency"

How to count events towards the final result count.

When querying with a data source of "eo_commerce_event", the aggregation may also be specified as "revenue", in which case the counts returned are the sum of revenue from matching events, and not the number of events themselves.

Default: total_count

enable_install_calculation

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).

默认值:false

Response Body Parameters

参数

描述

code

The response code

job_id

The unique ID of the request. This is used in the Export Download Status request.

status_url

The URL of the export request.

Example Request/Response:

curl --request POST \
     --url 'https://api2.branch.io/v2/analytics?organization_id={organization_id}&limit=5000&format=json' \
     --header 'Accept: application/json' \
     --header 'Access-Token: api_org_9999999999999999999999999999' \
     --header 'Content-Type: application/json' \
     --data '
{
     "start_date": "2021-12-12",
     "end_date": "2021-12-18",
     "data_source": "eo_install",
     "dimensions": [
          "user_data_os"
     ],
     "filters": {
          "attributed": "true",
          "user_data_os": [
              "IOS", 
              "ANDROID"
          ]
     },
     "enable_install_recalculation": true,
     "granularity": "day",
     "aggregation": "total_count"
}
'
{
    "code": 200,
    "job_id": "8a2514d5-9035-445f-b42a-948112aeb807",
    "status_url": "https://api2.branch.io/v2/analytics/a38bd2f0-9740-4334-8c96-5bfd90671b06"
}

导出下载状态

GET /v2/analytics/{job_id}
Host: api2.branch.io
Accept: application/json

Request Headers:

标头

描述

必要项

Access-Token

Key that encapsulates the users permission w.r.t an org. Obtained from the Branch Dashboard.

Response Path Parameters

参数

描述

必要项

job_id

The unique ID of the request.

Obtained from the Export Request

Request Query Parameters:

参数

描述

必要项

organization_id or app_id

Unique identifier for app/organization of requested data.

limit

要返回的最大结果数。

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

format

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

Response Body Parameters

参数

描述

code

The response code

status

The status of the original request by job_id

response_url

The URL of your request for download.

Example Request/Response:

curl --request GET \
     --url 'https://api2.branch.io/v2/analytics{job_id}?organization_id=787326553414456146&limit=5000&format=json' \
     --header 'Accept: application/json' \
     --header 'Access-Token: api_org_99999999999999999999'
{
    "code": 200,
    "status": "FINISHED",
    "response_url": "https://branch-exports.s3.amazonaws.com/partner-query/2021-12-12-2021-12-18-eo_install-day-8a2514d5-9035-445f-b42a-948112aeb807-j6zbNS9OxQOz7spz.json?Signature=gbEoMAFAr0y7kN3stZ1zzUh60ko%3D&AWSAccessKeyId=AKIAI7A6NRHGMRDK2LIQ&Expires=1648077926"
}

附录

筛选项

Filters work based on AND at the top level. Each dimension can have multiple "or" filters e.g. { "user_data_os": ["IOS", "ANDROID"] }.

Topics

[
  "eo_impression",
  "eo_click",
  "eo_web_to_app_auto_redirect",
  "eo_branch_cta_view",
  "eo_sms_sent",
  "eo_open",
  "eo_install",
  "eo_reinstall",
  "eo_web_session_start",
  "eo_pageview",
  "eo_commerce_event",
  "eo_custom_event",
  "eo_content_event",
  "eo_dismissal",
  "eo_user_lifecycle_event",
  "cost",
  "skadnetwork-valid-messages",
  //Fraud Topics
  "eo_click_blocked",
  "eo_impression_blocked",
  "eo_install_blocked",
  "eo_reinstall_blocked",
  "eo_open_blocked",
  "eo_web_session_start_blocked",
  "eo_pageview_blocked",
  "eo_sms_sent_blocked",
  "eo_custom_event_blocked",
  "eo_content_event_blocked",
  "eo_commerce_event_blocked",
  "eo_user_lifecycle_event_blocked",
  "eo_branch_cta_view_blocked",
  "eo_web_to_app_auto_redirect_blocked"
]

维度

[
  "name",
  "origin",
  "timestamp",
  "deep_linked",
  "from_desktop",
  "attributed"
]
[
  "user_data_os",
  "user_data_language",
  "user_data_platform",
  "user_data_environment",
  "user_data_geo_region_en",
  "user_data_geo_dma_code",
  "user_data_geo_country_code",
  "user_data_country",
  "user_data_opted_in",
  "user_data_opted_in_status"
]
[
  "last_attributed_touch_type",
  "last_attributed_touch_data_tilde_tags",
  "last_attributed_touch_data_tilde_secondary_publisher",
  "last_attributed_touch_data_plus_current_feature",
  "last_attributed_touch_data_plus_via_features",
  "last_attributed_touch_data_tilde_campaign",
  "last_attributed_touch_data_tilde_advertising_partner_name",
  "last_attributed_touch_data_tilde_advertising_partner_id",
  "last_attributed_touch_data_tilde_feature",
  "last_attributed_touch_data_tilde_creative_name",
  "last_attributed_touch_data_plus_web_format",
  "last_attributed_touch_data_tilde_creative_id",
  "last_attributed_touch_data_tilde_ad_name",
  "last_attributed_touch_data_tilde_ad_id",
  "last_attributed_touch_data_tilde_campaign_id",
  "last_attributed_touch_data_tilde_placement",
  "last_attributed_touch_data_tilde_stage",
  "last_attributed_touch_data_tilde_channel",
  "last_attributed_touch_data_tilde_ad_set_name",
  "last_attributed_touch_data_tilde_ad_set_id",
  "last_attributed_touch_data_tilde_keyword",
  "last_attributed_touch_data_tilde_journey_id",
  "last_attributed_touch_data_tilde_view_name",
  "last_attributed_touch_data_tilde_view_id",
  "last_attributed_touch_data_tilde_agency",
  "last_attributed_touch_data_tilde_agency_id"
]
[
  "last_cta_view_data_tilde_ad_name",
  "last_cta_view_data_tilde_secondary_publisher",
  "last_cta_view_data_tilde_campaign",
  "last_cta_view_data_tilde_advertising_partner_name",
  "last_cta_view_data_tilde_feature",
  "last_cta_view_data_tilde_ad_set_name",
  "last_cta_view_data_tilde_ad_set_id",
  "last_cta_view_data_tilde_campaign_id",
  "last_cta_view_data_tilde_creative_name",
  "last_cta_view_data_tilde_creative_id",
  "last_cta_view_data_plus_via_features",
  "last_cta_view_data_dollar_3p",
  "last_cta_view_data_tilde_tags",
  "last_cta_view_data_plus_web_format",
  "last_cta_view_data_tilde_channel",
  "last_cta_view_data_tilde_ad_id",
  "last_cta_view_data_tilde_stage"
]
[
  "body_ad_network_id",
  "body_campaign_id",
  "body_app_id",
  "body_redownload",
  "body_source_app_id",
  "body_conversion_value",
  "body_last_attributed_touch_data_tilde_creative_name",
  "body_last_attributed_touch_data_tilde_ad_set_name",
  "body_last_attributed_touch_data_tilde_creative_id",
  "body_last_attributed_touch_data_tilde_ad_set_id",
  "body_last_attributed_touch_data_tilde_ad_name",
  "body_last_attributed_touch_data_tilde_ad_id",
  "body_last_attributed_touch_data_tilde_campaign_id",
  "body_last_attributed_touch_data_tilde_campaign_name",
  "annotation_dollar_3p",
  "annotation_conversion_value_mapped_value",
  "annotation_conversion_value_revision",
  "annotation_campaign_id_mapped_value",
  "annotation_campaign_id_revision",
  "annotation_source_app_id_mapped_value",
  "annotation_source_app_id_revision",
  "body_last_attributed_touch_data_tilde_campaign",
  "last_attributed_touch_data_tilde_creative_name",
  "last_attributed_touch_data_tilde_ad_set_name",
  "last_attributed_touch_data_tilde_creative_id",
  "last_attributed_touch_data_tilde_ad_set_id",
  "last_attributed_touch_data_tilde_ad_name",
  "last_attributed_touch_data_tilde_ad_id",
  "last_attributed_touch_data_tilde_campaign_id",
  "last_attributed_touch_data_tilde_campaign",
  "last_attributed_touch_data_tilde_agency",
  "last_attributed_touch_data_tilde_agency_id",
  "last_attributed_touch_data_tilde_advertising_partner_name",
  "last_attributed_touch_data_tilde_advertising_partner_id",
  "annotation_customer_event_alias"
]
[
  "days_from_last_attributed_touch_to_event",
  "days_from_last_cta_view_to_event",
  "event_data_product_categories",
  "first_event_for_user",
  "customer_event_alias"
]