Aos2设备激活方案

发表于 2025/08/25

作者 klizzz

14 分钟阅读

Aos2设备激活方案

此文档修改自吕中原的钉钉在线文档《AOS2-设备激活方案》，以此文档为准。

1. 概述

通过为每个设备生成唯一标识，精准判断该设备本次安装行为是否为设备首次安装（设备激活）。其中，对于 H5 端和 Web 端，将不存在设备激活和设备重装的概念，在本次方案中不考虑。

本文档重点解决以下几个问题，同时作为 AOS2 服务开发的指导文档。

异常设备标识的检测
设备唯一标识的生成
设备激活的判定

基础流程图：

2. 异常设备标识的检测

按照不同的终端类型和系统类型，对不同的设备标识的合理性进行检测

移动端

安卓

设备标识	名称	合理性检测方式
IMEI	设备硬件序列号	字符合法性检查（`0~9、a~f、A~F`）；合理长度在10位到32位之间；对于连续出现超过5个0的标识为不合法
OAID	应用匿名标识符匿名标识符	字符合法性检查（`0~9、a~f、A~F`）；OAID的合理长度在14位到64位之间；常见的空值有00000000-0000-0000-0000-000000000000；对于连续出现超过5个0的标识为不合理
ANDROIDID	安卓ID	字符合法性检查（`0~9、a~f、A~F`）；长度检查：合理长度大于5
MAC	MAC地址	字符合法性检查（`0~9、a~f、A~F`）；长度检查：长度等于17

IOS

设备标识	名称	合理性检测方式
IDFA	广告追踪标识	字符合法性检查（0~9、a~z、A~F）；长度等于36，且为”8-4-4-4-12”格式；连续的0 不超过5个；常见的空值：00000000-0000-0000-0000-000000000000
IDFV	开发者应用标识	字符合法性检查（0~9、a~f、A~F）；长度等于36，且为”8-4-4-4-12”格式；连续的0 不超过5个；常见的空值：00000000-0000-0000-0000-000000000000

鸿蒙

设备标识	名称	合理性检测方式
AAID	应用匿名标识符	字符合法性检查（0~9、a~f、A~F）；长度等于36，且为”8-4-4-4-12”格式；连续的0 不超过5个；常见的空值：00000000-0000-0000-0000-000000000000
ODID	开发者匿名设备标识符	字符合法性检查（0~9、a~f、A~F）；长度等于36，且为”8-4-4-4-12”格式；连续的0 不超过5个；常见的空值：00000000-0000-0000-0000-000000000000
ASSETSTOREKIT	鸿蒙钥匙串数据	字符合法性检查（0~9、a~f、A~F）； dwplatid =1 时 ,长度等于36 dwplatid =9 时 ,长度等于48

PC端

设备标识	名称	合理性检测方式
DiskSerial	系统盘的硬盘序列号	长度检查：长度大于8
MAC	网卡MAC地址	长度检查：长度等于17

3. 设备唯一标识的生成

3.1 处理流程图

设备状态：

数据的存储格式为：索引集合 + 对象集合
存储数据库：MogoDB
库名：aos_devide

索引集合结构：

字段	名称	是否建立索引	数据类型	值内容
_id	设备标识索引	是	string	按照不同集合，分别用于存放：oaid\ imei\ androidid\ mac\ idfa\ idfv\ keychain\ aaid\ odid\ assetstorekit
dev_id	设备唯一ID	否	string	生成的设备唯一ID
dev_num	该索引下的设备数	否	int32

对象集合结构：

字段	名称	是否建立索引	数据类型	值内容
dev_id （_id）	设备唯一ID	是	string	生成的设备唯一ID
os	端类型	否	int	取值dwTOStype
company	终端生产厂商	否	string	设备厂商，字段不加密
unittype	终端设备型号	否	string	设备型号，不加密
dev_time	安装时间（首次、最近一次安装时间）	否	json	该设备在产线的首次/最近一次安装时间

对象数据结构示例：

        
      
{
  "_id": "1346a51c6s54d64894bd",
  "os": 1,
  "company": "VIVO",
  "unittype": "vivoplayerno1",
  "dev_time":{
    "1": {
       "ft": "17451651968",
       "lt": "17451651968",
    },
    "3": {
       "ft": "17451651969",
       "lt": "17451652222",
    }
  }
}

3.2 设备唯一ID 的生成规则

生成算法：

类型：String
长度： 32 char
各字节含义：

|<-2位->|<-2位->|<---- 8位 ---->|<--------- 10位--------->|<- 2位->|<-- 4位-->|<-- 4位-->|

|  终端 |  端   |    随机字符    |          时间戳         | 机器码 |   自增ID |  保留位   |  

含义解释：
- 终端：区分 PC、移动端、TV 端（m_nTType）生成方式：按当前设备终端的枚举值填写，补齐长度。举例：01-PC 端，02-移动端。
- 端：IOS \安卓 \鸿蒙（m_dwTOStype）
- 生成方式：按当前设备端类型填写，补齐长度。举例：1-Windows ，2-安卓， 3-IOS。
- 自增ID：服务器产生的自增 ID
- 机器码：服务器的编号码（在 TKAOS2Service.ini 中定义）。
【占位】

3.3 业务处理流程

判断终端类型和端类型

~~终端类型：使用 TK_ENUM_CLTCTRLINFO_ID_TERMINALTYPE 区分；1-PC、2-移动端~~

端类型：使用 TK_ENUM_CLTCTRLINFO_ID_OSTYPE 区分。字典见下方

        
      
TK_ENUM_CLTCTRLINFO_OSTYPE_RESERVE    = 0,    // 保留
TK_ENUM_CLTCTRLINFO_OSTYPE_WINDOWS    = 1,    // Windows
TK_ENUM_CLTCTRLINFO_OSTYPE_ANDROID    = 2,    // Android
TK_ENUM_CLTCTRLINFO_OSTYPE_IOS    = 3,    // IOS
TK_ENUM_CLTCTRLINFO_OSTYPE_WINDOWSPHONE    = 4,    // Windows Phone
TK_ENUM_CLTCTRLINFO_OSTYPE_ANDROIDTV    = 5,     // Android TV
TK_ENUM_CLTCTRLINFO_OSTYPE_ANDROID_SIMULATOR= 6,     // Android Simulator
TK_ENUM_CLTCTRLINFO_OSTYPE_IOS_SIMULATOR    = 7,     // IOS Simulator
TK_ENUM_CLTCTRLINFO_OSTYPE_HARMONYOS    = 8     // 鸿蒙

对于不同的端类型对其相关设备标识进行检测，对于不合理的设备标识不在业务中使用。合理性监测规则见_异常设备标识的检测_。
1. 按照上述_2.异常设备标识的检测_ 中的检测规则，筛除异常值。
2. 查询每类设备的异常标识库，排除异常标识。（主要解决不同厂家的默认值问题和黑灰产异常设备问题）
不同终端和端类型，采用不同的设备标识组来查找和生成设备唯一标识。
- ~~PC端~~
  
  ~~设备标识：DiskSerial、MAC~~
  
  ~~查找规则：同时使用DiskSerial 和MAC 查询设备标识库，若查找到设备，判断设备名称（TK_ENUM_CLTCTRLINFO_ID_TERMINALDEVICENAME）是否相同。优先使用设备名称相同的，其次优先选择DiskSerial结果。~~
- 移动端
  - 安卓
  - 设备标识：OAID、ANDROIDID、IMIE、MAC

3.4 设备标识的MogoDB的表结构

如下表格拷贝自钉钉共享文档《设备标识的MogoDB的表结构.xlsx》

4. 设备激活的判定

如何判定设备激活：

需要新生成一个设备激活ID，或是content对象中该产线已经被激活过时，则判定为设备激活（if_first =1）。

逻辑处理字段格式

字段名	类型	含义	说明
if_first	int	是否为设备激活	1-设备激活 / 0-设备重装
dev_ident	string	设备的激活ID(设备ID)
dev_ftime	int64	设备首次安装时间(时间戳)	举例：1702067108
dev_ltime	int64	设备最近一次安装时间(时间戳)	举例：1752067108
dev_anomaly	int	AOS2处理该设备时的错误码	错误码见 aos2::ErrorCode

数据样例：

        
      
{
	"if_first ": 1,
	"dev_ident": "6f3425c007203f0a54c8db2865a409", //生成方式未确定
	"dev_ftime": 1702067108,
	"dev_ltime": 1752067108,
	"dev_anomaly": 0
}

AOS2 服务激活重装实现流程图：

如下流程图见本地文件《AOS2_激活重装判断流程.drawio》

说明：在进行设备型号验证（UnitType）时,以下两种情况不参与设备型号验证：

官方包（G_SITEID=12300052）。因官方包历史数据的设备型号存在异常值，导致该字段无法进行验证。
IOS设备。IOS设备的设备型号字段不符合采集规范，因此无法使用。

5. 其他

5.1 IOS的设备排重

见钉钉在线文档《MCA-通用HTTP请求接口》，接口要求同见这个文档。

5.2 上下游协议

上游-MCABROKER

激活协议：

        
      
/********************************************************************
协议：广告推广激活通知接口-新版-JSON
说明：AAABrokerSrv -> MCAbrokerSrv 激活，增加补充数据
********************************************************************/
#define TKID_AAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON      (TKID_MSG_MCA_BASE +  0x11)
//请求：
typedef struct tagTkReqAAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON {
    inline DWORD GetMsgGroup()
    {
        return rand();
    };
    TKHEADER        header;
    TKSUFFIXIDX     data;                                   //JSON补充字段
    TKSUFFIXIDX     stSufCtrlIdent;                         //控制标识
} TKREQAAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON, * PTKREQAAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON;
//
//回馈：
typedef struct tagTkAckAAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON {
    TKHEADER    header;
} TKACKAAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON, * PTKACKAAAS2MCABROKERS_DEVACTIVENOTIFY_NEW_JSON;

HTTPS 请求协议：

        
      
/************************************************************************
协议：HTTPS查询请求
说明：WBS -> MCABrokerSrv
返回码：
************************************************************************/
#define TKID_WBS2MCABROKERS_HTTPS_QUERY        (TKID_MSG_MCA_BASE +  0x16)

//请求：
typedef struct tagTkReqWBS2MCABrokerHttpsQuery {
    TKHEADER     header;
    TKSUFFIXIDX  data;

} TKREQWBS2MCABROKERHTTPSQUERY, * PTKREQWBS2MCABROKERHTTPSQUERY;
//回馈：返回体格式有严格要求
typedef struct tagTkAckWBS2MCABrokerHttpsQuery {
    TKHEADER     header;
    TKSUFFIXIDX  data;
} TKACKWBS2MCABROKERHTTPSQUERY, * PTKACKWBS2MCABROKERHTTPSQUERY;

下游-MCAService