Adjust KPI通过对Adjust的拉式API,对我们所跟踪的移动应用以编程的方式请求数据。以下是RESTful JSON API的说明文档。

可发送至API的查询类型包括三种:总览事件同期群。这三种类型已经覆盖了Adjust控制面板的大部分数据,并支持您直接拉取相关KPI。

任意查询类型既可用于应用的所有渠道跟踪链接,也可用于指定父跟踪链接。 因此,每个来源均有两个端点:一个不带跟踪码,默认分组数据到所有渠道跟踪链接;另一个支持您指定跟踪码,从而对具体的子跟踪链接请求数据。

在详细了解API规范之前,建议您首先查看我们所开发的R client以帮助您实施API。如果您是R用户,那么您一定会喜欢该客户端将Adjust数据带入到R会话的简捷方式。

由于熟悉跟踪链接对于处理API具有重要意义,我们还建议您再次回顾跟踪链接相关术语。请特别留意跟踪链接结构中渠道、推广、广告组和素材层级的相关概念。

注意: KPI服务仅向Business Pro及以上套餐客户开放。您可以通过控制面板中的套餐计划查看您当前使用套餐级别。

注意:下文示例均使用最小长度的跟踪码。在实际应用中,请始终使用Adjust Campaign Wizard中显示的完整跟踪码。

1版本控制

为避免混淆,API版本会被明确写入所有端点的URL路径中。例如,版本1的URL路径为http://api.adjust.com/kpis/v1/..

2响应格式

API支持两种响应格式 - CSV和JSON,其中默认格式为JSON。如需指定其他格式,您可以通过对端点添加后缀(如在端点路径末尾添加.csv)的方式,或者发送带有Accept: text/csvHTTP标题的请求。本文档中请求和响应示例将主要使用JSON格式。

3验证

您对KPI服务的访问权限与Adjust用户账户相捆绑。每个用户账户对应一个关联用户识别码(user token),您可以通过该识别码独立控制对KPI的访问权限。

用户识别码可在控制面板的 “账号设置 > Your Data” 中找到,该识别码将用于下文的身份验证。

用户识别码和控制面板用户权限一致,也就是说如果您设置了自定义用户权限,用户对控制面板的访问权限将同样适用于其对KPI服务的访问。

您可以随时更新用户识别码。

采用用户识别码来验证API的方式有两种,您可以根据具体用例自由选择验证方式:

  • HTTP GET参数 - 添加user_token=your_user_token到任何API查询。
  • HTTP 验证标题 - 添加以下HTTP标题:
    `Authorization: Token token=your_user_token`
    

本文档中所有示例均假定使用HTTP标题验证方式,但您也可以对示例添加带有正确识别码的GET参数,验证同样有效。

4应用识别码和跟踪码

需特别强调的是,在实际应用中所有端点中的:app_token:tracker_token 都必须使用真实的识别码值,以获取有效的请求URL。如以下示例:

https://api.adjust.com/kpis/v1/2eb2na2w54c3/trackers/15jvui

仅是对应用识别码2eb2na2w54c3和跟踪码15jvui有效的URL。本文档中所有示例使用的应用识别码均是2eb2na2w54c3,您只需将其替换为自己的真实应用识别码即可。

5总览查询

总览查询提供应用KPI以及事件KPI的数据。您通常感兴趣的指标包括给定时间段所有应用投放渠道或指定父跟踪链接的点击会话安装等等。您还可以请求自定义Adjust事件的KPI,如收入首个事件等。此外还包括国家、平台、设备等范围指标。

5.1端点

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}

5.2查询参数

以下为所支持的查询参数列表;您还可参阅关于预期参数值的详细信息

参数名称 格式 说明
start_date YYYY-MM-DD 所选期间的起始日
end_date YYYY-MM-DD 所选期间的结束日
utc_offset [+-]HH:MM, 例如utc_offset=-05:00utc_offset=10:00 UTC时区偏移量
kpis 字符串,例如clicks,installs,maus 由逗号分隔的应用KPI列表。任何应用KPI组合均可被接受。
event_kpis 字符串,例如 token1_events,token1_revenue_per_user 由逗号分隔的事件KPI列表。每个KPI将带有事件识别码或all前缀。参见下文示例。
reattributed 字符串,例如truefalseall 按仅安装、仅再归因用户或所有用户(默认)筛选KPI。
sandbox 字符串 truefalse 请求沙箱或者生产数据。默认为生产数据。
impression_based 字符串 truefalse 请求基于点击或者展示的数据。默认为基于点击。
attribution_type 字符串 clickimpressionall 点击、展示或点击及展示(将改写impression_based参数)。
attribution_source 字符串 firstdynamic 应用内活动是仅归因到用户的安装来源(first),或分配给安装和后续再归因来源(dynamic)。默认设置为dynamic
countries 字符串,例如de,us 由逗号分隔的ISO 3166 alpha-2国家名称列表。
os_names 字符串,例如 ios,android 由逗号分隔的操作系统名称列表。您可在下文找到有效的操作系统名称。
device_types 字符串,例如phone,tablet 由逗号分隔的设备类型列表。您可在下文找到有效的设备类型。
grouping 字符串,例如 trackers,countries 分组参数。参见下文了解更多关于分组的详细信息。

5.3应用KPI

以下为所支持的应用KPI列表 - 您可以将这些值传递到kpis参数。

应用KPI 说明
clicks 点击数量
impressions 展示数量
installs 安装数量
uninstalls 卸载数量
uninstall_cohort 设定周期内安装用户的卸载数量
reinstalls 重装数量
click_conversion_rate 点击转化率,由clicks加权的installs/clicks平均值。
ctr 展示点击率,计算方法为clicks/impressions
impression_conversion_rate 展示转化率,由impressions加权的installs/impressions平均值。
reattributions 再归因数量
reattribution_reinstalls 被再归因的重装数量
deattributions 离归因数量
sessions 会话数量
revenue_events 收入事件数量
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控制面板中。

5.4防作弊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_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/(installs + rejected_installs)
rejected_install_anon_ip_rate 因匿名IP造成被拒安装的比率,即rejected_installs_anon_ip/(installs + rejected_installs)
rejected_install_too_many_engagements_rate 因过分频繁交互造成被拒安装的比率,即rejected_installs_too_many_engagements/(installs + rejected_installs)
rejected_install_distribution_outlier_rate 因分布异常造成被拒安装的比率,即rejected_installs_distribution_outlier/(installs + rejected_installs)
rejected_install_click_injection_rate 因点击劫持造成被拒安装的比率,即rejected_installs_click_injection/(installs + rejected_installs)
rejected_reattribution_rate 被拒再归因的比率,即rejected_reattributions/(reattributions + rejected_reattributions)
rejected_reattribution_anon_ip_rate 因匿名IP造成被拒再归因的比率,即rejected_reattributions_anon_ip/(reattributions + rejected_reattributions)
rejected_reattribution_too_many_engagements_rate 因过分频繁交互造成被拒再归因的比率,即rejected_reattributions_too_many_engagements/(reattributions + rejected_reattributions)
rejected_reattribution_distribution_outlier_rate 因分布异常造成被拒再归因的比率,即rejected_reattributions_distribution_outlier/(reattributions + rejected_reattributions)
rejected_reattribution_click_injection_rate 因点击劫持造成被拒再归因的比率,即rejected_reattributions_click_injection/(reattributions + rejected_reattributions)。

5.5成本KPI

成本KPI仅向已启用成本数据的账户开放。

成本KPI 说明
install_cost 安装成本
click_cost 点击成本
impression_cost 展示成本
cost click_cost + impression_cost + install_cost的总和
paid_installs 带成本数据的安装数量
paid_clicks 带成本数据的点击数量
paid_impressions 带成本数据的展示数量
ecpc 单次点击的有效成本,即cost / paid_clicks
ecpm 每千次展示的有效成本,即cost / paid_impressions * 1000
ecpi 单次安装的有效成本,即cost / paid_installs
cohort_gross_profit 总利润, 即cohort_revenue - cost
return_on_investment 投资回报率,即cohort_gross_profit / cost
revenue_to_cost 收入成本比率,即cohort_revenue/cost

请注意:成本数据显示到毫分,例如5.45661欧元将显示成本=545661。

5.6事件KPI

以下为所支持的事件KPI列表,加上event_token前缀后,您可以将这些值传递到Overview查询请求的event_kpis参数。这些事件KPI还可用于事件章节所提及的Events请求。

事件KPI 说明
revenue_events 收入事件的数量
revenue 以应用报告币种显示的总收入
events 事件数量
first_events 用户首次触发事件的数量。first_eventsevents的关系类似于installs对应sessions的关系。
revenue_per_event 总收入除以事件数量
revenue_per_revenue_event 总收入除以收入事件数量

5.7简化对事件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可用于扩展到全部已定义的事件。例如,如果您有两个事件,识别码分别为token1token2,以下字符串:

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

请注意,后两种格式之间的区别在于如何对指标进行排序。详细介绍请参见下文。

5.8示例

仅请求应用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数组之间一对一的对应关系。例如,在该响应中的跟踪链接Network 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", "token2_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数组之间一对一的对应关系。因此,上文响应中的跟踪链接Network 1有221次点击,100次带有识别码token1的事件发生,以及来自这些事件的收入为299.30。

5.9KPI排序

请注意,您请求kpis和/或event_kpis的顺序决定了所收到响应的顺序 。上文最后一个示例说明了这一点。

KPI排序在您请求API的csv数据时将特别有用。在这种情况下,响应列会准确匹配您请求KPI的方式。

6事件查询

下文将向您介绍如何查询事件KPI。如果您希望按照事件分组数据,这些端点将对您非常有帮助。

6.1端点

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}

6.2查询参数

以下为所支持的查询参数列表;您还可参阅关于预期参数值的详细信息

参数名称 格式 说明
start_date YYYY-MM-DD 所选期间的起始日
end_date YYYY-MM-DD 所选期间的结束日
utc_offset [+-]HH:MM,例如utc_offset=-05:00utc_offset=10:00 UTC时区偏移量
kpis 字符串,例如revenue_events,revenue 由逗号分隔的事件KPI列表。任意事件KPI组合均可被接受。
sandbox 字符串 truefalse 请求沙箱或者生产数据。默认为生产数据。
events 字符串,例如event_token1,event_token2 由逗号分隔的事件识别码列表。您可在Adjust控制面板中找到对应事件的事件识别码。
attribution_type 字符串 clickimpressionall 点击、展示或点击及展示(将改写impression_based参数)。
attribution_source 字符串 firstdynamic 应用内活动是仅归因到用户的安装来源(first),或分配给安装和后续再归因来源(dynamic)。默认为dynamic
countries 字符串,例如de,us 由逗号分隔的ISO 3166 alpha-2国家名称列表。
os_names 字符串,例如 ios,android 由逗号分隔的操作系统名称列表,您可在下文找到有效的操作系统名称。
device_types 字符串,例如phone,tablet 由逗号分隔的设备类型列表,您可在下文找到有效的设备类型。
grouping 字符串,例如 trackers,countries 分组参数。请参见下文了解更多关于分组的详细信息。

6.3事件KPI

事件KPI列表与上文相同。但是,请注意不同于总览查询,在事件查询中,您无需对事件KPI加上事件识别码前缀。如果您希望获取特定事件的数据,可使用events参数来指定事件识别码。

6.4示例

请求:

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。

7同期群查询

同期群查询支持您按照用户同期群查询汇总数据,例如:按照用户安装应用、 购买、注册等事件所发生的日期查询汇总数据。这将有助于检索基于同期群的KPI,例如安装后每天的留存率。请参阅我们的同期群分析指南了解详细信息。

同期群查询应按同期群期间和KPI群来定义。同期群期间代表数据的细分程度,例如每周同期群(如在指定日、周或月的安装用户)和基于该期间的KPI(如安装后日、周或月期间的用户留存率)。KPI群在所有用户、付费用户(至少触发过一次收入事件的用户)和已触发任意事件用户中定义用户子集。

7.1端点

GET /kpis/v1/:app_token/cohorts{.csv|.json}
GET /kpis/v1/:app_token/trackers/:tracker_token/cohorts{.csv|.json}

7.2查询参数:

所支持的查询参数列表如下;您也可参阅关于预期参数值的详细信息

参数名称 格式 说明
start_date YYYY-MM-DD 所选期间的起始日
end_date YYYY-MM-DD 所选期间的结束日
utc_offset [+-]HH:MM,例如utc_offset=-05:00utc_offset=10:00 UTC时区偏移量
kpis 字符串,例如revenue_events,revenue 由逗号分隔的应用KPI列表。任意应用KPI组合均可被接受。
sandbox 字符串 truefalse 请求沙箱或者生产数据。默认为生产数据。
attribution_type 字符串 clickimpressionall 点击、展示或点击及展示(将改写impression_based参数)。
attribution_source 字符串 firstdynamic 决定应用内活动是仅归因到用户的安装来源(first),或分配给安装和后续再归因来源(dynamic)。默认为dynamic
period day/week/month其中之一 同期群期间
reattributed true/false/all其中之一 决定同期群是否来自再归因用户(truefalse)。默认值为all,包括再归因和安装用户。数据自2016年10月1日起可用。
events 字符串,例如abcdef,12345 由逗号分隔的事件识别码列表。
countries 字符串,例如de,us 由逗号分隔的ISO 3166 alpha-2国家名称列表。
os_names 字符串,例如 ios,android 由逗号分隔的操作系统名称列表。您可在下文找到有效的操作系统名称。
device_types 字符串,例如phone,tablet 由逗号分隔的设备类型列表。您可在下文找到有效的设备类型。
grouping 字符串,例如 trackers,countries 分组参数。请参见下文了解更多关于分组的详细信息。

注意: period查询参数所使用的期间是以安装后的小时数来计算的,而不是日历天数。例如,用户于星期三12:47安装了应用,则该用户的第0周将于下一个星期三12:47(168小时后)结束,第0月将于30天后12:47(720小时后)结束。

7.3同期群KPI

同期群KPI 说明
retained_users 指定期间内留存用户的数量
cohort_size 在安装后第N个期间,至少安装了N个期间的用户数量
retention_rate retained_users 除以 cohort_size
reattributions 每个期间的再归因用户数量
deattributions 每个期间的离归因用户数量(即从安装跟踪链接被再归因的用户数量)
sessions 每个期间生成的会话数量
sessions_per_user 会话数量除以 retained_users
uninstalls 每个期间的卸载数量
uninstalls_total 所有期间的卸载总数
reinstalls 每个期间的重装数量
reinstalls_total 所有期间的重装总数
revenue 每个期间的收入金额
revenue_total 当前期间和所有先前期间产生的收入总额
revenue_per_user revenue 除以 cohort_size
revenue_per_paying_user revenue 除以 paying_user_size
revenue_total_in_cohort 在安装后第N个期间,至少安装了N个期间的用户所带来的所有期间(从0到N期间)收入总额
lifetime_value revenue_total_in_cohort 除以 cohort_size
paying_user_lifetime_value revenue_total_in_cohort 除以 paying_users_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_total_in_cohort 当前和所有先前期间的累计收入事件
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 除以 retention_rate

*在计算第0天、0周或0月的同期群时,请确保已减去所有安装会话。

7.4示例

请求:

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]
          }
        ]
      }
    ]
  }
}

再次提醒,请注意kpiskpi_values之间的对应关系。

8查询参数

本章节将向您详细说明上文所提及的API请求参数。请注意,API将反馈可能发现的错误,并解析请求参数。无效的请求将收到HTTP 400出错响应,详细说明请参见下文。

8.1期间

start_dateend_dateYYYY-MM-DD格式指定日期范围。若未指定日期范围,默认 期间为当月。

8.2时区

utc_offset用于指定相对于UTC时区的偏移量。例如,您希望查看2016年2月14日在太平洋时区(PT)所发生的安装数量,请添加start_date=2016-02-14&end_date=2016-02-14&utc_offset=-08:00到您的查询。

如未提供相关信息,则使用账户的默认时区。

时区格式为utc_offset=[+-]HH:MM,如utc_offset=+04:00。由于+是默认的偏移方向,可以被省略。但-必须始终包含在参数中。

8.3再归因

通过reattributed查询参数,您可以筛选出仅与再归因用户相关的KPI指标。再归因是指已安装用户通过新的Adjust跟踪来源重新回到应用。

注意: 此查询只能提取2017年9月1日及以后的数据。

当您将该筛选参数与WAUMAUKPI结合使用时,需要注意以下几点:

  • 一个用户不能同时既是安装用户又是再归因用户
    • 这意味着,如果用户在6月1日(周一)安装了应用,并于6月3日(周三)被再归因,该用户将截止到6月7日(周天)保持为安装的周活跃用户(WAU),并仅于6月8日(周一)和6月9日(周二)两天归属为再归因WAU。
      • 如果该用户在6月9日之后触发了新的应用会话,他们将再次被认定为再归因WAU(之后7天)。
  • 同样的逻辑适用于MAU,只是以月为周期。

8.4KPI

kpis指定了请求KPI列表,这些KPI由逗号分隔并可能因来源不同而异。如果未指定参数,则将使用默认列表。请注意result_set响应也会返回kpis数组。

8.5国家

countries指定了两个字符的ISO 3166-1 alpha-2 国家代码,代码由逗号分隔。若未指定country,则默认为所有国家。

8.6操作系统名称

os_names有效值列表如下:

android
bada
blackberry
ios
linux
macos
server
symbian
unknown
webos
windows
windows-phone

8.7设备类型

device_types有效值列表如下:

bot
console
ipod
mac
pc
phone
server
simulator
tablet
unknown

8.8人工可读的KPI

human_readable_kpis是经实践证明对於许多客户相当实用的功能,尤其在处理CSV数据时。将GET参数human_readable_kpis=true添加到任意请求URL将会把生成的KPI、期间等标题翻译成适当格式的英文。例如,您会收到Lifetime Value而不是lifetime_value,此外,假设同期群查询的选定时间段为week,响应字段将显示Weeks after Install而不是period

这有助于在报告中共享CSV API调用的数据,而不必再重新命名栏目或标题。同时,我们也因此能够在自动化API访问和程序化数据解析时使用一致的名称。

9分组

grouping指定数据集的分组。所得到的数据将按照指定的确切顺序进行嵌套。 例如grouping=trackers,countries 将会为每个跟踪链接按国家嵌入数据,而grouping=countries,trackers则会以相反方式嵌套。建议您尝试使用不同分组参数组合,以找到最适合您的组合方式。

以下是适用于grouping请求参数的所有可接受值列表。

9.1跟踪链接分组

跟踪链接分组允许您基于跟踪链接对数据进行细分,从而与跟踪链接树结构相对应。示例如下:

  • 如果您未指定父跟踪链接和grouping=trackers,您的数据将按照应用的所有渠道跟踪链接进行分组。

  • 如果您未指定父跟踪链接和grouping=campaigns,您的数据将按照应用的所有推广跟踪链接进行分组。

  • 如果您指定了父推广跟踪链接和grouping=trackersgrouping=adgroups ,您的数据则会按照由指定的父推广链接派生的所有广告组跟踪链接进行分组。

  • 如果您指定了父推广跟踪链接和grouping=creatives,您的数据则会按照由指定的父推广链接派生的所有素材跟踪链接进行分组。

可接受值的完整列表如下:

  • trackers:根据指定的tracker_token 按照渠道/推广/广告组/素材进行分组。请参阅 跟踪链接树章节了解更多关于跟踪链接分组的内容。

  • networks:按照渠道进行分组,与可选择指定的tracker_token无关。结果集将包括一个networks字段,内含一系列所发现的渠道数组。

  • campaigns:按照推广进行分组,与可选择指定的tracker_token无关。结果集将包括一个campaigns字段,内含一系列所发现的推广数组。

  • adgroups:按照广告组进行分组,与可选择指定的tracker_token无关。结果集将包括一个adgroups字段,内含一系列所发现的广告组数组。

  • creatives:按照素材进行分组,与可选择指定的tracker_token无关。结果集将包括一个creatives字段,内含一系列所发现的素材数组。

9.2时间段分组

  • hour:按小时分组。结果集将包括一个dates字段,内含期间内适用的小时数组,对应的date字段代表具体小时。

  • day:按天分组。结果集将包括一个dates字段,内含期间内适用的天数组,对应的date字段代表具体天。

  • week:按周分组。结果集将包括一个dates字段,内含期间内适用的周数组,对应的date字段代表周的起始日。

  • month:按月分组。结果集将包括一个dates字段,内含期间内适用的月数组,对应的date字段代表月的第一天。

注意:在使用较长时间段(周或月)分组时,建议将整个时间段包括在您的日期选择中。 第一个date取整为周或月的起始日。若您选择在一周或月的中间日期开始, 此分组则无法与您结果集中的其他分组进行适当比较。

9.3其他分组选项

  • countries:按国家分组。结果集将包括一个countries字段,内含已发现国家的数组, 对应的country字段显示两字符(ISO 3166-1 alpha-2)的国家代码。完整国家代码列表请参见下文表格。

  • region: 按业务地区分组,如APAC、EMEA和LATAM,结果集将包括一个region字段,内含已发现地区的数组,对应region字段列出地区首字母缩写。请点击此处获取国家和所属地区的完整列表。

  • device_types:按设备类型分组。结果集将包括一个device_types字段,内含已发现设备类型的数组,对应的device_type字段指定上文device_types列表中所包含的设备类型。

  • os_names:按操作系统名称分组。结果集将包括一个os_names字段,内含已发现操作系统名称数组,对应的os_name字段显示设备的操作系统。

10跟踪链接树

如前所述,无论是否指定跟踪码,您均可对所有端点进行请求。上文示例使用了两种不同形式的端点,其中第二种形式指定了跟踪码。如果您选择使用第二种形式,结果集将按照您提供的跟踪链接进行过滤,trackers分组将按照子跟踪链接来细分您的结果集。

如果未指定跟踪码,则将返回每个渠道的数据,trackers分组将按照渠道层跟踪链接将结果集分组为trackers数组条目。

通过trackers分组,结果集将包含每个跟踪链接的元数据。此元数据包括一个 has_subtrackers布尔字段,代表您还可以指定具体跟踪码,从而进一步查询跟踪链接树深层结构数据。

例如,如果您通过父推广跟踪链接进行请求查询,响应将包含按照相应广告组子跟踪链接分组后的数据。

11跟踪链接过滤

跟踪链接过滤对处理结构复杂的跟踪链接十分有用。您可以在任何KPI服务查询中使用tracker_filter参数,以便集中分析特定的跟踪链接数据。结合API提供的分组选项,您将能够深入分析特定的渠道、推广或广告组的数据。

举例来说,Adjust跟踪链接设置生成了两个渠道跟踪码x2yiy3vi4wwc 。您可以使用以下查询参数来过滤结果集,使其仅包括或承自此两个渠道的数据:

&tracker_filter=x2yiy3,vi4wwc&grouping=network,campaign,adgroup,creative

请注意grouping是可选参数。实际上,任意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调用中跨应用比较同一渠道的推广表现。

12多应用总览端点

到目前为止,我们所讨论的都是对单个应用请求数据的端点。这虽然有助于全面分析单个应用,但却无法为您提供对多个(或所有)Adjust跟踪应用的数据总览。本章节所讨论的多应用总览端点使其成为可能。

12.1端点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:00utc_offset=10:00 UTC时区偏移量
kpis 字符串,例如 clicks,installs,maus 由逗号分隔的应用KPI列表。任意应用KPI组合均可被接受。
sandbox 字符串 truefalse 请求沙箱或者生产数据。默认为生产数据。
impression_based 字符串 truefalse 请求基于点击或者展示的数据。默认为基于点击。
countries 字符串,例如 de,us 由逗号分隔的ISO 3166 alpha-2国家名称列表。
os_names 字符串,例如 ios,android 由逗号分隔的操作系统名称。请参阅操作系统名称列表。
device_types 字符串,例如 phone,tablet 由逗号分隔的设备类型。请参阅设备类型列表。
grouping 字符串,例如 apps,countries 分组参数。请参见下文了解更多关于分组的详细信息。
human_readable_kpis 布尔 按照英语格式列出的标题(例如:适当的使用大写字母)

12.2应用KPI

对此端点kpis参数,您可以使用上文章节列出的应用KPI。以下为有效的URL示例:

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=install,sessions

以下为同期群示例:

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts?kpis=converted_users,sessions

该请求将返回这两个应用(对应以上两个应用识别码)在默认时间段内的安装及会话数据。

12.3多应用分组

默认情况下,端点分组是在单个应用的基础上进行的。但是您也可按照跟踪链接、期间或两者结合进行数据分组。此外,分组章节提及的相关内容也适用于此处。

单个应用的时间序列数据

如需为两个应用之一获取安装和会话的时间序列数据,请参见以下示例:

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

该请求的响应示例如下:

日期 安装数 会话数
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

以下是以表格形式返回的输出示例:

应用识别码 应用名称 跟踪码 渠道 安装数 会话数
44cdcdck2syc First App 5aml2f AdNetwork 40 80
44cdcdck2syc First App 28kse9 Email Ads 192 292
9xmtsnp687ek My Other App 16px8z AnotherNetwork 2001 3001
9xmtsnp687ek My Other App 21h2o9 Email Ads 17 37

13KPI服务词汇表

我们的KPI服务词汇表为您提供了完整KPI列表,及其详细说明和计算方法。