通知服务扩展的使用说明

最后更新时间：2025-07-17 11:04:04
通知服务扩展的使用说明
最后更新时间： 2025-07-17 11:04:04
简介
为了精准统计消息抵达率和接收富媒体消息，SDK 提供了 Service Extension 接口，可供客户端调用，从而可以监听消息的到达和接收富媒体消息，您可以按以下指引使用此功能。
创建通知拓展 Target
1. 在 xcode 菜单栏，选择 File > New > Target。
说明：
主工程的 Bundle Id 和 Service 的 Bundle Id 必须不同，且 Service 的 Bundle Id 必须以主工程的 Bundle Id 为前缀（例如，主工程的 Bundle Id：com.tencent.tpns，Service 的 Bundle Id：com.tencent.tpns.service）。
若主工程 Target 最低支持版本小于10.0，扩展 Target 系统版本设置为10.0。
若主工程 Target 最低支持版本大于10.0，则扩展 Target 系统版本与主工程 Target 版本一致。
﻿
﻿
﻿
2. 进入 Target 页面，选择 Notification Service Extension， 单击 Next。
﻿
﻿
3. 输入 Product Name，单击 Finish。
﻿
﻿
添加移动推送扩展库（三选一）
方式一：Cocoapods 集成
通过 Cocoapods 下载地址：
pod 'TPNS-iOS-Extension', '~> 版本'  // 如果不指定版本，则默认为本地 pod TPNS-iOS-Extension 最新版本
使用说明：
1. 创建类型为 Application Extension 的 Notification Service Extension TARGET，例如 XXServiceExtension。
2. 在 Podfile 新增 XXServiceExtension 的配置栏目。
Podfile 中增加配置项目后展示效果，示例如下：
target ‘XXServiceExtension'do
  platform:ios,'10.0'
  pod 'TPNS-iOS-Extension' , '~> 版本' // 需要与主SDK（TPNS-iOS）版本保持一致
end
方式二：手动集成
1. 登录 腾讯移动推送控制台。
2. 在左侧导航栏中，单击工具箱 > SDK 下载，进入 SDK 下载管理页面。
3. 在 SDK 下载管理页面，选择 iOS 平台 ，单击下载。
4. 解压缩 SDK 包，并依次打开 demo > sdk > XGPushStatistics > extension 目录，获取 XGExtension.h 及 libXGExtension.a 文件。
5. 将获取到的 XGExtension.h及 libXGExtension.a 文件添加至通知扩展 Target：
添加系统库：libz.tbd
移动推送扩展库：libXGExtension.a
集成后的目录结构如下：
﻿
﻿
方式三：HomeBrew 集成
首次安装 new_tpns_svc_ext，请在终端执行下面的命令：
1. 关联 移动推送 homebrew 仓库。  
brew tap tpns/serviceExtension https://github.com/TencentCloud/homebrew-tpnsServiceExtension.git
2. 安装 new_tpns_svc_ext 命令行。  
brew install new_tpns_svc_ext
3. 安装移动推送通知扩展插件。  
new_tpns_svc_ext  "AccessID" "AccessKey" "xxx.xcodeproj"
参数说明：  
参数1：腾讯云-腾讯移动推送-您产品的 AccessID
参数2：腾讯云-腾讯移动推送-您产品的 AccessKey
参数3：.xcodeproj 的完整路径
使用示例：
new_tpns_svc_ext "1600013400" "IWRNAHX6XXK6" "/Users/yanbiaomu/Developer/tencent/demo2/SDKToolObjcDemo2/SDKToolObjcDemo2.xcodeproj"
说明：
 参数1、2的获取方式：请在 移动推送控制台>产品管理>选中您要配置推送能力的产品>配置管理中，粘贴复制 AccessID 和 AccessKey 到命令行new_tpns_svc_ext的参数1、2中。
﻿
﻿
1. 执行 new_tpns_svc_ext命令，进行结果验证。在终端执行 new_tpns_svc_ext 命令之后，如果输出如下结果，即说明集成通知扩展插件成功。  
TPNS service auto coding done!
New TPNSService Extension Success
升级 new_tpns_svc_ext 版本
当有新版本 SDK 通知扩展插件发布，可在终端执行如下命令进行升级：
brew update && brew reinstall new_tpns_svc_ext
说明：
您可以在 iOS 发布动态页 查看最新版本更新详情。
当前 homebrew 命令 new_tpns_svc_ext 只支持集成通知扩展插件 TPNSService，暂不支持基础推送能力的集成。
使用方式
调用 SDK 统计上报接口
1. 在通知扩展类 NotificationService 引入头文件 XGExtension.h。
2. 在回调方法 didReceiveNotificationRequest:withContentHandler: 中调用如下示例代码：
  /**
 @brief TPNS处理富媒体通知和抵达到终端的消息，即消息回执
 @param request 推送请求
 @param accessID TPNS应用 accessId
 @param accessKey TPNS应用 accessKey
 @param handler 处理消息的回调，回调方法中处理关联的富媒体文件
 */
  - (void)handleNotificationRequest:(nonnull UNNotificationRequest *)request
                           accessID:(uint32_t)accessID
                           accessKey:(nonnull NSString *)accessKey
                   contentHandler:(nullable void (^)(NSArray<UNNotificationAttachment *> *_Nullable attachments, NSError *_Nullable error))handler；
示例代码
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent *_Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
     /// 非广州集群，请开启对应集群配置（广州集群无需使用）
    //  [XGExtension defaultManager].reportDomainName = @"tpns.hk.tencent.com"; /// 中国香港集群
    //  [XGExtension defaultManager].reportDomainName = @"tpns.sgp.tencent.com";  /// 新加坡集群
    //  [XGExtension defaultManager].reportDomainName = @"tpns.sh.tencent.com";  /// 上海集群
    [[XGExtension defaultManager] handleNotificationRequest:request accessID:<your accessID> accessKey:<your accessKey
        > contentHandler:^(NSArray<UNNotificationAttachment *> * _Nullable attachments, NSError * _Nullable error) {
        self.bestAttemptContent.attachments = attachments;
        self.contentHandler(self.bestAttemptContent);  // 如果需要在弹出通知前增加业务逻辑，请在contentHandler调用之前处理。
    }];
}
接入验证
在您按以上流程完成接入后，可按如下步骤验证插件接入是否成功：
1. 关闭应用，给手机推送一条通知消息。
2. 在不点击的情况下，管理台查看消息抵达情况。
若有抵达数据，表示集成成功。
﻿
﻿
调试方式
若设备收到推送，但无抵达数据，可按照以下步骤进行调试：
1. 运行主 Target（图中为 Demo 示例）
﻿
﻿
2. 通过 PID 或者 Name 将 UNNotificationServiceExtension 的实现 Target（Demo 中抵达插件为 TPNSService-Cloud）连接到主 Target。
﻿
﻿
3. 在如图代码34行、38行的位置加断点，发送一条通知配合调试，注意需要使用 APNs (Apple Push Notification service) 通道，通知的内容中 mutable-content 字段必须为1（移动推送SDK 1.2.8.0开始，后台默认使用 APNs 通道，前台使用移动推送自建通道，调试抵达插件需要将 App 退到后台后）。如果看到断点被执行了，说明调试成功，否则停止所有 Target，重新重第1步开始。
﻿
﻿
常见问题
为何发送通知后，却没有看到抵达上报？
客户端抵达上报需要集成通知扩展服务插件。若集成后，还没有抵达数据上报，则需要排查主工程与抵达插件的 ACCESS ID 和 ACCESS KEY 是否一致。 且需要排查 Web 管理台或者 RestAPI 通知的内容中 mutable-content 字段是否为1。
只有主工程与抵达插件的 ACCESS ID 和 ACCESS KEY 一致， 且 Web 管理台或者 RestAPI 通知的内容中 mutable-content 字段为1，才会运行客户端抵达插件，从而有抵达数据上报。