文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>推送服务（Push）>平滑迁移方案

平滑迁移方案

最近更新时间：2026-03-23 15:31:21

我的收藏

本页目录：

本文档旨在指导您将 TPNS 原有的推送逻辑平滑迁移至 TIMPush 方案。通过以下简化的集成步骤，您可以实现更高效、更稳定的消息推送服务。

迁移影响范围

维度
TPNS
TIMPush
迁移影响
客户端 SDK
TPNS SDK
TIMPush SDK
需替换
认证方式
AccessId + SecretKey
需修改
推送 API 路径
/v3/push/app
v4/timpush/push (全员/标签推送)，/v4/timpush/batch (单发推送)
需修改
设备标识
TPNS Token
RegistrationID/UserID (IM 账号体系)
逻辑变化
标签管理
TPNS 标签体系
TIMPush 标签体系
需迁移
推送通道配置
TPNS 控制台
TIMPush 控制台
需重新配置
数据统计
TPNS 数据面板
TIMPush 数据面板
自动适配

迁移步骤

步骤1：环境清理

在开始集成前，请务必从您的项目中移除原有的推送集成代码逻辑及相关的 SDK 依赖库，以避免依赖冲突。以 TPNS 为例：
Android
iOS
android {
 ......
 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 常用功能场景请参考：推送典型场景介绍。

TPNS 至 TIMPush 服务端迁移

推送相关 API 对照表

类别
平台
接口文档
作用
全员/标签推送
TPNS
全量、标签、账号、设备等多目标推送
TIMPush
全量、标签组合、属性组合推送
单发推送
TPNS
单账号、批量账号推送
TIMPush
单账号、批量账号推送

标签管理 API 对照表

类别
平台
接口 URL
作用
标签添加
TPNS
给用户绑定标签
TIMPush
标签删除
TPNS
删除用户指定标签
TIMPush
标签清空
TPNS
删除用户全部标签
TIMPush
标签查询
TPNS
仅支持在控制台查看
查看用户标签列表
TIMPush

属性管理 API 对照表

类别
平台
接口 URL
作用
设置属性名称
TPNS
仅支持控制台设置
设置应用属性名称
TIMPush
查询属性名称
TPNS
仅支持控制台查看
获取应用属性名称
TIMPush
属性设置
TPNS
设置用户属性（例如 level=svip）
TIMPush
属性删除
TPNS
删除用户属性
TIMPush
属性查询
TPNS
获取用户属性
TIMPush

3.4 推送相关 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", ... }           // 其他参数说明可参见文档
  }
}

标签管理 API 迁移示例

示例 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"]
}

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

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/get_tag。
{
  "UserIDList": ["user1", "user2", "user3"]
}

属性管理 API 迁移示例

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

TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/set_attr_name。
{
    "AttrNames": {
        "0": "sex",
        "1": "city"
    },
    "AttrTypes": {
        "0": 0, // 设置属性对应的账号类型，设置之后不支持修改。
        "1": 0
    }
}

示例 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"}}
  ]
}

示例 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"]}
  ]
}

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

TPNS 请求示例如下，不支持批量，更多详细说明可参见：v3/device/set_custom_attribute。
{
    "cmd": 5,    
    "token": "token1"
}
TIMPush 请求示例如下，更多详细说明可参见：v4/timpush/get_attr
{
    "To_Account": ["user1", "user2", "user3"]
}

推送核心参数映射

TIMPush 的推送内容统一通过OfflinePushInfo配置，该对象与 TPNS 的message参数高度映射。
下面列出部分核心参数对照表，其他参数：TPNS 更多详细说明可参见 推送接口，TIMPush 更多详细说明可参见 公共参数（OfflinePushInfo说明）。

全局基础核心参数映射表

TIMPush 参数
TPNS 参数
类型
含义
OfflinePushInfo.Title
message.title
String
推送标题
OfflinePushInfo.Desc
message.content
String
推送内容

Android 厂商核心参数映射表

TIMPush 参数
TPNS 参数
类型
含义
OfflinePushInfo.AndroidInfo.XiaoMiChannelID
message.android.xm_ch_id
String
小米通道 ID
OfflinePushInfo.AndroidInfo.OPPOCategory
message.android.oppo_category
String
OPPO 消息分类
OfflinePushInfo.AndroidInfo.VIVOCategory
message.android.vivo_category
String
VIVO 消息分类
OfflinePushInfo.AndroidInfo.HuaWeiCategory
message.android.hw_category
String
华为消息分类
OfflinePushInfo.AndroidInfo.HonorImportance
message.android.honor_importance
String
荣耀消息优先级
OfflinePushInfo.AndroidInfo.Sound
message.android.ring_raw
String
安卓自定义铃声

APNs 厂商核心参数映射表

TIMPush 参数
TPNS 参数
类型
含义
OfflinePushInfo.ApnsInfo.InterruptionLevel
message.ios.aps.interruption-level
String
iOS 15+ 通知级别
OfflinePushInfo.ApnsInfo.MutableContent
message.ios.aps.mutable-content
Integer
APNs 推送扩展
OfflinePushInfo.ApnsInfo.Image
message.xg_media_resources
String
IOS 图片推送
OfflinePushInfo.ApnsInfo.Sound
message.ios.aps.sound
String
iOS 自定义铃声

特殊推送场景参数映射表

特殊场景
TIMPush
TPNS
APNs 透传推送
OfflinePushInfo.ApnsInfo.ContentAvailable=1
更多详情可参见 APNs 透传推送。
message.ios.aps.content-available=1
更多详情可参见 iOS 静默消息。
APNs VoIP 推送
OfflinePushInfo.ApnsInfo.IsVoipPush=1
更多详情可参见 APNs VoIP 推送。
-
APNs LiveActivity 推送
OfflinePushInfo.ApnsInfo.LiveActivity
更多详情可参见 APNs LiveActivity (灵动岛) 推送。
message.ios.aps.event/update 等
更多详情可参见 iOS LiveActivity。

补充说明

所有 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 标签属性批量设置接口实现。
中国站
目录