即时通信 IM 自定义点击推送跳转

一、功能概述

效果示例

二、厂商通道支持说明

三、各端功能实现

AndroidiOSFlutteruni-appReact Native微信小程序多端框架HarmonyOS

收到离线推送后，通知栏会显示推送信息如下，单击通知栏可以自定义打开应用的界面。1. 控制台配置点击后续动作按如下配置，选择打开应用内指定界面，使用默认参数即可。2. 发送消息填充透传参数。restAPISDK API控制台{ "MsgBody": […] // 这里同 MsgBody 相关描述 "OfflinePushInfo": { "PushFlag": 0, "Title":"离线推送标题", "Desc": "离线推送内容", "Ext": "{\\"entity\\":{\\"key1\\":\\"value1\\",\\"key2\\":\\"value2\\"}}" // 透传字段，推送使用json格式字符串 }}V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();v2TIMOfflinePushInfo.setTitle("推送标题");v2TIMOfflinePushInfo.setDesc("推送内容");OfflinePushExtInfo offlinePushExtInfo = new OfflinePushExtInfo();offlinePushExtInfo.getBusinessInfo().setSenderId("senderID");offlinePushExtInfo.getBusinessInfo().setSenderNickName("senderNickName");if (chatInfo.getType() == V2TIMConversation.V2TIM_GROUP) { offlinePushExtInfo.getBusinessInfo().setChatType(V2TIMConversation.V2TIM_GROUP); offlinePushExtInfo.getBusinessInfo().setSenderId("groupID");}// 透传字段填充v2TIMOfflinePushInfo.setExt(new Gson().toJson(offlinePushExtInfo).getBytes());final V2TIMMessage v2TIMMessage = message.getTimMessage();String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null, V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() { @Override public void onProgress(int progress) { } @Override public void onError(int code, String desc) { TUIChatUtils.callbackOnError(callBack, TAG, code, desc); } @Override public void onSuccess(V2TIMMessage v2TIMMessage) { TUIChatLog.v(TAG, "sendMessage onSuccess:" + v2TIMMessage.getMsgID()); message.setMsgTime(v2TIMMessage.getTimestamp()); TUIChatUtils.callbackOnSuccess(callBack, message); } });3. 点击离线推送消息，组件会回调该点击事件和透传填充的参数。自定义点击跳转实现自定义点击跳转实现（旧方案）注意：注册回调时机必须放在应用 Application 的 onCreate() 函数中。TIMPushManager.getInstance().addPushListener(new TIMPushListener() { @Override public void onNotificationClicked(String ext) { Log.d(TAG, "onNotificationClicked =" + ext); // 获取 ext 自定义跳转 // 示例：跳转到对应聊天界面 OfflinePushExtInfo offlinePushExtInfo = null; try { offlinePushExtInfo = new Gson().fromJson(extString, OfflinePushExtInfo.class); if (offlinePushExtInfo.getBusinessInfo().getChatAction() == OfflinePushExtInfo.REDIRECT_ACTION_CHAT) { String senderId = offlinePushExtInfo.getBusinessInfo().getSenderId(); if (TextUtils.isEmpty(senderId)) { return; } TUIUtils.startChat(senderId, offlinePushExtInfo.getBusinessInfo().getSenderNickName(), offlinePushExtInfo.getBusinessInfo().getChatType()); } } catch (Exception e) { Log.e(TAG, "getOfflinePushExtInfo e: " + e); } }});组件会以回调或者广播形式通知应用，应用在回调中配置 App 的跳转页面即可。注意：注册回调时机建议放在应用 Application 的 onCreate() 函数中。1. 回调方式如下：TUICore.registerEvent(TUIConstants.TIMPush.EVENT_NOTIFY, TUIConstants.TIMPush.EVENT_NOTIFY_NOTIFICATION, new ITUINotification() { @Override public void onNotifyEvent(String key, String subKey, Map<String, Object> param) { Log.d(TAG, "onNotifyEvent key = " + key + "subKey = " + subKey); if (TUIConstants.TIMPush.EVENT_NOTIFY.equals(key)) { if (TUIConstants.TIMPush.EVENT_NOTIFY_NOTIFICATION.equals(subKey)) { if (param != null) { String extString = (String)param.get(TUIConstants.TIMPush.NOTIFICATION_EXT_KEY); // 获取 ext 自定义跳转 } } } } });2. 广播方式如下：// 动态注册广播IntentFilter intentFilter = new IntentFilter();intentFilter.addAction(TUIConstants.TIMPush.NOTIFICATION_BROADCAST_ACTION);LocalBroadcastManager.getInstance(context).registerReceiver(localReceiver, intentFilter);//广播接收者public class OfflinePushLocalReceiver extends BroadcastReceiver { public static final String TAG = OfflinePushLocalReceiver.class.getSimpleName(); @Override public void onReceive(Context context, Intent intent) { DemoLog.d(TAG, "BROADCAST_PUSH_RECEIVER intent = " + intent); if (intent != null) { String ext = intent.getStringExtra(TUIConstants.TIMPush.NOTIFICATION_EXT_KEY); // 获取 ext 自定义跳转 } else { Log.e(TAG, "onReceive ext is null"); } }}

收到离线推送后，通知栏会显示推送信息如下，单击通知栏可以自定义打开应用的界面。1. 发送消息填充透传参数。REST APISDK API控制台{ "MsgBody": […] // 这里同 MsgBody 相关描述 "OfflinePushInfo": { "PushFlag": 0, "Title":"离线推送标题", "Desc": "离线推送内容", "Ext": "{\\"entity\\":{\\"key1\\":\\"value1\\",\\"key2\\":\\"value2\\"}}" // 透传字段，推送使用json格式字符串 }}#import <TUICore/OfflinePushExtInfo.h>V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];pushInfo.title = @"推送标题";pushInfo.desc = @"推送内容"; BOOL isGroup = groupID.length > 0;NSString *senderId = isGroup ? (groupID) : ([TUILogin getUserID]);NSString *nickName = isGroup ? (conversationData.title) : ([TUILogin getNickName] ?: [TUILogin getUserID]);OfflinePushExtInfo *extInfo = [[OfflinePushExtInfo alloc] init];OfflinePushExtBusinessInfo * entity = extInfo.entity;entity.action = 1;entity.content = @"推送内容";entity.sender = senderId;entity.nickname = nickName;entity.faceUrl = [TUILogin getFaceUrl] ?: @"";entity.chatType = [isGroup ? @(V2TIM_GROUP) : @(V2TIM_C2C) integerValue];entity.version = kOfflinePushVersion;// 透传字段pushInfo.ext = [extInfo toReportExtString];2. 点击离线推送消息，组件会回调该点击事件和透传填充的参数。自定义点击跳转实现自定义点击跳转实现（旧方案）注意：注册回调时机建议放在应用 AppDelegate 的 didFinishLaunchingWithOptions 函数中。- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [TIMPushManager addPushListener:self]; return YES;}#pragma mark – TIMPushListener- (void)onNotificationClicked:(NSString *)ext { // 获取 ext 自定义跳转}你需要在 AppDelegate.m 文件中实现 – onRemoteNotificationReceived 方法。#pragma mark – TIMPush – (BOOL)onRemoteNotificationReceived:(NSString *)notice { //- 如果返回 YES， TIMPush 将不在执行内置的 TUIKit 离线推送解析逻辑，完全交由你自行处理； //NSString *ext = notice; //OfflinePushExtInfo *info = [OfflinePushExtInfo createWithExtString:ext]; //return YES; //- 如果返回 NO，TIMPush 将继续执行内置的 TUIKit 离线推送解析逻辑，继续回调 – navigateToBuiltInChatViewController:groupID: 方法。 return NO;}

四、步骤1：厂商配置

参见 厂商配置 > Flutter，完成厂商配置。

注意：说明：

注意：应用内指定界面，请使用默认配置。

五、步骤2：客户端代码配置

参见 客户端代码配置，完成配置。

六、步骤3：处理消息点击回调，并解析参数

如果你需要自定义解析收到的远程推送，你可按照如下方法实现：

自定义点击跳转实现自定义点击跳转实现（旧方案）

注意：注册回调时机建议放在程序入口 main() 函数中。TIMPushListener timPushListener = TIMPushListener( onNotificationClicked: (String ext) { debugPrint("ext: $ext"); // 获取 ext 自定义跳转 } );tencentCloudChatPush.addPushListener(listener: timPushListener);

1. 请定义一个函数，用于接收推送消息点击回调事件.

该函数请定义成 {required String ext, String? userID, String? groupID} 的入参形式。

·其中，ext 字段，为该消息所携带的完整 ext 信息，由发送方指定，如果未指定，则有默认值。你可解析该字段，跳转至对应页面。

·userID 和 groupID 字段，为本插件，自动尝试解析 ext Json String， 获取里面携带的单聊对方 userID 和 群聊 groupID 信息。如果你未自定义 ext 字段，ext 字段由 SDK 或 UIKit 默认指定，则可使用此处的默认解析。如果尝试解析失败，则为 null 空。

你可定义一个函数来接收该回调，并据此跳转至对应会话页面或你的业务页面。

示例如下:

void _onNotificationClicked({required String ext, String? userID, String? groupID}) { print("_onNotificationClicked: $ext, userID: $userID, groupID: $groupID"); if (userID != null || groupID != null) { // 根据 userID 或 groupID 跳转至对应 Message 页面. } else { // 根据 ext 字段, 自己写解析方式, 跳转至对应页面. }}

2. 请注意，不要在 Flutter 程序入口的 main 方法中调用。

调用 TencentCloudChatPush().registerPush 方法成功后，就可以收到离线推送通知了。

TencentCloudChatPush().registerPush( onNotificationClicked: _onNotificationClicked, sdkAppId: 你的sdkAppId, appKey: "客户端密钥"， apnsCertificateID: 你配置的证书 ID);

七、步骤1：厂商配置

参见 厂商配置 > uni-app，完成厂商配置。

注意：说明：

注意：应用内指定界面，请使用默认配置。

八、步骤2：注册点击通知事件监听，进行自定义跳转。

在 App 启动时调用 addPushListener 注册 EVENT.NOTIFICATION_CLICKED 事件，回调中的 res 为发送端通过 ext 携带的推送扩展信息。解析后即可跳转到业务页面。以下示例只演示解析核心逻辑，跳转部分用 TODO 占位，请按自身业务补充：

import { addPushListener, EVENT } from '@/uni_modules/TencentCloud-Push';addPushListener(EVENT.NOTIFICATION_CLICKED, (res) => { console.log('notification clicked', res); if (!res) { return; } // 1. 解析 ext。res 为发送端通过 ext 携带的推送扩展信息，结构由业务自定义。 let data = res; if (typeof res === 'string') { try { data = JSON.parse(res); } catch (e) { console.error('parse ext failed', e); return; } } const conversationID = data.conversationID; const conversationType = data.conversationType; // 2. TODO: 根据业务字段跳转到目标页面。 // 若使用了 Chat / TUIKit，建议在用户登录成功后再跳转； // 冷启动场景可先把参数缓存起来，登录回调中再跳转。});

验证：点击通知后 EVENT.NOTIFICATION_CLICKED 回调被调用，且 res 内容与发送时设置的 ext 一致。如果回调未触发，请检查：控制台点击动作是否选择了打开应用内指定界面并保持默认填充值、监听器是否在 App 启动时注册、发送消息时是否设置了 ext。

九、步骤1: 厂商配置

参见 厂商配置 > React Native，完成厂商配置。

注意：说明：

注意：应用内指定界面，请使用默认配置。

十、步骤2: 获取离线推送扩展信息，进行自定义跳转。

import Push from '@tencentcloud/react-native-push';if (Push) { // 监听通知栏点击事件，获取推送扩展信息 Push.addPushListener(Push.EVENT.NOTIFICATION_CLICKED, (res) => { // res 为推送扩展信息 console.log('notification clicked', res); });}

十一、步骤1: 厂商配置

参见 厂商配置 > 微信小程序多端框架，完成厂商配置。

注意：应用内指定界面配置项，请使用默认配置，否则会收不到点击通知事件。

十二、步骤2: 注册点击通知事件监听，进行自定义跳转。

在小程序启动后，注册点击通知事件监听，用户点击通知后会收到点击通知事件，可根据扩展信息进行页面跳转。

const listener = (param) => { console.log('onEvent', JSON.stringify(param));}App({ onLaunch: function () { console.log('App Show') Push.addPushListener(Push.EventName.NOTIFICATION_CLICKED, listener); }}

收到离线推送后，通知栏会显示推送信息，单击通知栏可以自定义打开应用的界面。

十三、步骤1：厂商配置

参见 厂商配置 > HarmonyOS，完成厂商配置。

注意：说明：

注意：应用内指定界面，请使用默认配置。

十四、步骤2：获取离线推送扩展信息，进行自定义跳转。

注意：注册回调时机建议放在应用 UIAbility 的 onCreate() 函数中。

let pushListener: TIMPushListener = { onNotificationClicked: (data) => { const ext = data as string; console.info("onNotificationClicked: " + ext); // 获取 ext 自定义跳转 }}TIMPushManager.getInstance().addPushListener(pushListener);