即时通信 IM Unreal Engine

一、前置准备（控制台）

跑通 Demo 前，请先在腾讯云控制台完成账号与厂商通道准备：

1. 创建应用：登录即时通信 IM 控制台，在应用列表单击创建应用接入，记录生成的 SDKAppID。

2. 获取密钥：进入目标应用的应用配置，单击查看密钥，拷贝并妥善保管 SDKAppID 与客户端密钥 AppKey。

注意：推送服务的客户端密钥与 Chat 的密钥不同，请勿混用。密钥属于敏感信息，请勿提交到代码仓库。

3. 开通推送并配置厂商通道：在控制台推送服务页开通推送能力，按需配置 Android 厂商通道（小米 / 华为 / 荣耀 / OPPO / vivo / 魅族 / FCM）与 iOS APNs 通道，下载 timpush-configs.json 及各厂商服务配置文件，并记录 APNs 证书 ID。

二、环境要求

项目	要求
引擎	Unreal Engine 5，已配置 Android / iOS 打包环境
测试设备	Android 或 iOS 真机（离线推送必须通过真机验证）

三、工程结构

unreal engine/pushdemo/├── Config/ # DefaultEngine.ini 等├── Content/ # Demo 蓝图 / UMG 控件├── Plugins/TIMPush/ # TIMPush 插件（Source/TIMPush、TIMPush_APL.xml）├── Source/pushdemo/ # 主模块（pushdemo.Build.cs、MyUserWidget.cpp）└── pushdemo.uproject

项目已内置 Plugins/TIMPush 插件，且主模块 Source/pushdemo/pushdemo.Build.cs 已声明依赖 "TIMPush"，无需额外引入。

四、步骤 1：填写 SDKAppID 与 AppKey

打开 Source/pushdemo/MyUserWidget.cpp，在 CallRegisterPush() 中替换占位值：

int appID = 0; // 改为你的 SDKAppIDFString appKey = ""; // 改为你的 AppKey

五、步骤 2：配置 Android 端

编辑 Plugins/TIMPush/Source/TIMPush/TIMPush_APL.xml：

1. buildGradleAdditions：添加推送主包 com.tencent.timpush:tpush:VERSION（必选），并按需添加厂商包（huawei / xiaomi / oppo / vivo / honor / meizu / fcm），VERSION 请替换为更新日志中的最新版本号。

2. buildscriptGradleAdditions：添加华为 / 荣耀 / FCM 的 classpath 及对应 maven 仓库。

3. manifestPlaceholders：填写 vivo / 荣耀的 APPID 与 APPKEY（未接入的厂商可忽略）。

4. 放置配置文件：

·timpush-configs.json → Source/ThirdParty/TIMPushLibrary/Android/TIMPush/Assets/；

·华为 / 荣耀 / FCM 的 json 配置文件 → Source/ThirdParty/TIMPushLibrary/Android/TIMPush/。

六、步骤 3：配置 iOS 端

1. 在 UE 编辑器【Project Settings】中搜索 Additional Plist Data，填入：

<key>businessID</key><string>你的证书ID</string><key>TIMPushAppGroupID</key><string>你的AppGroupID</string>

注意：businessID 必填，即控制台 APNs 证书 ID；TIMPushAppGroupID 在需要统计触达 / 点击数据时填写。

2. 开启远程推送能力：在 Config/DefaultEngine.ini 的 [/Script/IOSRuntimeSettings.IOSRuntimeSettings] 下添加：

bEnableRemoteNotificationsSupport=True

注意：如使用源码编译引擎，也可在【Project Settings > iOS】勾选 Enable Remote Notifications Support；或用 Xcode 打开 .xcworkspace 添加 Push Notifications 能力，三者任选其一。

七、步骤 4：运行验证

1. 使用 UE5 将项目打包到真机并安装启动。

2. 在 Demo UI 中调用 RegisterPush。

3. 将 App 切至后台，通过控制台推送服务 Push > 接入测试发送一条测试推送，设备收到推送即代表全链路跑通。

八、注意事项

·监听注册时机：请在程序入口处通过 AddPushListener 注册推送监听，回调包括 OnRecvPushMessage / OnRevokePushMessage / OnNotificationClicked。

·通知点击跳转：如需点击通知跳转到指定页面，控制台厂商证书的点击后续动作请选择打开应用内指定界面并保持默认填充值不修改。

·触达统计（可选）：华为 / 荣耀 / vivo / 魅族需配置对应回执地址；FCM 暂不支持推送统计。华为推送证书 ID 小于等于 11344 时使用 v2 接口，不支持触达与点击回执，需重新生成并更新证书 ID。

·服务有效期：推送服务试用或购买到期后将自动停止推送，请及时续费。

九、常见问题

·Android 打包后注册失败：检查 TIMPush_APL.xml 中主包与厂商包版本号是否有效、厂商仓库与 classpath 是否配置完整、timpush-configs.json 是否放入 Assets 目录。

·收不到推送：确认真机厂商与目标厂商通道一致；使用控制台推送排查工具输入 RegistrationID 自查，并按错误码查询失败回调含义。

十、相关文档

·Unreal Engine SDK 接入

·Unreal Engine 厂商配置

·Unreal Engine 客户端 API

·推送排查工具