tencent cloud

简介

为了精准统计消息抵达率和接收富媒体消息，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中。

4. 执行 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 <span class="hljs-keyword">void</span> (^)(NSArray&lt;UNNotificationAttachment *> *_Nullable attachments, NSError *_Nullable <span class="hljs-keyword">error</span>))<span class="hljs-keyword">handler</span>；
  

示例代码

- (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，才会运行客户端抵达插件，从而有抵达数据上报。