Notification Service Extension Use Instructions

Last updated: 2020-12-14 11:47:12


    To accurately count the message reach rate and receive rich media messages, the SDK provides the Service Extension API that can be called by the client to listen on message arrivals and receive rich media messages. You can use this feature in the following steps:

    Creating Notification Extension Target

    1. In the Xcode menu bar, select File > New > Target.


      • The bundle ID of the primary project must be different from that of the service, and the latter must be prefixed with the former (for example, the former is com.tencent.tpns and the latter is com.tencent.tpns.service).
      • If the lowest version supported by the target of the primary project is below 10.0, set the extension target system version to v10.0.
      • If the lowest version supported by the target of the primary project is above 10.0, the extension target system version should be the same as the primary project target version.

    2. Enter the "Target" page, select Notification Service Extension, and click Next.

    3. Set "Product Name" and click Finish.

    Adding TPNS Extension Library (Three Methods)

    Method 1. Integrate through CocoaPods

    Download through Cocoapods:

    pod 'TPNS-iOS-Extension', '~> version'  // If the version is not specified, the latest version of the local pod TPNS-iOS-Extension will be downloaded

    Use instructions:

    1. Create a Notification Service Extension target in Application Extension type, such as XXServiceExtension.
    2. Add the configuration item of XXServiceExtension in Podfile.
      The display effect after the configuration item is added in Podfile is as shown below:
      target ‘XXServiceExtension'do
        pod 'TPNS-iOS-Extension' , '~>' 


    We recommend you use it together with pod 'TPNS-iOS' version or above.

    Method 2. Manually integrate

    Select the notification extension target and add the following dependent library files:

    • Add system libraries: libz.tbd, libsqlite3.tbd
    • Add the TPNS extension library: libXGExtension.a

    Method 3. Integrate through HomeBrew

    To install new_tpns_svc_ext for the first time, please run the following command in the terminal:

    1. Associate the TPNS homebrew repository.
      brew tap tpns/serviceExtension
    2. Install the new_tpns_svc_ext command line.
      brew install new_tpns_svc_ext
    3. Install the TPNS notification extension.
      new_tpns_svc_ext  "AccessID" "AccessKey" "xxx.xcodeproj"

    Parameter description:

    • Parameter 1: Tencent Cloud > TPNS > AccessID of your product
    • Parameter 2: Tencent Cloud > TPNS > AccessKey of your product
    • Parameter 3: full path of .xcodeproj


    new_tpns_svc_ext "1600013400" "IWRNAHX6XXK6" "/Users/yanbiaomu/Developer/tencent/demo2/SDKToolObjcDemo2/SDKToolObjcDemo2.xcodeproj"


    How to get parameters 1 and 2: go to TPNS Console > Product Management, select the product for which to configure the push capabilities, click Configuration Management, and copy and paste AccessID and AccessKey to parameters 1 and 2 of the new_tpns_svc_ext command line.

    1. Run the new_tpns_svc_ext command to verify the result.
      After running the new_tpns_svc_ext command in the terminal, if the following result is output, it means that the notification extension is successfully integrated.
      TPNS service auto coding done!
      New TPNSService Extension Success

    Upgrading new_tpns_svc_ext

    When a new version of the SDK notification extension is released, you can run the following command in the terminal for upgrade:

    brew update && brew reinstall new_tpns_svc_ext


    • You can view the release notes of the latest version in SDK for iOS Updates.
    • Currently, the homebrew command new_tpns_svc_ext only supports integrating the notification extension TPNSService but not the basic push capabilities.


    Calling SDK's statistics reporting API

    1. Import the header file XGExtension.h into the notification extension class NotificationService.
    2. Call the following sample code in the callback method didReceiveNotificationRequest:withContentHandler::
      @brief   TPNS's processing of rich media notification and message arriving at device, i.e., message receipt
      @param request   Push request
      @param accessID   TPNS application `accessId`
      @param accessKey   TPNS application `accessKey`
      @param handler   Callback for message processing. The associated rich media file is processed in the callback method
      - (void)handleNotificationRequest:(nonnull UNNotificationRequest *)request
                              accessKey:(nonnull NSString *)accessKey
                      contentHandler:(nullable void (^)(NSArray<UNNotificationAttachment *> *_Nullable attachments, NSError *_Nullable error))handler;

    Sample code

    - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent *_Nonnull))contentHandler {
        self.contentHandler = contentHandler;
        self.bestAttemptContent = [request.content mutableCopy];
         /// For clusters outside Guangzhou, please enable the corresponding cluster configuration (not required for clusters in Guangzhou)
        //  [XGExtension defaultManager].reportDomainName = @""; /// Cluster in Hong Kong (China)
        //  [XGExtension defaultManager].reportDomainName = @"";  /// Cluster in Singapore
        //  [XGExtension defaultManager].reportDomainName = @"";  /// Cluster in Shanghai
        [[XGExtension defaultManager] handleNotificationRequest:request accessID:<your accessID> accessKey:<your accessKey
            > contentHandler:^(NSArray<UNNotificationAttachment *> * _Nullable attachments, NSError * _Nullable error) {
            self.bestAttemptContent.attachments = attachments;

    Integration Verification

    After you complete the integration as instructed above, you can verify whether the extension is successfully integrated in the following steps:

    Arrival statistics

    Close the application and push a notification message to the phone. Without clicking the message, check in the console whether it arrives. If there is arrival data, the integration is successful.

    Pushing rich media message

    Close the application, push a rich media message with an image, and check whether the image is displayed when the message arrives on the phone. If it is not displayed, you can troubleshoot as follows:

    1. Select Service Target, make sure that the target's system version is lower than that of the device, and click the Run icon.

    2. Select the primary target to mount.

    3. Select the notification extension class, add the related print log, and check the print result. If an attachment (rich media push) is returned normally and error is nil, the push is successful.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback