通知服务扩展的使用说明

最后更新时间:2021-06-21 11:21:22

    简介

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

    添加 TPNS 扩展库(三选一)

    方式一:Cocoapods 集成

    通过 Cocoapods 下载地址:

    pod 'TPNS-iOS-Extension', '~> 版本'  // 如果不指定版本,则默认为本地 pod TPNS-iOS-Extension 最新版本
    

    使用说明:

    1. 创建类型为 Application ExtensionNotification Service Extension TARGET,例如 XXServiceExtension
    2. 在 Podfile 新增 XXServiceExtension 的配置栏目。
      Podfile 中增加配置项目后展示效果,示例如下:
      target ‘XXServiceExtension'do
       platform:ios,'10.0'
       pod 'TPNS-iOS-Extension' , '~>1.2.7.2' 
      end
      
      说明:

      建议配合 pod 'TPNS-iOS' version 1.2.7.2 及以上版本使用。

    方式二:手动集成

    1. 登录 腾讯移动推送控制台
    2. 在左侧导航栏中,单击【工具箱】>【SDK 下载】,进入 SDK 下载管理页面。
    3. 在 SDK 下载管理页面,选择 iOS 平台 ,单击【下载】。
    4. 解压缩 SDK 包,并依次打开 demo > sdk > XGPushStatistics > extension 目录,获取 XGExtension.hlibXGExtension.a 文件。
    5. 将获取到的 XGExtension.hlibXGExtension.a 文件添加至通知扩展 Target:
      • 添加系统库:libz.tbd
      • TPNS 扩展库:libXGExtension.a

    集成后的目录结构如下:

    方式三:HomeBrew 集成

    首次安装 new_tpns_svc_ext,请在终端执行下面的命令:

    1. 关联 TPNS homebrew 仓库。

      brew tap tpns/serviceExtension https://github.com/TencentCloud/homebrew-tpnsServiceExtension.git
      
    2. 安装 new_tpns_svc_ext 命令行。

      brew install new_tpns_svc_ext
      
    3. 安装 TPNS 通知扩展插件。

      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的获取方式:请在 【TPNS控制台】>【产品管理】>【选中您要配置推送能力的产品】>【配置管理】中,粘贴复制 AccessIDAccessKey 到命令行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: 中调用如下示例代码:
    objective-c
    /**
    @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 通道,通知的内容中 mutable-content 字段必须为1(TPNS SDK 1.2.8.0开始,后台默认使用 APNS 通道,前台使用 TPNS 自建通道,调试抵达插件需要将 App 退到后台后)。如果看到断点被执行了,说明调试成功,否则停止所有 Target,重新重第1步开始。

    常见问题

    为何发送通知后,却没有看到抵达上报?

    客户端抵达上报需要集成【通知扩展服务插件】。若集成后,还没有抵达数据上报,则需要排查主工程与抵达插件的 ACCESS ID 和 ACCESS KEY 是否一致。 且需要排查 Web 管理台或者 RestAPI 通知的内容中 mutable-content 字段是否为1。
    只有主工程与抵达插件的 ACCESS ID 和 ACCESS KEY 一致, 且 Web 管理台或者 RestAPI 通知的内容中 mutable-content 字段为1,才会运行客户端抵达插件,从而有抵达数据上报。