tencent cloud


Notification Service Extension

Last updated: 2024-01-16 17:42:20


    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 a Notification Service 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 10.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 Tencent Push Notification Service Extension Libraries (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 the Podfile. The display effect after the configuration item is added in the Podfile is as shown below:
    target `XXServiceExtension'do
    pod 'TPNS-iOS-Extension' , '~> Version' // The version must be consistent with the primary SDK (TPNS-iOS) version.

    Method 2: Manually integrate

    2. In the left sidebar, choose Toolbox > SDK Download.
    3. On the SDK Download page, select the iOS platform and click Download.
    4. Decompress the SDK package, go to the demo > sdk > XGPushStatistics > extension directory, and obtain the XGExtension.h and libXGExtension.a files.
    5. Add the XGExtension.h and libXGExtension.a files obtained to the notification service extension target:
    System library: libz.tbd
    Tencent Push Notification Service extension library: libXGExtension.a
    After the integration, the directory structure is as follows:

    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 homebrew repository of Tencent Push Notification Service.
    brew tap tpns/serviceExtension https://github.com/TencentCloud/homebrew-tpnsServiceExtension.git
    2. Install new_tpns_svc_ext.
    brew install new_tpns_svc_ext
    3. Install the notification service extension plug-in for Tencent Push Notification Service.
    new_tpns_svc_ext "AccessID" "AccessKey" "xxx.xcodeproj"
    Parameter description:
    AccessID: AccessID of your Tencent Push Notification Service product
    AccessKey: AccessKey of your Tencent Push Notification Service product
    xxx.xcodeproj: full path of .xcodeproj
    new_tpns_svc_ext "1600013400" "IWRNAHX6XXK6" "/Users/yanbiaomu/Developer/tencent/demo2/SDKToolObjcDemo2/SDKToolObjcDemo2.xcodeproj"
    To get AccessID and AccessKey, go to the Tencent Push Notification Service console, choose Product Management, and click Configuration Management in the record of a target product. Then you can find AccessID and AccessKey on the page displayed.
    4. Run the new_tpns_svc_ext command to verify the result.If the following result is displayed after the new_tpns_svc_ext command is run in the terminal, the notification extension plugin 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 plugin 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.
    Currently, the HomeBrew command new_tpns_svc_ext supports integrating only the notification service extension plugin TPNSService but not basic push capabilities.


    Calling the SDK's statistics reporting API

    1. Import the header file NotificationService into the notification extension class XGExtension.h.
    2. Call the following sample code in the callback method didReceiveNotificationRequest:withContentHandler:
    @brief //Tencent Push Notification Service processes rich media notifications and device-reached messages, that is, message receipts.
    @param request //Push request
    @param accessID //Tencent Push Notification Service application `AccessID`
    @param accessKey //Tencent Push Notification Service application `AccessKey`
    @param handler //Callback of processing messages. Process the associated rich media file in the callback method.
    (void)handleNotificationRequest:(nonnull UNNotificationRequest *)request
    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>;
    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 = @"tpns.hk.tencent.com"; /// Cluster in Hong Kong (China)
    // [XGExtension defaultManager].reportDomainName = @"tpns.sgp.tencent.com"; /// Cluster in Singapore
    // [XGExtension defaultManager].reportDomainName = @"tpns.sh.tencent.com"; /// 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;
    self.contentHandler(self.bestAttemptContent); // If you need to add business logic before the notification pops up, add it before calling ContentHandler.

    Integration Verification

    After completing the integration as instructed above, you can verify whether the extension plugin is successfully integrated in the following steps:
    1. Close the application and push a notification message to the phone.
    2. Without clicking the message, check whether the message arrives on the phone in the console. If there is arrival data, the integration is successful.


    If the device receives the pushed message but there is no arrival data, troubleshoot as follows:
    1. Run the primary target (demo example in the figure).
    2. Attach the implementation target (TPNSService-Cloud in the demo) of UNNotificationServiceExtension to the primary target by PID or Name.
    3. Add breakpoints at code lines 34 and 38 as shown in the figure, and send a notification for debugging. Note that the notification must be sent through the Apple Push Notification service (APNs) channel and that the mutable-content field in the notification content must be 1 (since Tencent Push Notification Service SDK v1.2.8.0, the APNs channel is used by default in the background, and the Tencent Push Notification Service channel is used in the foreground. To debug the notification service extension plugin, you need to make the application run in the background). If the breakpoints are executed, the debugging is successful. Otherwise, stop all targets and start over from step 1.


    Why is there no arrival report after I sent a notification?

    The notification service extension plugin must be integrated for client arrival reporting. If no arrival data is reported after integration, check whether AccessID and AccessKey of the primary project are consistent with those of the notification service extension plugin and whether the mutable-content field in the notification content in the web console or RESTful API is 1. Only when the two conditions checked are met, the notification service extension plugin on the client will be run, and arrival data will be reported.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support