Adjust KPI 服务
Adjust KPI 服务是 Adjust 的拉式 API,您可以对其进行编程,针对您跟踪的移动应用发出数据请求。下文介绍了 RESTful JSON API 如何实现这一功能。

您可以向 API 发出三种查询:概览事件同期群。这些主要反映了 Adjust 控制面板中给定的部分,并且支持直接拉动相关 KPI。

查询可以是针对应用的所有渠道跟踪链接设置,也可以是针对给定父级跟踪链接。因此,每个资源都有两个终端:一端是没有跟踪码,默认为所有渠道跟踪链接进行数据分组,另一端则支持您指定跟踪码并细分到子跟踪链接组。

详细了解 API 内容前,建议快速查看为补充此 API 开发的 R 客户端。R 客户端可直接将 Adjust 数据导入 R 会话,如果您是 R 用户,定会喜欢这一简单易用的功能。

想要 API 数据具备价值,跟踪连接的概念至关重要,所以我们建议进行跟踪链接术语复习。特别注意渠道、推广活动、广告组和素材等不同部分的分层跟踪链接的概念。

注意:KPI 服务仅向 Business Pro 及以上等级套餐的客户提供。您可以查看控制面板中您当前的套餐。

注意: 以下页面包含使用最小长度跟踪码的示例。始终使用 Adjust 推广活动设置向导中显示的完整跟踪码。

版本控制

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/15jv

才是应用识别码 2eb2na2w54c3 和跟踪码 15jvui 的有效 URL。本文档中的所有示例都使用应用识别码 2eb2na2w54c3,您可以用自己的应用识别码轻松替换。

评价查询

评价查询可以提供应用 KPI事件 KPI 数据。通常,您会感兴趣的是给定时间段内应用运行的所有渠道和给定的父级跟踪链接的指标(例如 clickssessionsinstalls 等等)。您还可以为自定义 Adjust 事件(例如,revenuefirst_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_dateYYYY-MM-DD选定周期的开始日期。
end_dateYYYY-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字符串 true 或 false可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。
impression_based字符串 true 或 false请求可以作为基于点击或者基于展示的浏览量发出。默认情况下,假定基于点击。
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为参数分组。有关分组的更多详细信息,请参见下文。


应用 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总收入(按应用的报告币种计算)
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_revenuecohort_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/(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)


成本 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
roas广告支出回报率,ROA 指标由 cohort_ad_revenue / cost 计算得出
注意:成本精确到小数点后五位,即 5.45661 欧元会将成本记为 545661
 

事件 KPI

查看可以传递的支持事件 KPI 的列表,“概览”请求的 event_token 参数前添加 event_kpis 前缀。如事件部分所述,这些事件 KPI 也用于 Events 请求。
 
事件 KPI描述
revenue_events收入事件量
revenue总收入(按应用的报告币种计算)
events事件量
first_events用户首次触发的事件量。说到first_eventsevents 的过程,您自然会想到 installssessions 的过程!
revenue_per_event总收入除以事件量
revenue_per_revenue_event总收入除以收入事件量


促成事件 KPI 请求

本节内容仅供您计划通过“Overview”请求申请 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

请注意,最后两种格式的区别在于指标的顺序不同。如果要了解更多相关信息,请继续参阅下文。


示例

仅请求应用 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_dateYYYY-MM-DD选定周期的开始日期
end_dateYYYY-MM-DD选定周期的结束日期
utc_offset&[+-]HH:MM,例如,utc_offset=-05:00utc_offset=10:00时区的 UTC 偏离
kpis字符串,例如,revenue_events,revenue用逗号隔开的事件 KPI 列表。可以采用任意组合的事件 KPI。
sandbox字符串 truefalse可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。
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用逗号隔开的设备类型列表。在下面找到有效的设备类型。
partner_ids整数,例如:1234,789用逗号隔开的合作伙伴 ID 列表。将只显示属于这些合作伙伴的跟踪链接上的数据。
grouping字符串,例如,trackers,countries为参数分组。有关分组的更多详细信息,请参见下文。


事件 KPI

事件 KPI 列表同上。尽管如此,还需注意:您在执行 Overview 请求时,不用在事件 KPI 前面加上事件识别码,这一点与 Events 查询不同。如果需要特定事件的相关数据,请用事件参数替换事件识别码。


示例

请求:

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 数组之间是一一对应的关系。此响应中,“登录”事件记录了 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_dateYYYY-MM-DD选定周期的开始日期
end_dateYYYY-MM-DD选定周期的结束日期
utc_offset[+-]HH:MM,例如,utc_offset=-05:00utc_offset=10:00时区的 UTC 偏离
kpis字符串,例如,revenue_events,revenue用逗号隔开的应用 KPI 列表。可以采用任意组合的应用 KPI。
sandbox字符串 truefalse可以发出 sandbox 或真实流量请求。默认情况下,假定为真实流量请求。
attribution_type字符串 clickimpressionall点击、展示或结合点击与展示(此操作将覆盖 impression_based 参数)
attribution_source字符串, firstdynamic确定应用内活动是分配给用户的安装来源 (first),还是分配给安装来源和后续再归因来源 (dynamic)。默认情况下,设置为 dynamic
periodday/week/month 中任选一个同期群周期
reattributedtrue/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,install_date为参数分组。有关分组的更多详细信息,请参见下文。

注意:period 查询参数所用的周期从安装完成后小时数开始计算,而并非按安装完成后的日历天计算。也就是说,如果用户在周三的 12:47 安装了应用,该用户的第 0 周将在下周三(168个小时后)的 12:47 结束,而第 0 月将在 30 天后(720 小时后)的 12:47 结束。


同期群 KPI

同期群 KPI描述
retained_users周期内回归的用户数量
cohort_size安装后开始计时的第 N 个周期,至少在 N 个周期之前安装应用的用户数量
retention_rateretained_users 除以 cohort_size
reattributions每个周期再归因的用户数量
deattributions每个周期离归因(即,已从安装跟踪链接再归因)的用户数量
sessions每个周期产生的会话数
sessions_per_user会话数除以 retained_users
uninstalls每个周期卸载的次数
uninstalls_total所有周期卸载的次数
reinstalls每个周期重装的次数
reinstalls_total所有周期重装的次数
revenue每个周期产生的收入数额
revenue_total本周期和本周期之前的累计收入
revenue_per_user收入 除以 cohort_size
revenue_per_paying_user收入 除以 paying_user_size
revenue_total_in_cohort安装后开始计时的第 N 个周期,至少 N 个周期之前已安装应用的用户从第 0 个周期到第 N 个周期的累计收入
lifetime_valuerevenue_total_in_cohort 除以 cohort_size
paying_user_lifetime_valuerevenue_total_in_cohort 除以 paying_user_size
time_spent周期内用户所花费的总时间(以秒计),
time_spent_per_usertime_spent 除以 cohort_size
time_spent_per_sessiontime_spent 除以 sessions *
paying_users周期内的付费用户数量
paying_user_size安装后第 N 个周期,至少在 N 个周期之前已安装应用的付费用户数量
paying_users_retention_ratepaying_users 除以 retained_users
paying_user_ratepaying_users 除以 cohort_size
revenue_events每个周期的收入事件的数量
revenue_events_total_in_cohort安装后开始计时的第 N 个周期,至少在 N 个周期之前已安装应用的用户从第 0 到第 N 个周期的所有累计的 revenue_events 数量
revenue_events_per_userrevenue_events 除以 cohort_size
revenue_events_per_active_userrevenue_events 除以 retained_users
revenue_events_per_paying_userrevenue_events 除以paying_users
converted_users安装后的第 N 个周期,触发指定事件/总事件量的独立用户的数量一个用户可能贡献多个安装后天数。
converted_user_size安装后的第 N 个周期,至少在 N 个周期之前已安装应用的转化用户的数量
conversion_distributionconverted_users 除以 converted_user_size
conversion_per_userconverted_users 除以cohort_size
conversion_per_active_userconverted_users 除以 retained_users
events周期内触发的事件量
events_per_converted_userevents 除以 converted_users
events_per_userevents 除以 cohort_size
events_per_active_userevents 除以 retained_users
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_revenuead_revenue + revenue
all_revenue_totalad_revenue_total + revenue_total
all_revenue_per_user all_revenue 除以 cohort_size
all_revenue_total_in_cohortad_revenue_total_in_cohort + revenue_total_in_cohort
ad_rpm每千次 ad_impressions 期间的 ad_revenue,即 ad_revenue / ad_impressions * 1000

*对于第 0 天、第 0 周、第 0 月的同期群计算结果,应减去安装会话量


示例

请求:

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 之间的对应关系。


查询参数

本节对上述各个 API 请求参数进行了更为详细的说明。应注意的是,API 会对其可能发现的错误进行描述性说明,解析请求参数。无效的请求将收到 HTTP 400 这样的错误提示信息,并在信息正文中详细说明该问题。


时间周期

YYYY-MM-DD 格式指定事件筛选范围的 start_dateend_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+ 是默认的偏离方向,可以省略。必须确保始终包含 -


已再归因

您可以使用 reattributed 查询参数只筛选再归因用户的 KPI。当一名用户已经安装您的应用,但是又通过由 Adjust 跟踪的新来源返回到应用,就会被再归因。

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

将此筛选条件与 WAUMAU KPI 一起使用时,应牢记以下注意事项:
  • 同一个用户不能既是已安装用户又是再归因用户。
    • 也就是说,如果用户在 6 月 1 日(星期一)安装,在 6 月 3 日(星期三)再归因,则该用户在 6 月 7 日(星期日)之前仍为已安装的 WAU 用户,并且只有在 6 月 8 日(星期一)和 6 月 9 日(星期二)才能成为再归因的 WAU 用户
      • 如果该用户在 6 月 9 日触发了新的应用会话,则又变成再归因的 WAU 用户(保持 7 天)
  • 这一逻辑也适用于 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=trackersgrouping=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 跟踪链接设置的渠道跟踪码是 x2yiy3vi4wwc。您可以使用查询参数将结果集细化为仅包含属于或来自于这两个渠道的数据:
 
&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 调用中的表现。


多应用总览终端

到目前为止讨论的终端只请求单个应用的数据。这些数据对于单个应用的完整分解是必不可少的,但不会提供多个(甚至所有)应用的概览。在此讨论的多应用终端可以提供完整的概览。


终端地址

可以调用的终端可交付成果有两种不同的类别:
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_dateYYYY-MM-DD选定周期的开始日期。
end_dateYYYY-MM-DD选定周期的结束日期。
utc_offset[+-]HH:MM,例如,utc_offset=-05:00 或 utc_offset=10:00时区的 UTC 偏离
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

该请求的响应示例为:
 
日期installssessions
2015-12-01209311703
2015-12-02112411211
2015-12-0356515687

请注意,这是表格响应版本(即,以 CSV 格式输出)。

应用和渠道跟踪链接分解
接下来,可以为这两个应用分别请求安装和会话数据,并通过渠道跟踪链接进行聚合。此操作对比较应用配置文件中不同渠道的表现十分有用。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,networks

同样,响应此请求的表格格式输出示例为:
 
app_tokenapp_nameapp_namenetworkinstallssessions
44cdcdck2syc首个应用5aml2f广告渠道4080
44cdcdck2syc首个应用28kse9电子邮件广告192292
9xmtsnp687ek我的其他应用16px8z另一个渠道20013001
9xmtsnp687ek我的其他应用21h2o9电子邮件广告1737


KPI 服务术语表

我们可以提供 KPI 的完整列表,在 KPI 服务术语表中,您可以查看它们的定义以及它们的计算方式。

有关此主题