Adjust KPI 服务
Adjust KPI 服务是 Adjust 的拉式 API,您可以对其进行编程,针对您跟踪的移动应用发出数据请求。下文介绍了 RESTful JSON API 如何实现这一功能。
操作前须知
以下是您在操作前需要了解的内容。
适用条件
- KPI 服务仅向 Business Pro 及以上等级套餐的客户提供
实用信息
- 以下页面包含使用最小长度跟踪码的示例。请始终使用 Adjust 推广设置向导中显示的完整跟踪码。
您可以向 API 发出三种查询:概览 (Overview)、事件 (Events)和同期群 (Cohorts)。这些主要反映了 Adjust 控制面板中不同的部分,并且支持直接拉动相关 KPI。
查询可以是针对应用的所有渠道跟踪链接,也可以是针对给定父级跟踪链接。因此,每个资源都有两个终端:一端是没有跟踪码,默认为所有渠道跟踪链接进行数据分组,另一端则支持您指定跟踪码并细分到子跟踪链接组。
开始了解 KPI API 内容前,您可以查看为补充此 API 开发的 R 客户端。R 客户端可直接将 Adjust 数据导入 R 会话,非常简单易用。
想要 API 数据具备价值,跟踪链接的概念至关重要。因此,请确保您熟悉跟踪链接相关术语,以及渠道、推广活动、广告组和素材子层等分层结构的概念。
版本控制
API 发布了几个不同的版本。为避免混淆,API 版本明确写入所有终端的 URL 路径中。例如,访问 http://api.adjust.com/kpis/v1/..
获取版本 1。
响应格式
API 支持两种响应格式:CSV 和 JSON(默认为 JSON)。若要指定不同的格式,您可以相应地为终端添加后缀(例如,在终端路径的末尾添加 .csv
)或者随请求发送 Accept: text/csv
HTTP 标头。本文档中,我们主要使用 JSON 来介绍请求和响应。
认证
您的 KPI 服务的访问权限与 Adjust 用户账户相关联。每个用户账户都有一个关联的用户识别码,支持您单独控制 KPI 的访问权限。
您可以进入控制面板,在 账户设置 > 您的数据 > 用户详情 中找到用户识别码。这是我们在接下来进行身份验证时引用的用户识别码。
每个用户识别码都与控制面板用户有相同的限制条件。也就是说,如果您设置自定义用户权限,则通过 KPI 服务的访问权限将会遵循与控制面板访问权限相同的规则。
您可以随时更新用户识别码。
使用用户识别码进行 API 身份验证有两种选择,您可根据给定的使用情况选择自己喜欢的一种:
- HTTP GET 参数 — 向任意 API 查询附加 user_token=your_user_token
- HTTP 认证标头 — 添加以下 HTTP 标头:
Authorization: Token token=your_user_token
本文档中的所有示例都假设了 HTTP 标头认证,但您也可以向示例附加带有正确识别码的 GET 参数。
应用识别码和跟踪码
为避免混淆,我们将在此处记录的所有终端中提及这两个识别码::app_token
和 :tracker_token
必须替换为实际识别码才能获得有效的请求 URL。例如:
https://api.adjust.com/kpis/v1/2eb2na2w54c3/trackers/15jvui
才是应用识别码 2eb2na2w54c3
和跟踪码 15jvui
的有效 URL。本文档中的所有示例都使用应用识别码 2eb2na2w54c3
,您可以用自己的应用识别码轻松替换。
概览查询
概览查询可以提供应用 KPI 和事件 KPI 数据。通常,您会感兴趣的是给定时间段内应用运行的所有渠道和给定的 父级 跟踪链接 的指标 (例如 clicks
、sessions
、installs
等等)。您还可以为自定义 Adjust 事件 (例如,revenue
、first_events
等) 请求 KPI。此外,还可以套用可选的 国家/地区 、 平台 和 设备 范围。
终端
GET https://api.adjust.com/kpis/v1/:app_token{.csv|.json}
GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token{.csv|.json}
查询参数
此处提供了一份受支持查询参数的列表;还可参阅预期参数值详情。
参数名称 | 格式 | 描述 |
start_date | YYYY-MM-DD | 选定周期的开始日期。 |
end_date | YYYY-MM-DD | 选定周期的结束日期。 |
utc_offset | [+-]HH:MM,例如, utc_offset=-05:00 或 utc_offset=10:00 | 与UTC 0 时区的时差,例如:如果您希望查询的起止日期是以北京时间定义的,那么您在此可以设此参数为:utc_offset=08:00 |
kpis | 字符串,例如, clicks,installs,maus | 用逗号隔开的 应用 KPI列表。可以采用任意组合的应用 KPI。 |
event_kpis | 字符串,例如, token1_events,token1_revenue_per_user | 用逗号隔开的 事件 KPI列表。为每个 KPI 添加事件识别码或 all 前缀。有关示例,请参见下文。 |
reattributed | 字符串 true 、false 或 all | 根据仅已安装或已再归因的用户或者全部用户筛选 KPI(默认) |
sandbox | 字符串 true 或 false | 可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。 |
impression_based (已弃用) | 字符串 true 或 false |
已弃用,请换用 |
attribution_type | 字符串 click 、impression 或 all | 点击、展示或结合点击与展示。 请注意:已弃用 = true 等同于 = false 等同于 |
attribution_source | 字符串 first 或 dynamic | 确定应用内活动是分配给用户的安装来源 ( first ),还是分配给安装来源和后续再归因来源 (dynamic )。默认情况下,设置为 dynamic 。 |
countries | 字符串,例如, de,us | 用逗号隔开的国家/地区名称列表(采用 ISO 3166 alpha-2 代码) |
os_names | 字符串,例如, ios,android | 用逗号隔开的操作系统名称列表。在下面找到有效的操作系统名称。 |
device_types | 字符串,例如, phone,tablet | 用逗号隔开的设备类型列表。在下面找到有效的设备类型。 |
regions | 字符串,例如 APAC、EMEA | 由逗号分隔的标准或账户特定业务地区列表。在地区名称之前添加+ 或 - 号来包含(默认)或排除地区。 |
grouping | 字符串,例如, trackers,countries | 为参数分组。有关分组的更多详细信息,请参见下文。 |
cohort_revenue_period | 字符串,例如15d 、[1d-30d , 60d , 90d , 120d ] | 结果将仅汇总归因后前 n 天的收入。 |
应用 KPI
下面给出了支持的应用 KPI 列表,您可以将其传递给 kpis
参数。
应用 KPI | 描述 |
clicks | 点击量 |
impressions | 展示量 |
installs | 安装量 |
uninstalls | 卸载量 |
uninstall_cohort | 所选时段内,已安装应用用户的卸载量 |
reinstalls | 重装量 |
click_conversion_rate | 点击转化率(平均 安装 /点击 ,按点击 加权)。 |
ctr | 点击率( 点击 /展示 ,按展示 加权)。 |
impression_conversion_rate | 展示转化率(平均 安装 /展示 ,按展示 加权)。 |
reattributions | 再归因量 |
reattribution_reinstalls | 导致再归因的总重装量 |
deattributions | 离归因量 |
sessions | 会话量 |
revenue_events | 收入事件量 |
revenue | 总收入(按应用的报告币种计算) |
all_revenue | revenue + ad_revenue |
cohort_revenue | 选定时间内已归因的用户带来的总收入 |
daus | 平均每日活跃用户 |
waus | 平均每周活跃用户 |
maus | 平均每月活跃用户 |
limit_ad_tracking_installs | 已启用限制广告跟踪的设备产生的安装量 |
limit_ad_tracking_install_rate | 已启用限制广告跟踪的设备产生的安装比例:limit_ad_tracking_installs /installs |
limit_ad_tracking_reattributions | 已启用限制广告跟踪的设备产生的再归因量 |
limit_ad_tracking_reattribution_rate | 已启用限制广告跟踪的设备产生的安装比例:limit_ad_tracking_reattributions /reattributions |
gdpr_forgets | 已经行使被遗忘权的用户总数。Adjust 将永久删除所有这些用户的个人历史数据,但会保留他们用于控制面板报告的聚合数据。Adjust 将不会再接收他们的设备数据,这些设备数据将来也不会出现在 Adjust 控制面板中。 |
cohort_ad_revenue | 在选定时间段内,用户安装所带来的总广告收入 |
cohort_all_revenue | cohort_revenue + cohort_ad_revenue |
作弊 KPI
作弊 KPI 仅适用于已启用 Adjust 防作弊套件的账户。
作弊 KPI | 描述 |
rejected_installs | 被拒安装量。此为 rejected_installs_anon_ip + rejected_installs_too_many_engagements + rejected_installs_distribution_outlier + rejected_installs_click_injection 的总和 |
rejected_installs_anon_ip | 因匿名 IP 被拒安装量 |
rejected_installs_too_many_engagements | 因交互过多被拒安装量 |
rejected_installs_distribution_outlier | 因分布异常被拒安装量 |
rejected_installs_click_injection | 因交互劫持被拒安装量 |
rejected_installs_invalid_signature | 因缺失或无效 SDK 签名被拒安装量 |
rejected_reattributions | 被拒再归因量。此为 rejected_reattributions_anon_ip + rejected_reattributions_too_many_engagements + rejected_reattributions_distribution_outlier + rejected_reattributions_click_injection 的总和 |
rejected_reattributions_anon_ip | 因匿名 IP 被拒再归因量 |
rejected_reattributions_too_many_engagements | 因交互过多被拒再归因量 |
rejected_reattributions_distribution_outlier | 因分布异常被拒再归因量 |
rejected_reattributions_click_injection | 因交互劫持被拒再归因量 |
rejected_install_rate | 被拒安装率: rejected_installs /( |
| 因匿名 IP 被拒安装率: rejected_installs_anon_ip /(installs + rejected_installs )。 |
| 因交互过多被拒安装率: rejected_installs_too_many_engagements /(installs + rejected_installs )。 |
| 因分布异常被拒安装率: rejected_installs_distribution_outlier /(installs + rejected_installs )。 |
| 因交互劫持被拒安装率: rejected_installs_click_injection /(installs + rejected_installs ) |
| 被拒再归因率: rejected_reattributions /(reattributions + rejected_reattributions )。 |
| 因匿名 IP 被拒再归因率: rejected_reattributions_anon_ip /(reattributions + rejected_reattributions )。 |
| 因交互过多被拒再归因率: rejected_reattributions_too_many_engagements /(reattributions + rejected_reattributions )。 |
| 因分布异常被拒再归因率: rejected_reattributions_distribution_outlier /(reattributions + rejected_reattributions )。 |
| 因劫持交互被拒再归因率: rejected_reattributions_click_injection /(reattributions + rejected_reattributions ) |
成本 KPI
成本 KPI 仅适用于已启用成本数据的账户。
成本 KPI | 描述 |
---|---|
install_cost | 安装成本 |
click_cost | 点击成本 |
impression_cost | 展示成本 |
cost | 总计: click_cost + impression_cost + install_cost + event_cost |
paid_installs | 存在成本数据的安装量 |
paid_clicks | 存在成本数据的点击量 |
paid_impressions | 存在成本数据的展示量 |
CPE | 每事件成本总计,即 event_cost / paid_events |
ecost | 成本总计,仅用于 eCPI、eCPC 和 eCPM 总计: click_cost + impression_cost + install_cost |
ecpc | 单次点击有效成本,即 ecpi_cost / paid_clicks |
ecpi | 单次安装有效成本,即 cost / paid_installs |
ecpm | 每千次展示有效成本,即 cost / paid_impressions * 1000 |
cohort_gross_profit | 毛利,即 cohort_all_revenue - cost |
return_on_investment | 投资回报率指标: cohort_gross_profit / cost |
RCR | 收入成本比率: cohort_all_revenue / cost |
roas | 广告支出回报率,ROAS 指标计算公式: cohort_all_revenue/cost *100 |
请注意: 所有成本 KPI 都四舍五入至小数点后两位; ecpc
、ecpm
和 ecpi
则是例外,四舍五入至小数点后四位。例如,在舍入小数点后两位时,5.45661 欧元将显示为 cost=5.46 。
广告收入 KPI
广告收入 KPI | 描述 |
ad_revenue | 来自 ad_impressions 的总收入(按应用的报告币种计算) |
ad_impressions | ad_impressions 的数量 |
ad_rpm | 每千次展示的 ad_revenue,即ad_revenue / ad_impressions * 1000 |
事件 KPI
查看可以传递的支持事件 KPI 的列表,"概览" 请求的 event_token
参数前添加 event_kpis
前缀。如事件部分所述,这些事件 KPI 也用于 Events
请求。
事件 KPI | 描述 |
revenue_events | 收入事件量 |
revenue | 总收入(按应用的报告币种计算) |
events | 事件量 |
first_events | 用户首次触发的事件量。 first_events 与 events 的关系类似于 installs 和 sessions 。 |
revenue_per_event | 总收入除以事件量 |
revenue_per_revenue_event | 总收入除以收入事件量 |
简化事件 KPI 请求
本节内容仅供您计划通过概览请求申请 event_kpis 时参阅。如果是其他操作,您可以跳过本节。
单独指定 event_kpis 可能会很快导致参数过长。例如:以下是 event_kpis 的有效值:
event_kpis=token1_events,token2_events,token1_revenue,token2_revenue
为避免这种情况,我们支持使用一些快捷方式。字符串:
event_kpis=token1_revenue|events|revenue_per_event
等同于
event_kpis=token1_revenue,token1_events,token1_revenue_per_event
此外,可以使用特殊关键词 all
,从而扩展至 全部 定义事件。例如:您有两个识别码分别为 token1
和 token2
的事件,值:
event_kpis=all_revenue|events|revenue_per_event
就会等同于
event_kpis=token1_revenue,token1_events,token1_revenue_per_event,token2_revenue,token2_events,token2_revenue_per_event
最后,字符串:
event_kpis=all_revenue,all_events,all_revenue_per_event
就会等同于
event_kpis=token1_revenue,token2_revenue,token1_events,token2_events,token1_revenue_per_event,token2_revenue_per_event
请注意,最后两种格式的区别在于指标的顺序不同。如果要了解更多相关信息,请继续参阅下文。
示例
仅请求应用 KPI
请求:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions,installs&countries=de,gb
响应:
{
"result_parameters": {
"kpis": ["sessions", "installs"],
"start_date": "2015-05-01",
"end_date": "2015-05-31",
"sandbox": false,
"countries": ["de", "gb"],
"trackers": [
{
"token": "foobar",
"name": "Network 1",
"has_subtrackers": true
},
{
"token": "15jvui",
"name": "Network 2",
"has_subtrackers": true
}
],
"grouping": ["trackers"]
},
"result_set": {
"token": "2eb2na2w54c3",
"name": "app name",
"currency": "USD",
"trackers": [
{
"token": "foobar",
"kpi_values": [100, 299]
},
{
"token": "15jvui",
"kpi_values": [557, 880]
}
]
}
}
请注意 result_parameters
中的 kpis
数组与 result_set
中的 kpi_values
数组之间是一一对应的关系。例如:此响应中的跟踪链接渠道 1
有 100 个 会话
和 299 次 安装
。
请求应用与事件 KPI
除 kpis
参数之外,您还可以使用 event_kpis
参数请求事件 KPI。
请求:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=clicks&event_kpis=token1_events,token1_revenue&countries=de,gb
响应:
{
"result_parameters": {
"kpis": ["clicks", "token1_events", "token1_revenue"],
"start_date": "2015-05-01",
"end_date": "2015-05-31",
"sandbox": false,
"countries": ["de", "gb"],
"trackers": [
{
"token": "foobar",
"name": "Network 1",
"has_subtrackers": true
},
{
"token": "15jvui",
"name": "Network 2",
"has_subtrackers": true
}
],
"events":[
{
"name": "YourEventName",
"token": "token1"
}
],
"grouping": ["trackers"]
},
"result_set": {
"token": "2eb2na2w54c3",
"name": "app name",
"currency": "USD",
"trackers": [
{
"token": "foobar",
"kpi_values": [221, 100, 299.30]
},
{
"token": "15jvui",
"kpi_values": [1005, 557, 880.75]
}
]
}
}
请注意 result_parameters
中的 kpis
数组与 result_set
中的 kpi_values
数组之间是一一对应的关系。此响应中的跟踪链接渠道 1
有 221 次点击,识别码为 token1
的事件发生了 100 次,这些事件创收 299.30。
KPI 排序
请注意,请求 kpis
和/或 event_kpis
的顺序决定了将收到的响应的顺序。上述后一个示例说明了这一点。
当您向 API 请求 csv
数据时,KPI 排序可能会特别有用。在这种情况下,响应的各列可能会与您请求 KPI 的顺序精确对应。
事件查询
本节内容主要介绍事件 KPI 查询。如果您要按事件对数据分组,这些终端值会十分有用。
终端
GET https://api.adjust.com/kpis/v1/:app_token/events{.csv|.json}
GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token/events{.csv|.json}
查询参数
此处给出了一个受支持的查询参数列表;还可参阅预期参数值详情。
参数名称 | 格式 | 描述 |
start_date | YYYY-MM-DD | 选定周期的开始日期 |
end_date | YYYY-MM-DD | 选定周期的结束日期 |
utc_offset | &[+-]HH:MM,例如, utc_offset=-05:00 或 utc_offset=10:00 | 与UTC 0 时区的时差,例如:如果您希望查询的起止日期是以北京时间定义的,那么您在此可以设此参数为:utc_offset=08:00 |
kpis | 字符串,例如, revenue_events,revenue | 用逗号隔开的 事件 KPI列表。可以采用任意组合的事件 KPI。 |
sandbox | 字符串 true 或 false | 可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。 |
events | 字符串,例如, event_token1,event_token2 | 用逗号隔开的事件识别码列表。在 Adjust 控制面板中可以查看事件的事件识别码。 |
attribution_type | 字符串 click 、impression 或 all | 点击、展示或结合点击与展示(此操作将覆盖 impression_based 参数) |
attribution_source | 字符串, first 或 dynamic | 确定应用内活动是分配给用户的安装来源 ( first ),还是分配给安装来源和后续再归因来源 (dynamic )。默认情况下,设置为 dynamic 。 |
countries | 字符串,例如, de,us | 用逗号隔开的国家/地区名称列表(采用 ISO 3166 alpha-2 代码) |
os_names | 字符串,例如, ios,android | 用逗号隔开的操作系统名称列表。在下面找到有效的操作系统名称。 |
device_types | 字符串,例如, phone,tablet | 用逗号隔开的设备类型列表。在下面找到有效的设备类型。 |
partner_ids | 整数,例如: 1234,789 | 用逗号隔开的合作伙伴 ID 列表。将只显示属于这些合作伙伴的跟踪链接上的数据。 |
grouping | 字符串,例如, trackers,countries | 为参数分组。有关分组的更多详细信息,请参见下文。 |
事件 KPI
事件 KPI 列表同上。尽管如此,还需注意:您在执行 概览
请求时,不用在事件 KPI 前面加上事件识别码,这一点与 事件
查询不同。如果需要特定事件的相关数据,请用事件参数替换事件识别码。
示例
请求:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/events?start_date=2015-05-01&end_date=2015-05-31&kpis=revenue,events,revenue_per_event&grouping=trackers,weeks,events&countries=de,gb
响应:
{
"result_parameters": {
"kpis": ["revenue", "events", "revenue_per_event"],
"start_date": "2015-05-01",
"end_date": "2015-05-31",
"sandbox": false,
"countries": ["de", "gb"],
"events": [{"token": "abcdef","name": "Login"}, {"token": "badcfe","name": "Level Up"}],
"grouping": ["trackers", "weeks", "events"],
"trackers": [
{
"token": "foobar",
"name": "Network 1",
"has_subtrackers": true
}
]
},
"result_set": {
"token": "2eb2na2w54c3",
"name": "app name",
"currency": "USD",
"trackers": [
{
"token": "foobar",
"dates": [
{
"date": "2015-05-02",
"events": [
{
"token": "abcdef",
"kpi_values": [4, 5, 0.8]
},
{
"token": "badcfe",
"kpi_values": [3, 5, 7.2]
}
]
},
{
"date": "2015-05-09",
"events": [
{
"token": "badcfe",
"kpi_values": [4, 5, 0.8]
}
]
}
]
}
]
}
}
请注意 result_parameters
中的 kpis
数组与 result_set
中的 kpi_values
数组之间是一一对应的关系。此响应中,“Login”事件记录了 5 次,revenue_per_event
的值为 0.8。
同期群查询
同期群查询支持您查询用户同期群的聚合数据(例如,用户完成安装、购买、注册等操作的日期)。通过同期群查询,您可以检索基于同期群的 KPI(例如,安装完成后第二天开始的留存率)。
建议根据同期群周期和 KPI 用户群命名同期群。周期说明了数据的细分程度,不仅可以展示每周同期群 (例如,某天、某周或某月安装应用的用户) 和根据此周期确定的 KPI (例如,安装完成后某天、某周或某月的留存率)。KPI 用户群确定了用户子集为全部用户,还是付费用户 (至少触发一次收入事件的用户),或是触发过一次任意事件的用户。
自 2019 年 5 月 1 日起,我们支持最长达 120 天和 52 周的同期群查询。月份数没有限制。您可以使用 cohort_period_filter 占位符为指定的一天、多天 (或两者) 或指定的一周或多周进行同期群查询。
要查询具体一天的数据 (例如安装后第 30 天),请使用格式 cohort_period_filter=30
要查询数天范围内的数据 (例如安装后 30 天期间),请使用格式 cohort_period_filter=0-30
要同时查询特定一天和具体时间范围内的数据 (例如安装后的头 30 天期间以及第 120 天),请使用格式 cohort_period_filter=0-30,120
要查询具体一周的数据 (例如安装后第 10 周),请使用格式 cohort_period_filter=10&period=week
要查询数周范围内的数据 (例如安装后头 10 周期间),请使用格式 cohort_period_filter=0-10&period=week
终端
GET /kpis/v1/:app_token/cohorts{.csv|.json}
GET /kpis/v1/:app_token/trackers/:tracker_token/cohorts{.csv|.json}
查询参数
此处给出了一个受支持的查询参数列表;还可参阅预期参数值详情。
参数名称 | 格式 | 描述 |
start_date | YYYY-MM-DD | 选定周期的开始日期 |
end_date | YYYY-MM-DD | 选定周期的结束日期 |
utc_offset | [+-]HH:MM,例如, utc_offset=-05:00 或 utc_offset=10:00 | 与UTC 0 时区的时差,例如:如果您希望查询的起止日期是以北京时间定义的,那么您在此可以设此参数为:utc_offset=08:00 |
kpis | 字符串,例如, revenue_events,revenue | 用逗号隔开的 应用 KPI列表。可以采用任意组合的应用 KPI。 |
sandbox | 字符串 true 或 false | 可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。 |
attribution_type | 字符串 click 、impression 或 all | 点击、展示或结合点击与展示。 |
attribution_source | 字符串, first 或 dynamic | 确定应用内活动是分配给用户的安装来源 ( first ),还是分配给安装来源和后续再归因来源 (dynamic )。默认情况下,设置为 dynamic 。 |
period | 从day /week /month 中任选一个 | 同期群周期 |
reattributed | 从true /false /all 中任选一个 | 确定是否基于再归因确定同期群( true 或 false )。默认值为 all ,包括再归因数量和安装量。可用数据起始日期:2016 年 10 月 1 日 |
events | 字符串,例如, abcdef,12345 | 用逗号隔开的事件识别码列表 |
countries | 字符串,例如, de,us | 用逗号隔开的国家/地区名称列表(采用 ISO 3166 alpha-2 代码) |
os_names | 字符串,例如, ios,android | 用逗号隔开的操作系统名称列表。在下面找到有效的操作系统名称。 |
device_types | 字符串,例如, phone,tablet | 用逗号隔开的设备类型列表。在下面找到有效的设备类型。 |
grouping | 字符串,例如, trackers,install_date | 为参数分组。有关分组的更多详细信息,请参见下文。 |
注意: period
查询参数所用的周期从安装完成后小时数开始计算,而并非按安装完成后的日历天计算。也就是说,如果用户在周三的 12:47 安装了应用,该用户的第 0 周将在下周三 (168个小时后) 的 12:47 结束,而第 0 月将在 30 天后 (720 小时后) 的 12:47 结束。
同期群 KPI
同期群 KPI | 描述 |
---|---|
retained_users | 周期内回归的用户数量 |
cohort_size | 安装后开始计时的第 N 个周期,至少在 N 个周期之前安装应用的用户数量 |
retention_rate | retained_users 除以 cohort_size |
sessions | 每个周期产生的会话数 |
sessions_per_user | 会话数除以 retained_users |
revenue | 每个周期产生的收入数额 |
revenue_total | 本周期和本周期之前的累计收入 |
revenue_events_total | 本周期和之前所有周期的累计 revenue_events 数量 |
revenue_per_user | revenue 除以 cohort_size |
revenue_per_paying_user | revenue 除以 paying_user_size |
revenue_total_in_cohort | 安装后开始计时的第 N 个周期,至少 N 个周期之前已安装应用的用户从第 0 个周期到第 N 个周期的累计收入 |
revenue_events_total_in_cohort | 安装后开始计时的第 N 个周期,至少在 N 个周期之前已安装应用的用户从第 0 到第 N 个周期的所有累计的 revenue_events 数量 |
lifetime_value | all_revenue_total_in_cohort 除以 cohort_size |
paying_user_lifetime_value | revenue_total_in_cohort 除以 paying_user_size |
time_spent | 周期内用户所花费的总时间(以秒计), |
time_spent_per_user | time_spent 除以 cohort_size |
time_spent_per_session | time_spent 除以 sessions * |
paying_users | 周期内的付费用户数量 |
paying_user_size | 安装后第 N 个周期,至少在 N 个周期之前已安装应用的付费用户数量 |
paying_users_retention_rate | paying_users 除以 retained_users |
paying_user_rate | paying_users 除以 cohort_size |
revenue_events | 每个周期的收入事件的数量 |
revenue_events_per_user | revenue_events 除以 cohort_size |
revenue_events_per_active_user | revenue_events 除以 retained_users |
revenue_events_per_paying_user | revenue_events 除以paying_users |
converted_users | 安装后的第 N 个周期,触发指定事件/总事件量的独立用户的数量一个用户可能贡献多个安装后天数。 |
converted_user_size | 安装后的第 N 个周期,至少在 N 个周期之前已安装应用的转化用户的数量 |
conversion_distribution | converted_users 除以 converted_user_size |
conversion_per_user | converted_users 除以cohort_size |
conversion_per_active_user | converted_users 除以 retained_users |
events | 周期内触发的事件量 |
events_per_converted_user | events 除以 converted_users |
events_per_user | events 除以 cohort_size |
events_per_active_user | events 除以 retained_users |
reattributions | 每个周期产生的再归因数 |
deattributions | 每个周期产生的离归因数(首次再归因) |
reattributions_per_user | reattributions 除以 cohort_size |
deattributions_per_user | deattributions / cohort_size |
reattributions_per_deattribution | reattributions 除以 deattributions |
uninstalls | 每个周期卸载的次数 |
uninstalls_total | 一段时间内累计卸载总数 |
reinstalls | 每个周期重装的次数 |
reinstalls_total | 一段时间内累计重装总数 |
first_uninstalls | 每个周期的首次卸载数 |
first_uninstalls_total | 一段时间内累计首次卸载总数 |
first_reinstalls | 每个周期的首次重装数 |
first_uninstalls_total | 一段时间内累计首次重装总数 |
gdpr_forgets | 每个周期希望被遗忘的用户数 |
gdpr_forgets_total | 一段时间内希望被遗忘的累计用户总数 |
注意: 仅在选择 attribution_source=first
时,与离归因和再归因相关的同期群 KPI 值才有意义。选择 attribution_source = dynamic
时,这些事件将仅在第一个 (0) 周期,即归因周期中显示。
广告收入同期群 KPI
广告收入同期群 KPI | 描述 |
---|---|
ad_revenue | 每个周期产生的 ad_revenue |
ad_revenue_total | 本周期和所有之前周期的累计ad_revenue |
ad_revenue_total_in_cohort | 安装后开始计时的第 N 个周期;也就是至少 N 个周期之前已安装应用的用户,他们从第 0 个周期到第 N 个周期的累计ad_revenue |
ad_impressions | 每个周期产生的ad_impressions 数量 |
ad_impressions_total | 本周期和所有之前周期的累计ad_impressions |
ad_impressions_total_in_cohort | 安装后开始计时的第 N 个周期;也就是至少 N 个周期之前已安装应用的用户,他们从第 0 个周期到第 N 个周期的累计ad_impressions |
all_revenue | ad_revenue + revenue |
all_revenue_total | ad_revenue_total + revenue_total |
all_revenue_per_user | all_revenue 除以 cohort_size |
all_revenue_total_in_cohort | ad_revenue_total_in_cohort + revenue_total_in_cohort |
ad_rpm | 每千次ad_impressions 期间的 ad_revenue ,即 ad_revenue / ad_impressions * 1000 |
示例
请求:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/cohorts?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions&grouping=trackers,periods&period=week
响应:
{
"result_parameters": {
"kpis": ["sessions"],
"start_date": "2015-05-01",
"end_date": "2015-05-31",
"sandbox": false,
"grouping": ["trackers", "periods"],
"trackers": [
{
"token": "foobar",
"name": "Network 1",
"has_subtrackers": true
}
],
"period": "week"
},
"result_set": {
"token": "{your_user_token}",
"name": "app name",
"currency": "USD",
"trackers": [
{
"token": "foobar",
"periods": [
{
"period": "0",
"kpi_values": [4]
},
{
"period": "1",
"kpi_values": [5]
}
]
}
]
}
}
同理,请注意 kpis
和 kpi_values
之间的对应关系。
查询参数
本节对上述各个 API 请求参数进行了更为详细的说明。应注意的是,API 会对其可能发现的错误进行描述性说明,解析请求参数。无效的请求将收到 HTTP 400
这样的错误提示信息,并在信息正文中详细说明该问题。
时间周期
以 YYYY-MM-DD
格式指定事件筛选范围的 start_date
和 end_date
。如果没有指定这样的时间范围,则默认为当前月份。
时区
使用 utc_offset
查询参数确定 UTC 相对时区。例如:如果您想知道太平洋时间 (PT) 2016 年 2 月 14 日产生了多少次安装,则应在查询中输入 start_date=2016-02-14&end_date=2016-02-14&utc_offset=-08:00
。格式为 utc_offset=[+-]HH:MM
,例如 utc_offset=+04:00
。+
是默认的偏离方向,可以省略。但是,必须确保始终包含 -
。
注意: 如果未添加utc_offset
,则使用UTC时区。
已再归因
您可以使用 reattributed
查询参数只筛选再归因用户的 KPI。当一名用户已经安装您的应用,但是又通过由 Adjust 跟踪的新来源返回到应用,就会被再归因。
注意: 此查询只能提取 2017 年 9 月 1 日以后的数据。
将此筛选条件与 WAU
和 MAU
KPI 一起使用时,应牢记以下注意事项:
同一个用户不能既是已安装用户又是再归因用户。
- 也就是说,如果用户在 6 月 1 日(星期一)安装,在 6 月 3 日(星期三)再归因,则该用户在 6 月 7 日(星期日)之前仍为已安装的 WAU 用户,并且只有在 6 月 8 日(星期一)和 6 月 9 日(星期二)才能成为再归因的 WAU 用户
- 如果该用户在 6 月 9 日触发了新的应用会话,则又变成再归因的 WAU 用户(保持 7 天)
- 也就是说,如果用户在 6 月 1 日(星期一)安装,在 6 月 3 日(星期三)再归因,则该用户在 6 月 7 日(星期日)之前仍为已安装的 WAU 用户,并且只有在 6 月 8 日(星期一)和 6 月 9 日(星期二)才能成为再归因的 WAU 用户
这一逻辑也适用于 MAU,只是时间周期变成以月计算
KPI
kpis
指用逗号隔开的已请求 KPI 列表,该列表可能会因资源的不同而出现差异。如果没有指定参数,则使用默认列表。应注意的是,result_set
响应也会返回一个 kpis
数组。
国家/地区
countries
指用逗号隔开的两字符 ISO 3166-1 alpha-2 国家/地区代码列表。如果没有指定 country
筛选条件,则默认使用所有国家/地区。
操作系统名称
有效 os_name
值列表
android
bada
blackberry
ios
linux
macos
server
symbian
unknown
webos
windows
windows-phone
设备类型
device_types
的有效值列表:
bot
console
ipod
mac
pc
phone
server
simulator
tablet
unknown
人类可读 KPI
human_readable_kpis
是一个经证明对很多客户都很实用的功能,在处理 CSV 中的数据时特别有用。将 GET 参数 human_readable_kpis=true
附加到任何请求 URL 就可以将产生的 KPI、周期等标题转化成格式化的英语。例如:您会得出 Lifetime Value
,而不是 lifetime_value
。此外,假设在同期群查询里选择的周期为 week
,则响应字段会显示 Weeks after Install
,而不是 period
。
这样便于将 CSV API 调用的结果作为报告共享,而无需重命名列或标题。同时,借此,我们还可以实现数据自动 API 访问和程序化解析的一致性命名。
捆绑隐私声明
grouping
指数据集的分组。结果数据将按照指定的确切顺序嵌套。例如:grouping=trackers,countries
将按国家/地区针对各跟踪链接嵌套,而 grouping=countries,trackers
将以相反的方向嵌套。为了获得更好的体验,我们鼓励您使用分组参数。
以下是 grouping
请求参数的所有可接受值的完整列表。
与跟踪链接有关的分组
跟踪链接分组可以根据跟踪链接树用跟踪链接分解数据。让我们来看一些示例:
- 如果您未指定父级跟踪链接和
grouping=trackers
,则会按您的应用的所有渠道跟踪链接对您的数据进行分组。 - 如果您未指定父级跟踪链接和
grouping=campaigns
,则会按您的应用的所有推广活动跟踪链接对您的数据进行分组。 - 如果您指定了推广活动父级跟踪链接和
grouping=trackers
或grouping=adgroups
,则会按指定的推广活动父级跟踪链接扩展得出的所有广告组跟踪链接对您的数据进行分组。 - 如果您指定了推广活动父级跟踪链接和
grouping=creatives
,则会按指定的推广活动父级跟踪链接扩展得出的所有素材推广链接对您的数据进行分组。
可接受值的完整列表:
trackers
:将根据指定的tracker_token
(可选),按渠道/推广活动/广告组/素材进行分组。要了解更多关于跟踪链接分组的信息,请参阅跟踪链接树的章节内容。networks
:将按渠道分组,而不用考虑指定的tracker_token
(可选)。结果集将包含一个存有已找到渠道数组的渠道字段。campaigns
:将按渠道分组,而不用考虑指定的tracker_token
(可选)。结果集将包含一个存有已找到推广活动数组的推广活动字段。adgroups
:将按渠道分组,而不用考虑指定的tracker_token
(可选)。结果集将包含一个存有已找到广告组数组的广告组字段。creatives
:将按渠道分组,而不用考虑指定的tracker_token
(可选)。结果集将包含一个存有已找到素材数组的素材字段。
时间周期分组
hour
:将按小时分组。结果集将包含一个存有本周期适用小时数数组的dates
字段,对应的date
字段将显示小时数。day
:将按天分组。结果集将包含一个存有本周期适用天数数组的dates
字段,对应的date
字段将显示天数。week
:将按周分组。结果集将包含一个存有本周期适用周数数组的dates
字段,对应的date
字段将显示该周的开始日期。month
:将按月分组。结果集将包含一个存有本周期适用月数数组的dates
字段,对应的date
字段将显示该月的开始日期。
注意: 使用较长的日期(周或月)分组时,建议日期选项包含完整周期。第一个数据将四舍五入为周或月的开始日期。如果在周或月过半时才开始选择日期,则该组数据与结果集中的其他组数据相比可能并不那么准确。
进一步分组选项
countries
:将按国家/地区分组。结果集将包含一个存有已找到国家/地区数组的countries
字段,对应的country
字段将显示两个字符(ISO 3166-1 alpha-22)的国家/地区代码。如果要了解国家/地区代码的完整列表,请参阅下表。region
:将按业务地区(即,APAC、EMEA 和 LATAM)分组。结果集将包含一个存有已找到地区数组的region
字段,对应的region
字段将显示地区首字母缩写。如果要了解所属国家/地区的完整列表,请点击此处。device_types
:将按设备类型分组。结果集将包含一个存有已找到 device_types 数组的device_types
字段,对应的device_type
字段将显示上述device_types
章节的列表中所列的设备类型。os_names
:将按操作系统名称分组。结果集将包含一个存有已找到 os_names 数组的os_names
字段,对应的os_names
字段将显示设备的操作系统名称。partners
:将按合作伙伴的姓名分组。结果集将包含一个存有已找到合作伙伴数组的partners
字段,对应的partner
字段将显示数据所属的合作伙伴。
跟踪链接树
如前所述,可以通过指定(或不指定)跟踪码请求所有终端。对于上述每个资源,都指定了两个终端,其中第二个表格指定了一个跟踪链接。如果使用第二个表格,则将根据提供的跟踪链接来筛选结果集,并且 trackers
分组将按子跟踪链接将结果集分段。
如果没有指定跟踪码,则会返回各个渠道的数据,并且 trackers
分组将按渠道层跟踪链接将结果集作为 trackers
数组中的条目进行分段。
通过 trackers
分组,结果集将包含各跟踪链接的元数据。该元数据包括一个 has_subtrackers
布尔字段,这表明您也可以查询指定的识别码来更深入地遍历树。
例如:如果用推广活动父级跟踪链接来请求查询,则响应会包含按各广告组子跟踪链接分组的数据。
跟踪链接筛选
跟踪链接筛选对处理复杂的跟踪链接设置十分有用。通过您的任一 KPI 服务查询获取 tracker_filter
查询参数,您可以将结果集集中到特定跟踪链接的数据。此操作与 API 提供的 Grouping 选项相结合,创建了一个强大的工具。它不仅可以深入分析数据,还可以保持对指定渠道、推广活动或广告组的关注。
例如:您的 Adjust 跟踪链接设置的渠道跟踪码是 x2yiy3
和 vi4wwc
。您可以使用查询参数将结果集细化为仅包含属于或来自于这两个渠道的数据:
&tracker_filter=x2yiy3,vi4wwc&grouping=network,campaign,adgroup,creative
请注意,grouping
参数为可选参数。事实上,grouping
(或根本就没有) 可以针对您的搜索目标给出有意义的结果。
此外,跟踪链接筛选可以与多应用总览终端一起使用,例如:
GET https://api.adjust.com/kpis/v1?app_tokens=44cdcdck2syc,9xmtsnp687ek&tracker_filter=q9y2y2,xi2wxq,x2yiy3,vi4wwc&grouping=app,network,campaign,adgroup,creative
例如:通过这种方式,可以比较多个应用的同一个渠道在单次 API 调用中的表现。
多应用总览终端
到目前为止讨论的终端只请求单个应用的数据。这些数据对于单个应用的完整分解是必不可少的,但不会提供多个(甚至所有)应用的概览。在此讨论的多应用终端可以提供完整的概览。
终端 URL
可以调用的终端可交付成果有两种不同的类别:
GET https://api.adjust.com/kpis/v1{.csv|.json}?app_tokens=44cdcdck2syc,9xmtsnp687ek
GET https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek{.csv|.json}?
这两种终端都将返回同样的结果。
对于同期群,可能需要使用以下终端:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts{.csv|.json}?
请注意,所有其他终端也同理,.csv
或 .json
扩展并非强制性的。默认的响应格式依然是 JSON,但是如果要改为 CSV,仅需附加 .csv
扩展名。
参数名称 | 格式 | 描述 |
---|---|---|
start_date | YYYY-MM-DD | 选定周期的开始日期。 |
end_date | YYYY-MM-DD | 选定周期的结束日期。 |
utc_offset | [+-]HH:MM,例如, utc_offset=-05:00 或 utc_offset=10:00 | 与UTC 0 时区的时差,例如:如果您希望查询的起止日期是以北京时间定义的,那么您在此可以设此参数为:utc_offset=08:00 |
kpis | 字符串,例如,clicks,installs,maus | 用逗号隔开的 应用 KPI列表。可以采用任意组合的应用 KPI。 |
sandbox | 字符串 true 或 false | 可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。 |
impression_based (已弃用) | 字符串 true 或 false |
已弃用,请换用 |
countries | 字符串,例如,de,us | 用逗号隔开的国家/地区名称列表(采用 ISO 3166 alpha-2 代码) |
os_names | 字符串,例如,ios,android | 用逗号隔开的操作系统名称列表。套用 OS names 列表。 |
device_types | 字符串,例如,phone,tablet | 用逗号隔开的设备类型列表。套用 Device Types 列表。 |
grouping | 字符串,例如,apps,countries | 为参数分组。有关分组的更多详细信息,请参见下文。 |
human_readable_kpis | 布尔 | 采用英语格式打印标题(例如,遵循正确的大写规则)。 |
应用 KPI
值得重申的是,对于此终端的 kpis
参数,可以使用先前讨论的应用 KPI 集。以下为有效的 URL 示例:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions
对于您的同期群:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts?kpis=converted_users,sessions
此操作会分解两个已请求应用(即,两个应用识别码)在默认周期间的安装和会话数据。
多应用分组
默认情况下,会按单个应用对此终端进行分组。但是,也可以按跟踪链接、周期或跟踪链接和周期的任何组合进行分组。特别值得一提的是,此种情况也可以参阅分组章节的纲要。
单个应用的时间序列数据
关于如何获取这两个应用的安装和会话的时间序列数据,请看以下示例:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,days
所有应用的时间序列数据
此时,可以忽略分组中的 apps
,仅根据 days
聚合。这是快速查看整个应用配置文件的好方法。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=days
该请求的响应示例为:
日期 | 安装 | sessions |
2015-12-01 | 2093 | 11703 |
2015-12-02 | 1124 | 11211 |
2015-12-03 | 5651 | 5687 |
请注意,这是表格响应版本(即,以 CSV 格式输出)。
应用和渠道跟踪链接分解
接下来,可以为这两个应用分别请求安装和会话数据,并通过渠道跟踪链接进行聚合。此操作对比较应用配置文件中不同渠道的表现十分有用。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,networks
同样,响应此请求的表格格式输出示例为:
app_token | app_name | tracker_token | 渠道 | 安装 | sessions |
---|---|---|---|---|---|
44cdcdck2syc | 首个应用 | 5aml2f | 广告渠道 | 40 | 80 |
44cdcdck2syc | 首个应用 | 28kse9 | 电子邮件广告 | 192 | 292 |
9xmtsnp687ek | 我的其他应用 | 16px8z | 另一个渠道 | 2001 | 3001 |
9xmtsnp687ek | 我的其他应用 | 21h2o9 | 电子邮件广告 | 17 | 37 |
KPI 服务术语表
我们可以提供 KPI 的完整列表,在 KPI 服务术语表中,您可以查看它们的定义以及它们的计算方式。