即时通信 IM 平滑迁移方案

一、迁移影响范围

三、步骤1：环境清理

在开始集成前，请务必从你的项目中移除原有的推送集成代码逻辑及相关的 SDK 依赖库，以避免依赖冲突。以 TPNS 为例：

AndroidiOSandroid { …… defaultConfig { manifestPlaceholders = [ // 以下内容删除 XG_ACCESS_ID : "注册应用的accessid", XG_ACCESS_KEY : "注册应用的accesskey", ] …… } ……}dependencies { …… //删除以下依赖 implementation 'com.tencent.tpns:tpns:[VERSION]-release' implementation 'com.tencent.tpns:honor:[VERSION]-release' implementation 'com.tencent.tpns:xiaomi:[VERSION]-release' implementation 'com.tencent.tpns:huawei:[VERSION]-release' implementation 'com.tencent.tpns:oppo:[VERSION]-release' implementation 'com.tencent.tpns:vivo:[VERSION]-release' implementation 'com.tencent.tpns:meizu:[VERSION]-release' implementation 'com.tencent.tpns:fcm:[VERSION]-release'}你需要在 Podfile 中移除组件依赖：target 'YourAppName' do # 移除组件依赖 pod 'TPNS-iOS', '~> 版本'end

四、步骤2：厂商配置

你需要先在 即时通信 IM 控制台 > 推送服务 Push 中配置各平台厂商的推送证书。这一步是确保消息能够通过系统级通道触达的关键。

·Android 平台：请参考 Android 厂商推送配置指引。

·iOS 平台：请参考 Apple 推送证书配置指引。

五、步骤3：快速集成 TIMPush SDK

完成云端配置后，请按照以下文档将 TIMPush 组件集成到你的客户端应用中：

·Android 端集成：快速接入 TIMPush (Android)。

·iOS 端集成：快速接入 TIMPush (iOS)。

·点击推送通知跳转：自定义点击跳转。

六、验证与发布

恭喜你！完成上述步骤后，SDK 的迁移工作已基本就绪。

注意：说明：

注意：Push 常用功能场景请参考：推送典型场景介绍。

八、推送相关 API 对照表

九、标签管理 API 对照表

十、属性管理 API 对照表

十二、示例 1：全员推送（TPNS → TIMPush）

TPNS 请求示例更多详细说明可参见：/v3/push/app。

{ "audience_type": "all", "message_type": "notify", "environment": "product", "message": { "title": "全量推送通知", "content": "全量推送内容", "android": {"hw_category": "MARKETING", …}, // 其他参数说明可参见文档 "ios": {"aps": {"sound": "default", …}} // 其他参数说明可参见文档 }}

TIMPush 请求示例更多详细说明可参见：v4/timpush/push。

{ "From_Account": "administrator", "MsgRandom": 123456789, "OfflinePushInfo": { "Title": "全量推送通知", "Desc": "全量推送内容", "Ext": "{\\"entity\\":{\\"k1\\":\\"v1\\",\\"k2\\":\\"v2\\"}}", // 透传字段，推荐使用 json 字符串，常用于推送点击跳转 "AndroidInfo": {"HuaWeiCategory": "MARKETING", …}, // 其他参数说明可参见文档 "ApnsInfo": {"Sound": "default.mp3", … } // 其他参数说明可参见文档 }}

十三、示例 2：标签推送（OR 规则）（TPNS → TIMPush）

TPNS 请求示例更多详细说明可参见：/v3/push/app。

{ "audience_type": "tag", "tag_rules": [ { "tag_items": [ { "tags": ["guangdong", "beijing"], "tags_operator": "OR" } ] } ], "message_type": "notify", "environment": "product", "message": { "title": "标签推送", "content": "标签用户专属通知", "android": {"hw_category": "MARKETING", …}, // 其他参数说明可参见文档 "ios": {"aps": {"sound": "default", …}} // 其他参数说明可参见文档 }}

TIMPush 请求示例更多详细说明可参见：v4/timpush/push。

{ "From_Account": "administrator", "MsgRandom": 987654321, "Condition": {"TagsOr": ["guangdong", "beijing"]}, "OfflinePushInfo": { "PushFlag": 0, "Title": "标签推送", "Desc": "标签用户专属通知", "Ext": "{\\"entity\\":{\\"k1\\":\\"v1\\",\\"k2\\":\\"v2\\"}}", // 透传字段，推荐使用 json 字符串，常用于推送点击跳转 "AndroidInfo": {"HuaWeiCategory": "MARKETING", …}, // 其他参数说明可参见文档 "ApnsInfo": {"Sound": "default.mp3", … } // 其他参数说明可参见文档 }}

十四、示例 3：属性推送（AND 规则）（TPNS → TIMPush）

TPNS 请求示例更多详细说明可参见：/v3/push/app。

{ "audience_type": "tag", "tag_type": "user_attr", "tag_rules": [ { "tag_items": [ {"tags": ["city=shenzhen"], "tags_operator": "AND"}, {"tags": ["level=svip"], "tags_operator": "AND"} ] } ], "message_type": "notify", "environment": "product", "message": { "title": "SVIP专属推送", "content": "深圳SVIP用户专属福利", "android": {"hw_category": "MARKETING", …}, // 其他参数说明可参见文档 "ios": {"aps": {"sound": "default", …}} // 其他参数说明可参见文档 }}

TIMPush 请求示例更多详细说明可参见：v4/timpush/push。

{ "From_Account": "administrator", "MsgRandom": 654321987, "Condition": { "AttrsAnd": {"city": "shenzhen", "level": "svip"} }, "OfflinePushInfo": { "PushFlag": 0, "Title": "SVIP专属推送", "Desc": "深圳SVIP用户专属福利", "Ext": "{\\"entity\\":{\\"k1\\":\\"v1\\",\\"k2\\":\\"v2\\"}}", // 透传字段，推荐使用 json 字符串，常用于推送点击跳转 "AndroidInfo": {"HuaWeiCategory": "MARKETING", …}, // 其他参数说明可参见文档 "ApnsInfo": {"Sound": "default.mp3", … } // 其他参数说明可参见文档 }}

十五、示例 4：指定账号推送（TPNS → TIMPush）

TPNS 请求示例更多详细说明可参见：/v3/push/app。

{ "audience_type": "account_list", "account_list": ["user1","user2"], "message_type": "notify", "environment": "product", "message": { "title": "全量推送通知", "content": "全量推送内容", "android": {"hw_category": "MARKETING", …}, // 其他参数说明可参见文档 "ios": {"aps": {"sound": "default", …}} // 其他参数说明可参见文档 }}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/batch。

{ "From_Account": "administrator", "To_Account": ["user1","user2"], "MsgRandom": 1122334455, "OfflinePushInfo": { "PushFlag": 0, "Title": "SVIP专属推送", "Desc": "深圳SVIP用户专属福利", "Ext": "{\\"entity\\":{\\"k1\\":\\"v1\\",\\"k2\\":\\"v2\\"}}", // 透传字段，推荐使用 json 字符串，常用于推送点击跳转 "AndroidInfo": {"HuaWeiCategory": "MARKETING", …}, // 其他参数说明可参见文档 "ApnsInfo": {"Sound": "default.mp3", … } // 其他参数说明可参见文档 }}

十七、示例 1：批量添加用户标签（TPNS → TIMPush）

TPNS 请求示例如下，更多详细说明可参见：/v3/device/tag。

{ "operator_type": 9, "tag_token_list": [ {"tag": "t1","token": "token1"}, {"tag": "t2","token": "token2"} ]}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/add_tag。

{ "UserTags": [ {"To_Account": "user1", "Tags": ["male", "vip", "guangdong"]}, {"To_Account": "user2", "Tags": ["female", "vip", "beijing"]} ]}

十八、示例 2：批量删除用户标签（TPNS → TIMPush）

TPNS 请求示例如下，更多详细说明可参见：/v3/device/tag。

{ "operator_type": 10, "tag_token_list": [ {"tag": "t1","token": "token1"}, {"tag": "t2","token": "token2"} ]}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/remove_tag。

{ "UserTags": [ {"To_Account": "user1", "Tags": ["vip"]}, {"To_Account": "user2", "Tags": ["vip", "beijing"]} ]}

十九、示例 3：批量清空用户标签（TPNS → TIMPush）

TPNS 请求示例如下，更多详细说明可参见：/v3/device/tag。

{ "operator_type": 5, "token_list": ["user1", "user2", "user3"]}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/clear_all_tags。

{ "To_Account": ["user1", "user2", "user3"]}

20、示例 4：批量获取用户标签（TIMPush 专属，TPNS 仅支持控制台查询）

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/get_tag。

{ "UserIDList": ["user1", "user2", "user3"]}

22、示例 1：设置应用属性名称（TIMPush 专属，TPNS 仅支持控制台设置）

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/set_attr_name。

{ "AttrNames": { "0": "sex", "1": "city" }, "AttrTypes": { "0": 0, // 设置属性对应的账号类型，设置之后不支持修改。 "1": 0 }}

23、示例 2：批量设置用户属性（TPNS → TIMPush）

TPNS 请求示例如下，不支持批量，更多详细说明可参见：v3/device/set_custom_attribute。

{ "cmd": 1, "token": "token1", "attributeInfo": {"attributeMap": {"sex": "male", "city": "shenzhen"}}}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/set_attr。

{ "UserAttrs": [ {"To_Account": "user1", "Attrs": {"sex": "male", "city": "shenzhen"}}, {"To_Account": "user2", "Attrs": {"sex": "female", "city": "guangzhou"}} ]}

24、示例 3：批量删除用户属性（TPNS → TIMPush）

TPNS 请求示例如下，不支持批量，更多详细说明可参见：v3/device/set_custom_attribute。

{ "cmd": 3, "token": "token1", "attributeInfo": {"attributeMap": {"sex": "male"}}}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/remove_attr。

{ "UserAttrs": [ {"To_Account": "user1", "Attrs": ["city"]}, {"To_Account": "user2", "Attrs": ["sex", "city"]} ]}

25、示例 4：批量获取用户属性（TPNS → TIMPush）

TPNS 请求示例如下，不支持批量，更多详细说明可参见：v3/device/set_custom_attribute。

{ "cmd": 5, "token": "token1"}

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/get_attr

{ "To_Account": ["user1", "user2", "user3"]}

26、推送核心参数映射

TIMPush 的推送内容统一通过OfflinePushInfo配置，该对象与 TPNS 的message参数高度映射。

下面列出部分核心参数对照表，其他参数：TPNS 更多详细说明可参见 推送接口，TIMPush 更多详细说明可参见 公共参数（OfflinePushInfo说明）。

27、全局基础核心参数映射表

28、Android 厂商核心参数映射表

29、APNs 厂商核心参数映射表

30、特殊推送场景参数映射表

31、补充说明

·所有 TIMPush 接口的usersig必须由 App 管理员账号生成，普通账号会返回 90009 权限错误。

·TIMPush 接口公共参数中random需传入 32 位无符号随机数，用于同一秒内消息去重。

·标签 / 属性推送时，Condition中仅能选择一种类型（标签 / 属性），不可混用，否则返回 90039 错误。

·TIMPush 标签单个用户最多 10 个，TagsAnd/TagsOr最多 10 个标签；属性仅支持字符串 / 数字精确匹配，不支持数值比较（需业务侧预处理）。

·iOS 平台推送需注意：Sound参数必须带文件后缀（例如 default.mp3），TPNS 无后缀格式需手动补充。

·富媒体图片仅支持 HTTPS 地址，且需符合厂商尺寸要求（如 iOS 建议 1080×1920，Android 建议 720×1280）。

·若需迁移历史标签 / 属性数据，可通过 TIMPush 标签属性批量设置接口实现。