Integrate the iOS Extension SDK

Complete example

The following example shows how to use CloudPushExtSDK in a Notification Service Extension:

// NotificationService.m
#import "NotificationService.h"
#import <CloudPushExtSDK/CloudPushExtSDK.h>

@interface NotificationService ()

@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request
                   withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {

    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    // 1. Initialize the SDK (use the same AppKey and AppSecret as the main application).
    [CloudPushExtSDK initWithAppKey:@"your_app_key" appSecret:@"your_app_secret"];

    // 2. Send the push delivery receipt.
    [CloudPushExtSDK sendNotificationExtensionAck:request
                                       completion:^(BOOL success) {
        // 3. Process the notification content (optional).
        self.bestAttemptContent.title = [NSString stringWithFormat:@"✓ %@", self.bestAttemptContent.title];

        // 4. Complete the notification processing.
        self.contentHandler(self.bestAttemptContent);
    }];
}

- (void)serviceExtensionTimeWillExpire {
    // Called when the system is about to terminate the extension service.
    self.contentHandler(self.bestAttemptContent);
}

@end

Key steps

1. Initialize the SDK: Initialize the SDK in the didReceiveNotificationRequest method.

2. Parameter consistency: The AppKey and AppSecret for initialization must match those used to initialize the CloudPushSDK in the main application.

3. Send receipt: Call sendNotificationExtensionAck to send the delivery receipt.

4. Handle the callback: Implement your custom notification processing logic in the callback.

5. Call contentHandler: Make sure to call contentHandler at the end to complete the notification processing.

Side effects

When you use this SDK to send a delivery receipt, the notification is displayed only after the receipt is reported. This can cause a delay of several seconds before the notification appears.

Initialization parameter consistency

Ensure that the initialization parameters for the extension SDK are consistent with the main application:

• The AppKey and AppSecret must be identical to the parameters used to initialize CloudPushSDK in the main application.

• Inconsistent parameters will prevent the delivery receipt from being reported, which affects the accuracy of push statistics.

• Define these parameters as constants and share them between the main application and the extension.

// Recommended practice: Define shared constants
// Constants.h
extern NSString * const kCloudPushAppKey;
extern NSString * const kCloudPushAppSecret;

// Constants.m
NSString * const kCloudPushAppKey = @"your_app_key";
NSString * const kCloudPushAppSecret = @"your_app_secret";

// Use these constants in both the main application and the extension
[CloudPushSDK initWithAppKey:kCloudPushAppKey appSecret:kCloudPushAppSecret];
[CloudPushExtSDK initWithAppKey:kCloudPushAppKey appSecret:kCloudPushAppSecret];

Extension service time limit

• Total running time: An iOS extension service has a total running time limit of 30 seconds.

• Receipt reporting time: The SDK can take up to 17 seconds to report a delivery receipt. This includes 3 retries, with each retry having a 5 second timeout and a 1 second retry interval.

• Custom logic time: If you have custom notification processing logic, ensure that its execution time does not exceed 10 seconds.

• Timeout consequences: If the total time exceeds 30 seconds, the system will forcibly terminate the extension process. This can cause the following issues:

  • The delivery receipt fails to report.

  • Notification content modifications are lost.

  • The system limits the launch frequency of the extension service.

Lifecycle management

• Use the callback: Ensure that you call contentHandler only after the network request is complete.

• Avoid premature exit: If you call contentHandler before the asynchronous request finishes, the system will immediately terminate the extension process.

• Error handling: Even if the delivery receipt fails to report, you must still call contentHandler to complete the notification processing.

Environment limits

• This SDK applies only to the iOS Notification Service Extension environment.

• This SDK is not supported for use in the main application. Instead, use the full version of CloudPushSDK.

• When you use Advanced Push or PushV2 - Advanced Push to send iOS notifications, enable the notification extension capability.

Feature limits

• This SDK provides only the push confirmation feature.

• Does not include full push features such as device registration or tag management.

• Does not support local notification processing.

• You can view extension delivery receipts in the receipt log. The event type is ext_ack. For more information, see Receipt Log.

Network requirements

• Requires network connectivity to send confirmation requests.

• Supports the HTTP and HTTPS protocols.

• It can be used on a Wi-Fi or cellular network.

Error handling

The SDK has a built-in error handling mechanism that includes:

• Parameter validation

• Network exception handling

• Automatic retry mechanism

Performance optimization

• Asynchronous processing: All network requests run on a background thread.

• Memory optimization: The SDK is optimized for minimal memory usage.

• Quick launch: The initialization process is optimized to reduce the startup time of the extension service.

Debugging tips

• You can enable console logs to view the running status of the SDK.

• You can check whether the userInfo of the push message contains the required fields.

• You can confirm the network connectivity status.

Initialization method

• CloudPushExtSDK/initWithAppKey:appSecret:

Message confirmation

• CloudPushExtSDK/sendNotificationExtensionAck:completion: