iOS Extension SDK集成

完整示例

以下是在通知服务扩展中使用 CloudPushExtSDK 的完整示例：

// 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. 初始化 SDK（使用与主应用相同的 AppKey 和 AppSecret）
    [CloudPushExtSDK initWithAppKey:@"your_app_key" appSecret:@"your_app_secret"];

    // 2. 发送推送确认回执
    [CloudPushExtSDK sendNotificationExtensionAck:request
                                       completion:^(BOOL success) {
        // 3. 处理通知内容（可选）
        self.bestAttemptContent.title = [NSString stringWithFormat:@"✓ %@", self.bestAttemptContent.title];

        // 4. 完成通知处理
        self.contentHandler(self.bestAttemptContent);
    }];
}

- (void)serviceExtensionTimeWillExpire {
    // 系统即将终止扩展服务时调用
    self.contentHandler(self.bestAttemptContent);
}

@end

关键步骤说明

1. 初始化 SDK：在 didReceiveNotificationRequest 方法中首先初始化 SDK

2. 参数一致性：初始化时使用的 AppKey 和 AppSecret 必须与主应用中 CloudPushSDK 的初始化参数保持一致

3. 发送回执：调用 sendNotificationExtensionAck 发送确认回执

4. 处理回调：在回调中完成自定义通知处理逻辑

5. 调用 contentHandler：确保最终调用 contentHandler 完成通知处理

副作用说明

使用本 SDK 发送回执时，通知会在回执上报完毕之后才显示。这可能导致您的通知延迟数秒显示。

初始化参数一致性

必须确保扩展 SDK 的初始化参数与主应用保持一致：

• AppKey 和 AppSecret 必须与主应用中 CloudPushSDK 的初始化参数完全相同

• 参数不一致会导致推送回执上报失败，影响推送统计数据的准确性

• 建议将这些参数定义为常量，在主应用和扩展中共享使用

// 推荐做法：定义共享常量
// Constants.h
extern NSString * const kCloudPushAppKey;
extern NSString * const kCloudPushAppSecret;

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

// 在主应用和扩展中都使用这些常量
[CloudPushSDK initWithAppKey:kCloudPushAppKey appSecret:kCloudPushAppSecret];
[CloudPushExtSDK initWithAppKey:kCloudPushAppKey appSecret:kCloudPushAppSecret];

扩展服务时间限制

• 总执行时间：iOS 扩展服务有 30 秒的总执行时间限制

• 回执上报耗时：SDK 回执上报理论最长耗时约 17 秒（包含 3 次重试，每次 5 秒超时 + 1 秒重试间隔）

• 自定义逻辑时间：如果有自定义通知处理逻辑，建议控制在 10 秒以内

• 超时后果：如果总时间超过 30 秒，系统会强制终止扩展进程，可能导致：

  • 回执上报失败

  • 通知内容修改丢失

  • 扩展服务被系统限制启动频率

生命周期管理

• 必须使用回调：确保在网络请求完成后再调用 contentHandler

• 避免过早退出：如果在异步请求完成前调用 contentHandler，系统会立即终止扩展进程

• 错误处理：即使回执上报失败，也应该调用 contentHandler 完成通知处理

环境限制

• 仅适用于 iOS 通知服务扩展（Notification Service Extension）环境

• 不支持主应用中使用（请使用完整版 CloudPushSDK）

• 在使用Push - 高级推送或者PushV2 - 高级推送推送iOS通知时，请启用扩展通知能力

功能限制

• 仅提供推送确认功能

• 不包含设备注册、标签管理等完整推送功能

• 不支持本地通知处理

• 扩展回执请在回执日中进行查看，事件类型为ext_ack，参见回执日志

网络要求

• 需要网络连接以发送确认请求

• 支持 HTTP/HTTPS 协议

• 建议在 Wi-Fi 或蜂窝网络环境下使用

错误处理

SDK 内置了完善的错误处理机制，包括：

• 参数验证

• 网络异常处理

• 自动重试机制

性能优化

• 异步处理：所有网络请求均在后台线程执行

• 内存优化：使用最小化的内存占用

• 快速启动：优化初始化流程，减少扩展服务启动时间

调试建议

• 开启控制台日志查看 SDK 运行状态

• 检查推送消息的 userInfo 是否包含必要字段

• 确认网络连接状态

初始化方法

• CloudPushExtSDK/initWithAppKey:appSecret:

消息确认

• CloudPushExtSDK/sendNotificationExtensionAck:completion: