产品动态

公告

产品功能动态

Android SDK 发布动态

iOS SDK 发布动态

macOS SDK 发布动态

产品简介

产品概述

产品优势

应用场景

全球化部署

购买指南

价格总览

购买指引

计费模式

免费试用

欠费说明

快速入门

创建产品和应用

Android 快速接入

iOS 快速接入

创建推送任务

查询推送记录

推送测试方法指引

产品限制说明

操作指南

推送管理

推送高级功能

实践教程

iOS 平台角标功能实践

API 文档

简介

API 概览

调用方式

推送相关接口

标签相关接口

账号相关接口

统计相关接口

用户属性相关接口

服务端错误码

服务端 SDK

API（Java）

SDK 文档

Android 接入指南

iOS 接入指南

客户端集成插件

macOS接入指南

用户及权限

快速入门配置

进阶自定义配置

资源标签

服务协议

服务等级协议

开发者协议

常见问题

iOS 常见问题

Android 常见问题

Flutter 常见问题

其他问题

移动推送政策

移动推送隐私协议

TPNS 数据处理和安全协议

Developer Agreement

联系我们

词汇表

通知服务扩展的使用说明

PDF

聚焦模式

字号

最后更新时间： 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，才会运行客户端抵达插件，从而有抵达数据上报。