获取应用使用概览
查看应用在某一天/某一周/某一个月的使用数据，可以查看租户整体对应用的使用情况，也可以分部门查看。
Tip: 1. 仅支持企业版/旗舰版租户使用 2. 一般每天早上10点产出前一天的数据 3. 已经支持的指标包括：应用的活跃用户数、累计用户数、新增用户数、访问页面数、打开次数 4. 数据从飞书4.10版本开始统计，使用飞书版本4.10及以下版本的用户数据不会被统计到 5. 按照部门查看数据时，会展示当前部门以及其子部门的整体使用情况 6. 调用频控为100次/分
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/application/v6/applications/:app_id/app_usage/overview |
| HTTP Method | POST |
| 接口频率限制 | 100 次/分钟 |
| 支持的应用类型 | custom |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 | application:application.app_usage_stats.overview:readonly 获取员工使用应用的概览数据 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
app_id | string | 目标应用 ID 示例值："cli_9f115af860f7901b" |
查询参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
department_id_type | string | 否 | 调用中使用的部门ID的类型 示例值：open_department_id 可选值有： - department_id: 以自定义department_id来标识部门 - open_department_id: 以open_department_id来标识部门默认值： open_department_id |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
date | string | 是 | 查询日期，格式为yyyy-mm-dd，若cycle_type为1，date可以为任何自然日；若cycle_type为2，则输入的date必须为周一； 若cycle_type为3，则输入的date必须为每月1号 示例值："2021-07-08" |
cycle_type | int | 是 | 活跃周期的统计类型 示例值：1 可选值有： - 1: 日活，指自然日，返回当前日期所在日的数据 - 2: 周活，指自然周，返回当前日期所在周的数据。若到查询时当周还没结束，则返回周一到当前日期的数值。例如在2021/7/15 查询2021/7/5 这一周的数据，则代表的是2021/7/5 ~ 2021/7/11。但若是在2021/7/8 查询2021/7/5 这一周的数据，则返回的是2021/7/5 ~ 2021/7/7 的数据 - 3: 月活，指自然月，返回当前日期所在月的数据。若不满一个月则返回当月1日到截止日期前的数据。例如在2021/8/15 查询 7月的数据，则代表2021/7/1~2021/7/31。 若在2021/8/15 查询8月的数据，则代表2021/8/1~2021/8/14的数据 |
department_id | string | 否 | 查询的部门id，获取方法可参考部门ID概述 - 若部门id为空，则返回当前租户的使用数据；若填写部门id，则返回当前部门的使用数据（包含子部门的用户）； - 若路径参数中department_id_type为空或者为open_department_id，则此处应该填写部门的 open_department_id；若路径参数中department_id_type为department_id，则此处应该填写部门的 department_id。 示例值："od-4e6ac4d14bcd5071a37a39de902c7141" |
ability | string | 是 | 能力类型，按能力类型进行筛选，返回对应能力的活跃数据 示例值："app" 可选值有： - app: 返回应用整体的数据，指标值包括：uv：活跃用户数，total_users：累计用户数，new_users：新增用户数，pv：在应用（小程序或网页）中访问的页面数，lifecycle：打开应用（小程序或网页）的次数 - mp: 返回小程序能力的数据，指标值包括：uv（小程序活跃用户数）、pv（用户在小程序中的访问页面数）、lifecycle（小程序的打开次数） - h5: 返回网页能力的数据，指标值包括：uv（网页应用活跃用户数）、pv（用户在网页应用中的访问页面数）、lifecycle（网页应用的打开次数） - bot: 返回机器人能力的数据，指标值包括：uv（机器人的活跃用户数） |
请求体示例
json
{
"date": "2021-07-26",
"cycle_type": 1,
"department_id": "od-bb009b4df5431400dc31d3bc8a37e069",
"ability": "app"
}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
└ items | application.app_usage\[\] | 员工使用应用概览数据 |
└ metric_name | string | 指标名称 |
└ metric_value | int | 指标值 |
响应体示例
json
{
"code": 0,
"data": {
"items": [
{
"metric_name": "uv",
"metric_value": 0
},
{
"metric_name": "total_users",
"metric_value": 2
},
{
"metric_name": "new_users",
"metric_value": 0
},
{
"metric_name": "pv",
"metric_value": 0
},
{
"metric_name": "lifecycle",
"metric_value": 0
}
]
},
"msg": "success"
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 403 | 211004 | no authority for quota limit | 检查是否是企业版/旗舰版租户 |
| 400 | 211005 | invalid app id | 检查 app id |
| 400 | 211006 | invalid department id | 检查 department id |
| 400 | 211007 | invalid date format | 检查 date 字段的格式是否符合"2021-07-01" |
| 400 | 211008 | invalid ability | 检查 ability 取值是否正确 |
| 400 | 211009 | invalid cycle type | 检查 cycle_type 取值是否正确 |
| 400 | 211010 | invalid date range | 检查 date 的取值范围是否正确 |
| 200 | 211011 | data not found | 数据不存在。可能是该应用在目标查询日期范围内没有数据。请检查请求参数 |
附录-统计指标说明
| 指标 | 指标定义 | 备注 |
|---|---|---|
| 小程序应用活跃用户数 | - 打开小程序的唯一用户数，按用户ID去重 | - 支持查看某一天/某一周/某一个月的数据 |
| 网页应用活跃用户数 | - 打开网页应用的唯一用户数，按用户ID去重 - 只统计飞书内webview容器部分的数据，不包含三方浏览器容器的内容 | - 支持查看某一天/某一周/某一个月的数据 |
| 机器人应用活跃用户数 | - 满足以下条件之一就算作机器人的活跃用户： - 机器人消息已读 - 主动给机器人发消息 - 单个统计周期内按照用户ID合并去重； | - 支持查看某一天/某一周/某一个月的数据 |
| 应用活跃用户数 | - 满足以下条件之一就算作应用的活跃用户： - 打开小程序 - 打开h5 - 给机器人发消息 - 阅读机器人消息 - 单个统计时间周期内按 用户ID去重计数，以上所有条件合并去重 | - 支持查看某一天/某一周/某一个月的数据 |
| 应用累计用户数 | - 历史上所有使用过应用的用户数 | - 由于累计用户数与时间周期无关，所以只支持截止到某一天的累计用户数 - 即cycle_type只能为1 - 只支持查看应用粒度的累计用户数，不支持区分小程序网页和机器人。 - 即 ability 只能为 app - 注：累计用户数会包含离职人员的统计，所以可能会出现累计用户数大于租户成员数的情况 |
| 应用新增用户数 | - 统计周期内首次访问的唯一用户数 | - 支持查看某一天/某一周/某一个月的数据 - 只支持查看应用粒度的累计用户数，不支持区分小程序网页和机器人。 - 即 ability 只能为 app |
| 应用打开次数 | - 在飞书客户端内打开应用（小程序或网页）的次数 | - 当ability为app、h5、mp时返回具体数据，当ability为bot时返回为空。 - 注：当用户主动退出应用或切换至其他应用超 5min 后记为一次打开 |
| 页面访问数 | - 在应用（小程序或网页）中访问的页面次数 | - 当ability为app、h5、mp时返回具体数据，当ability为bot时返回为空。 - 注：若应用使用过程中切换到其他应用，再切换回飞书打开此应用时，pv会增加 |