跳到主要内容

APP 活跃上报接口

核心概念：文档中心 | APP 活跃上报接口 | 概览

本接口用于设备端上报 APP 的活跃数据（运行时长、启动次数等），支持实时、延迟及特殊上报模式。

相关业务文档：APP活跃统计管理

核心概念：文档中心 | APP 活跃上报接口 | 接口地址（APP 活跃上报）

接口地址（APP 活跃上报）​

http://app.activity.thirdparty.akrdinfo.cn:30133/app-api/third/app/activity/v2

核心概念：文档中心 | APP 活跃上报接口 | 请求参数说明（APP 活跃上报）

请求参数说明（APP 活跃上报）​

时区警告

特殊上报和延迟上报模式下，涉及日期的判断逻辑（如跨天、日期变更）**必须严格按照北京时间（Asia/Shanghai，UTC+8）**进行处理，以确保服务端统计的准确性。

mac: 终端设备的 MAC 地址 (必填)
cpu: 设备 CPU 信息 (必填)
packageName: APP 包名 (必填)
versionCode: APP 版本号 (必填)
type: 上报类型，0-实时上报/特殊上报，1-延迟汇总上报 (必填)
timeIntervalConfig: 上次从服务端获取的配置间隔（分钟），也是本次上报周期的运行时长 (Type=0 时必填)
time_stamp: 设备时间戳，13位 Long 类型 (Type=0 时必填)
time_zone: 设备时区 (如 "Asia/Shanghai")
delayDatas: 延迟上报数据集合 (Type=1 时必填)
delayDatas[*].day: 延迟上报日期，格式为 YYYY-MM-DD
delayDatas[*].duration: 对应日期内的运行总时长，单位：分钟
核心概念：文档中心 | APP 活跃上报接口 | 上报模式说明

上报模式说明​

接口支持以下三种上报模式，设备端需根据业务场景选择合适的模式：

1. 实时上报模式 (Type = 0)​

  • 场景：设备正常联网运行期间的常规活跃数据上报。
  • 逻辑：
    1. 获取配置：设备首次上报或按配置间隔上报时，服务端会在响应中返回 deviceConfigurationResp，其中包含下一次上报的时间间隔要求。
    2. 间隔计时：设备端需按此间隔进行计时。
    3. 回传时长：计时结束后，设备再次调用本接口，并将上一次服务端下发的间隔时间作为 timeIntervalConfig 参数回传。服务端将此数值记录为该周期的运行时长。

2. 延迟上报模式 (Type = 1)​

  • 场景：用于上报历史积压数据（如跨天数据、断网重连后的补报）。
  • 逻辑：
    1. 每日汇总：设备端需自行记录当天的应用运行时长。跨过当日零点（北京时间）后，将前一日的总运行时长通过 delayDatas 字段上报。
    2. 断网补报：如果设备关机或断网导致数据未能及时上报，需在网络恢复后打包补报历史数据。
    3. 重试策略：若接口返回 500 错误，建议按 5m/30m/100m/300m/1d/3d/5d/10d/20d 的间隔重试；若多次失败则丢弃。非 200/500 错误（如网络故障）建议延迟 1 小时重试。

3. 特殊上报模式 (Type = 0, timeIntervalConfig = 0)​

  • 场景：不统计具体运行时长，仅统计“是否活跃”（如开机启动、日期变更）。
  • 逻辑：
    1. 触发条件：
      • 设备开机启动时。
      • 设备日期发生变更时（以北京时间为准）。
    2. 参数设置：走实时上报逻辑（type=0），但必须将 timeIntervalConfig 固定设置为 0。
    3. 服务端处理：服务端接收到 0 时长请求后，仅记录一次活跃行为，不累计运行时长。
核心概念：文档中心 | APP 活跃上报接口 | 请求示例

请求示例​

场景：常规心跳上报，回传配置的时长。

入参示例 (JSON)：

{
  "mac": "00:1A:79:A0:01:CC",
  "cpu": "17509184403286cce35bc4be141eaab",
  "packageName": "com.gzsuy.sz01",
  "versionCode": 11235,
  "type": 0,
  "timeIntervalConfig": 5,
  "time_stamp": 1753181666064,
  "time_zone": "Asia/Shanghai"
}
核心概念：文档中心 | APP 活跃上报接口 | 返回示例

返回示例​

成功返回​

{
  "code": 200,
  "data": [
    {
      "type": 10,
      "param": [
        1, // 下次上报间隔配置（分钟）
        5
      ]
    }
  ],
  "msg": "Submitted successfully"
}

失败返回​

{
  "code": 500,
  "data": null,
  "msg": "data in wrong format"
}
核心概念：文档中心 | APP 活跃上报接口 | 实体类定义

实体类定义 (Java)​

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Data;
import java.util.Date;
import java.util.List;

/**
 * app活跃请求实体
 */
@Data
public class AppActivityReq {
    public static final int TYPE_REALTIME = 0;
    public static final int TYPE_DELAY = 1;

    /**
     * mac地址
     */
    private String mac;
    /**
     * cpu
     */
    private String cpu;
    /**
     * 包名
     */
    private String packageName;
    /**
     * 版本号
     */
    private Integer versionCode;

    /**
     * 拉取到的服务端配置时间间隔(分钟)，也是本次上报的运行时长
     * Type=0 时必填，特殊上报模式传 0
     */
    private Integer timeIntervalConfig;

    /**
     * 类型：0-实时上报/特殊上报，1-延迟汇总上报
     */
    private int type;

    /**
     * 设备时间戳 (13位 Long 类型)
     */
    @JsonProperty("time_stamp")
    private Long timeStamp;

    @JsonProperty("time_zone")
    private String timeZone;

    private String ip;

    private List<DelayData> delayDatas;

    @Data
    public static class DelayData {
        /**
         * 延迟上报日期 (YYYY-MM-DD)
         */
        String day;
        /**
         * 运行时长 (分钟)
         */
        private int duration;
    }
}
AI 问答