iOS SDK API接口

iOS SDK API接口

1. 初始化服务

+ (void)startSdkWithAppId:(NSString *)appid appKey:(NSString *)appKey appSecret:(NSString *)appSecret delegate:(id<GeTuiSdkDelegate>)delegate launchingOptions:(NSDictionary * __nullable)launchOptions;

参数:

  • appid: 个推登记应用的appid
  • appKey:个推登记应用的appKey
  • appSecret:个推登记应用的appSecret
  • delegate:个推SDK回调代理
  • launchOptions:传入didFinishLaunchingWithOptions中的launchOptions参数

说明:

  • 初始化个推服务,接口调用后个推服务后台运行,联网成功后,通过GeTuiSdkDelegate回调接口返回 cid 信息。
  • appid、appKey 和 appSecret 必须正确,否则会导致推送消息无法接收。
  • 该方法需要在主线程中调用。
  • launchOptions用于回执报表统计。

头文件:

  • GeTuiSdk.h

接口调用示例:

[GeTuiSdk startSdkWithAppId:kGtAppId appKey:kGtAppKey appSecret:kGtAppSecret delegate:self launchingOptions:launchingOptions];
// 通过 appId、 appKey 、appSecret 启动SDK,注:该方法需要在主线程中调用

请求结果处理示例:

/// [ GTSDK回调 ] SDK启动成功返回cid
- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId {
    NSLog(@"[ TestDemo ] [GTSdk RegisterClient]:%@", clientId);
}

2. 注册远程通知

+ (void)registerRemoteNotification:(UNAuthorizationOptions)types;

参数:

  • types: UNAuthorizationOptions类型的通知选项

说明:

  • 必须使用个推注册远程通知,否则通过个推代理无法获取部分APNs回调!!
  • 注意,个推内部自动关联DeviceToken和cid,无需开发者手动调用[GeTuiSdk registerDeviceTokenData:deviceToken]关联。
  • 该方法需要在主线程中调用。个推内部兼容iOS10以下注册远程通知逻辑,开发者无需特殊处理。

头文件:

  • GeTuiSdk.h

接口调用示例:

UNAuthorizationOptions types = (UNAuthorizationOptionBadge |
                                    UNAuthorizationOptionAlert |
                                    UNAuthorizationOptionSound);
[GeTuiSdk registerRemoteNotification:types];

3. 监听在线状态

- (void)GeTuiSDkDidNotifySdkState:(SdkStatus)status;

参数:

  • status:SDK运行的状态
  • SdkStatusStarting 正在启动
  • SdkStatusStarted 启动
  • SdkStatusStoped 停止
  • SdkStatusOffline 离线

说明:

  • 监控SDK运行状态, SDK初始化到cid登入成功为正在启动状态, cid登入成功后为启动状态。

示例:

- (void)GeTuiSDkDidNotifySdkState:(SdkStatus)status {
    NSLog(@"[GetuiSdk Status]:%u", status);
}

4. 展示APNs通知

- (void)GeTuiSdkNotificationCenter:(UNUserNotificationCenter *)center
           willPresentNotification:(UNNotification * )notification
             completionHandler:(void (^) (UNNotificationPresentationOptions))completionHandler;

参数:

  • center: 通知中心实例
  • notification: 接收到的APNs通知内容
  • completionHandler: 是否展示通知回调详情block

说明:

  • 支持iOS10及以上,App在前台时收到APNs通知后的展示回调。用户可以设定当前通知的展示权限。
  • 本方法接管了系统的userNotificationCenter: willPresentNotification: withCompletionHandler:展示回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]

头文件:

  • GeTuiSdk.h

接口调用示例:

- (void)GeTuiSdkNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification completionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APNs] %@ \n%@", NSStringFromSelector(_cmd), notification.request.content.userInfo];
    [self.homePage logMsg:msg];
    // [ 参考代码,开发者注意根据实际需求自行修改 ] 根据APP需要,判断是否要提示用户Badge、Sound、Alert等
    //completionHandler(UNNotificationPresentationOptionNone); 若不显示通知,则无法点击通知
    completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionAlert);
}

5. 接收APNs通知

- (void)GeTuiSdkDidReceiveNotification:(NSDictionary *)userInfo
                    notificationCenter:(nullable UNUserNotificationCenter *)center
                              response:(nullable UNNotificationResponse *)response
                fetchCompletionHandler:(nullable void (^)(UIBackgroundFetchResult))completionHandler;

参数:

  • userInfo:通知内容
  • center:UNUserNotificationCenter(iOS10及以上版本)
  • response:UNNotificationResponse(iOS10及以上版本)
  • fetchCompletionHandler:用来在后台状态下进行操作(iOS10以下版本)

说明:

  • APNs接收通知回调。
  • 本方法接管了系统的application: didReceiveRemoteNotification: fetchCompletionHandler:
    userNotificationCenter: didReceiveNotificationResponse: withCompletionHandler: 通知回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]
  • 注意:如果你重写了application: didReceiveRemoteNotification: fetchCompletionHandler: 和 当前方法,要注意只保留一个completionHandler调用,调用多次可能多导致偶现crash。

头文件:

  • GeTuiSdk.h

示例:

- (void)GeTuiSdkDidReceiveNotification:(NSDictionary *)userInfo notificationCenter:(UNUserNotificationCenter *)center response:(UNNotificationResponse *)response fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APNs] %@ \n%@", NSStringFromSelector(_cmd), userInfo];
    [self.homePage logMsg:msg];
    if(completionHandler) {
        // [ 参考代码,开发者注意根据实际需求自行修改 ] 根据APP需要自行修改参数值
        completionHandler(UIBackgroundFetchResultNoData);
    }

- (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo fetchCompletionHandler:(void(^)(UIBackgroundFetchResult))completionHandler
{
    //注意,如果执行了上述代理方法中的completionHandler,就不要执行当前回调中的completionHandler。
    //防止两次调用completionHandler引起崩溃
    //completionHandler(UIBackgroundFetchResultNewData);
}

6. 接收透传消息

- (void)GeTuiSdkDidReceiveSlience:(NSDictionary *)userInfo
                        fromGetui:(BOOL)fromGetui
                          offLine:(BOOL)offLine
                            appId:(nullable NSString *)appId
                           taskId:(nullable NSString *)taskId
                            msgId:(nullable NSString *)msgId
           fetchCompletionHandler:(nullable void (^)(UIBackgroundFetchResult))completionHandler;

参数:

  • userInfo: 推送消息内容
  • fromGetui: YES: 个推通道,NO:苹果APNs通道
  • offLine: YES: 个推离线消息,NO: 个推在线消息
  • appId: 应用的appId
  • taskId: 推送消息的任务id
  • msgId: 推送消息的messageid
  • completionHandler: 用来在后台状态下进行操作(通过苹果APNs通道的消息 才有此参数值)

说明:

  • 通过个推发送透传消息时,如果下发时cid在线,GeTuiSdkDelegate将收到回调且offLine=NO。如果下发时cid离线,消息将存入个推离线服务器,通过苹果APNS发送静默消息通知。 cid在线后将收到本条消息且offLine=YES。
  • 本方法接管了系统的application: didReceiveRemoteNotification: fetchCompletionHandler:通知回调,处理来自苹果APNs的静默消息通知回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]
  • 个推在线渠道的点击数,需要您在客户端在线透传消息自处理展示后,自己监听点击动作,当客户端出现点击动作时,调用sendFeedbackMessage方法,上报actionid为60002的点击回执,以此来补全统计苹果在线个推渠道透传消息的点击数。
  • 静默通知相关说明

头文件:

  • GeTuiSdk.h

示例:

- (void)GeTuiSdkDidReceiveSlience:(NSDictionary *)userInfo fromGetui:(BOOL)fromGetui offLine:(BOOL)offLine appId:(NSString *)appId taskId:(NSString *)taskId msgId:(NSString *)msgId fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APN] %@ \nReceive Slience: fromGetui:%@ appId:%@ offLine:%@ taskId:%@ msgId:%@ userInfo:%@ ", NSStringFromSelector(_cmd), fromGetui ? @"个推消息" : @"APNs消息", appId, offLine ? @"离线" : @"在线", taskId, msgId, userInfo];
    [self.homePage logMsg:msg];

    if(completionHandler) {
        // [ 参考代码,开发者注意根据实际需求自行修改 ] 根据APP需要自行修改参数值
        completionHandler(UIBackgroundFetchResultNoData);
    }
}
//以下处理用于推送苹果在线透传消息时,补全上报个推渠道消息点击数;需通过上述userInfo的_gmid_中获取到taskId 和msgId,_gmid_组成格式是taskId:msgId:clientid,以冒号区分;在您自身点击事件逻辑触发时,执行上报埋点,点击id固定为60002。
// [GeTuiSdk sendFeedbackMessage:60002 andTaskId:taskId andMsgId:msgId];

7. 授权回调

- (void)GetuiSdkGrantAuthorization:(BOOL)granted error:(NSError *)error;

参数:

  • granted: 是否授权
  • error: 错误信息

说明:

  • 开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]
  • 用户的授权状态会通过回调GetuiSdkGrantAuthorization告知开发者。

头文件:

  • GeTuiSdk.h

示例:

- (void)GetuiSdkGrantAuthorization:(BOOL)granted error:(NSError *)error {
    NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APNs] %@ \n%@ %@", NSStringFromSelector(_cmd), @(granted), error];
    NSLog(@"%@", msg);
}

8. 通知设置回调

- (void)GeTuiSdkNotificationCenter:(UNUserNotificationCenter *)center
       openSettingsForNotification:(nullable UNNotification *)notification

参数:

  • center:UNUserNotificationCenter(iOS10及以上版本)
  • notification: 接收到的APNs通知内容

说明:

  • 支持iOS10及以上,注册远程通知时,若设置UNAuthorizationOptionProvidesAppNotificationSettings(此配置支持iOS12+),开发者可以申请自定义通知设置。在”设置“对应的通知设置中跳转到当前App的回调。
  • 本方法接管了系统的userNotificationCenter: openSettingsForNotification:通知设置回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]

头文件:

  • GeTuiSdk.h

9. 发送自定义回执

+ (BOOL)sendFeedbackMessage:(NSInteger)actionId andTaskId:(NSString *)taskId andMsgId:(NSString *)msgId;

参数:

  • actionId:用户自定义的actionid,int类型,取值90001-90999
  • taskId:下发任务的任务ID
  • msgId:下发任务的消息ID

返回:

  • BOOL: 发送成功 YES, 发送失败 NO,taskid 为空或者 messageid 为空 或者 actionid 不在取值范围以内。

说明:

第三方自定义回执,可用于数据统计。

头文件:

  • GeTuiSdk.h

示例:

/// [ GTSDK回调 ] SDK收到透传消息回调
- (void)GeTuiSdkDidReceivePayloadData:(NSData *)payloadData andTaskId:(NSString *)taskId andMsgId:(NSString *)msgId andOffLine:(BOOL)offLine fromGtAppId:(NSString *)appId {
    // [ GTSDK ]:汇报个推自定义事件(反馈透传消息)
    [GeTuiSdk sendFeedbackMessage:90001 andTaskId:taskId andMsgId:msgId];
}

10. APPLink 点击回执

+ (NSString*) handleApplinkFeedback:(NSURL* )webUrl;

参数:

  • webUrl: applink的 url 对象

返回:

  • 返回 weburl 中的 payload 信息

说明:

  • APPLink 用户点击回执。
  • 返回下发中的透传信息,开发者可在获取到payload内容后处理具体业务逻辑。
  • 该接口可统计APPLink用户点击次数。

头文件:

  • GeTuiSdk.h

示例:

/// [ 系统回调 ] APPLink回调
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray<id<UIUserActivityRestoring>> * __nullable restorableObjects))restorationHandler {
    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL *webUrl = userActivity.webpageURL;

        // [ GTSDK ]:处理个推APPLink回执统计
        // APPLink url 示例:https://link.gl.ink/getui?n=payload&p=mid, 其中 n=payload 字段存储用户透传信息,可以根据透传内容进行业务操作。
        NSString *payload = [GeTuiSdk handleApplinkFeedback:webUrl];
        if (payload) {
            NSLog(@"[ TestDemo ] 个推APPLink中携带的用户payload信息: %@,URL : %@", payload, webUrl);
            // TODO: 用户可根据具体 payload 进行业务处理
        }
    }
    return YES;
}

11. 关闭推送

+ (void)setPushModeForOff:(BOOL)isValue;

参数:

  • isValue:关闭推送模式功能,关闭推送 YES, 开启推送 NO,默认推送开启。

说明:

  • 客户端可以关闭服务器的推送功能,关闭后,服务器将不给该客户端发推送消息,默认推送开启。
  • 请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidSetPushMode:(BOOL)isModeOff error:(NSError *)error;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件:

  • GeTuiSdk.h

接口调用示例:

[GeTuiSdk setPushModeForOff:NO];

请求结果处理示例:

- (void)GeTuiSdkDidSetPushMode:(BOOL)isModeOff error:(NSError *)error {
    if (error) {
        NSString* errorInfo = [NSString stringWithFormat:@">>>[SetModeOff error]: %@", [error localizedDescription]];
        NSLog(@"GeTuiSdkDidSetPushMode with error : %@", errorInfo);
        return;
    }

    NSString* settingInfo = [NSString stringWithFormat:@">>>[GexinSdkSetModeOff]: %@", isModeOff ? @"开启" : @"关闭"];
    NSLog(@"%@", settingInfo);
}

12. 设置标签

+ (BOOL)setTags:(NSArray *)tags;
+ (BOOL)setTags:(NSArray *)tags andSequenceNum:(NSString *)aSn;

参数:

  • tags:NSString 的对象数组,不能为 nil。只能包含中文字符、英文字母、0-9、+-*.的组合(不支持空格)
  • aSn:用户自定义的请求序列号,用来唯一标识该动作。若不指定sn,会根据tags自动生成sn。建议每个设置标签操作设置不同的sn标识。

说明:

  • 设置一组标签,后续可使用该标签定向推送。
  • 需要在获取到 cid 之后调用。默认一天只能成功设置一次(可联系技术支持进行修改)。
  • 请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidSetTagsAction:(NSString *)sequenceNum result:(BOOL)isSuccess error:(NSError *)aError;

头文件:

  • GeTuiSdk.h

接口调用示例:

[GeTuiSdk setTags:@[@"标签1",@"标签2",@"标签3"]];
[GeTuiSdk setTags:@[@"标签1",@"标签2",@"标签3" andSequenceNum:@"seqtag-1"];

请求结果处理示例:

- (void)GeTuiSdkDidSetTagsAction:(NSString *)sequenceNum result:(BOOL)isSuccess error:(NSError *)aError {
    /*
     参数说明
     sequenceNum: 请求的序列码
     isSuccess: 操作成功 YES, 操作失败 NO
     aError.code:
     20001:tag 数量过大(单次设置的 tag 数量不超过 100)
     20002:调用次数超限(默认一天只能成功设置一次)
     20003:标签重复
     20004:服务初始化失败
     20005:setTag 异常
     20006:tag 为空
     20007:sn 为空
     20008:离线,还未登陆成功
     20009:该 appid 已经在黑名单列表(请联系技术支持处理)
     20010:已存 tag 数目超限
     20011:tag 内容格式不正确
     */
    NSLog(@"GeTuiSdkDidSetTagAction sequenceNum:%@ isSuccess:%@ error: %@", sequenceNum, @(isSuccess), aError);
}

13. 绑定别名

+ (void)bindAlias:(NSString *)alias andSequenceNum:(NSString *)aSn;

参数:

  • alias:别名名称,长度40字节,支持中、英文(区分大小写)、数字以及下划线
  • aSn: 绑定序列码,不为nil

说明:

  • 绑定别名,后续可以使用该别名进行定向推送,重复绑定以最后一次为准,两次调用的间隔需大于 5s,单个 cid 在 24 小时内限制调用50次。
  • 可用于与客户账号系统关联,建议将邮箱、昵称、手机号等用户标识设为别名
  • 使用场景:同一个账号(比如手机号)分别登陆在 A、B、C 三台设备上的同一个 APP, 产生了 3 个不同的 cid, 想让这三台设备同时接收到推送,就可以考虑使用该接口,让三台设备的三个 cid 都绑定同一个别名也就是你的账号(比如手机号),最多支持 10 台设备,也就是最多绑定 10 个 cid
  • 请求回调见 GeTuiSdkDelegate 中的
    GeTuiSdkDidAliasAction:(NSString *)action result:(BOOL)isSuccess sequenceNum:(NSString *)aSn error:(NSError *)aError;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件:

  • GeTuiSdk.h

接口调用示例:

[GeTuiSdk bindAlias:@"个推" andSequenceNum:@"seq-1"];

请求结果处理示例:

- (void)GeTuiSdkDidAliasAction:(NSString *)action result:(BOOL)isSuccess sequenceNum:(NSString *)aSn error:(NSError *)aError {
    /*
     参数说明
     isSuccess: 操作成功 YES, 操作失败 NO
     aError.code: 
     30001:操作别名失败,频率过快,两次调用的间隔需大于 5s
     30002:操作别名失败,参数错误
     30003:当前 cid 绑定别名次数超限
     30004:操作别名失败,未知异常
     30005:操作别名时,cid 未获取到
     30006:操作别名时,发生网络错误
     30007:别名无效
     30008:sn 无效 */
    if([action isEqual:kGtResponseBindType]) {
        NSLog(@"[ TestDemo ] bind alias result sn = %@, code = %@", aSn, @(aError.code));
    }
    if([action isEqual:kGtResponseUnBindType]) {
        NSLog(@"[ TestDemo ] unbind alias result sn = %@, code = %@", aSn, @(aError.code));
    }
}

14. 解绑别名

+ (void)unbindAlias:(NSString *)alias andSequenceNum:(NSString *)aSn andIsSelf:(BOOL) isSelf;

参数:

  • alias: 别名名称:长度40字节,支持中、英文(区分大小写)、数字以及下划线
  • aSn: 绑定序列码,不为nil
  • isSelf :是否只对当前cid有效,如果是YES,只对当前cid做解绑;如果是NO,对所有绑定该别名的cid列表做解绑

说明:

  • 解绑别名,两次调用的间隔需大于 5s。只能解绑与当前应用 cid 关联的别名,单个 cid 在 24 小时内限制调用50次。
  • 请求回调同绑定别名

  • GeTuiSdk.h

示例:

[GeTuiSdk unbindAlias:@"个推" andSequenceNum:@"seq-1" andIsSelf:YES];

15. 设置角标

+ (void)setBadge:(NSUInteger)value;

参数:

  • value:设置的角标值, 取值范围:[0, 99999]

说明:

  • 同步服务器角标计数。
  • APP角标显示需额外调用 [[UIApplication sharedApplication] setApplicationIconBadgeNumber:badge] 进行设置。

头文件:

  • GeTuiSdk.h

示例:

[GeTuiSdk setBadge:5];

//如果需要角标显示需要调用系统方法设置
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:5];

16. 复位角标

+ (void)resetBadge;

说明:

  • 设置服务器角标计数为0。
  • APP角标复位需额外调用 [[UIApplication sharedApplication] setApplicationIconBadgeNumber:0] 进行设置。

头文件:

  • GeTuiSdk.h

示例:

//重置角标
[GeTuiSdk resetBadge];

//如果需要角标清空需要调用系统方法设置
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];

17. 清空通知

+ (void)clearAllNotificationForNotificationBar;

说明:

  • 清空下拉通知栏全部通知,并将角标置 0,即不显示角标。

头文件:

  • GeTuiSdk.h

示例:

 //清空通知和角标
 [GeTuiSdk clearAllNotificationForNotificationBar];

18. 获取缓存CID

+ (NSString *)clientId;

返回:

  • clientId: NSString* 个推唯一 ID,用于标识当前应用

说明:

  • 获取当前用户缓存的 cid(长时间未登录或 AppId 发生变化造成的 cid 变化以17. 获取回调CID接口中的 cid 为准)

头文件:

  • GeTuiSdk.h

示例:

[GeTuiSdk clientId];

19. 获取个推CID

- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId;

参数:

  • clientId:个推唯一 ID,用于标识当前应用

说明:

  • 启动GeTuiSdk后,SDK会自动向个推服务器注册SDK,当成功注册时,SDK通知应用注册成功获取到cid。
  • 注册成功仅表示推送通道建立,如果appid/appkey/appSecret等验证不通过,依然无法接收到推送消息,请确保验证信息正确。
  • 请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件:

  • GeTuiSdk.h

示例:

- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId {
    NSLog(@"[GetuiSDK ClientId]:%@", clientId);
}

20. 获取 SDK 服务状态

+ (SdkStatus)status;

返回:

  • SdkStatus:sdk状态
  • SdkStatusStarting 正在启动
  • SdkStatusStarted 启动
  • SdkStatusStoped 停止
  • SdkStatusOffline 离线

    说明:

  • 获取当前 SDK 的服务状态。

头文件:

  • GeTuiSdk.h

示例:

[GeTuiSdk status];

21. 获取 SDK 版本号

+ (NSString *)version;

返回:

  • NSString*:当前 SDK 版本号字符串

说明:

  • 获取当前 SDK 版本号

头文件:

  • GeTuiSdk.h

示例:

[GeTuiSdk version];

22. 设置渠道

+ (void)setChannelId:(NSString *)channelId;

参数:

  • channelId: 渠道信息

说明:

  • 根据用户分发的渠道进行设置,个推后台可根据渠道信息进行统计分析,生成报表。

头文件:

  • GeTuiSdk.h

示例:

 //设置渠道信息
 [GeTuiSdk setChannelId:@"GT-Channel"];

23. 注册 VOIPToken

+ (BOOL)registerVoipTokenCredentials:(NSData *)voipToken;

参数:

  • voipToken:传入iOS系统回调的voipToken

说明:

  • 在iOS8,苹果引入了一个新的被用于 VoIP APP 类型的推送消息。收到 VOIP 推送时,若APP在后台则会执行相关系统回调函数,若APP杀死状态则将被唤醒并执行相关系统回调函数。个推 VOIP 服务通过该接口注册 VoipToken,从而进行 VOIP 推送服务。

头文件:

  • GeTuiSdk.h

示例:

/// [ 系统回调 ]
- (void)pushRegistry:(PKPushRegistry *)registry didUpdatePushCredentials:(PKPushCredentials *)credentials forType:(NSString *)type {
    //向个推服务器注册 VoipToken
    [GeTuiSdk registerVoipTokenCredentials:credentials.token];
}

24. VOIP推送消息回执

+ (void)handleVoipNotification:(NSDictionary *)payload;

参数:

  • payload:VOIP 推送中携带的payload信息

说明:

  • 接收 VOIP 消息后调用,统计 VOIP 推送到达数。

警告:在iOS 13 之后 Apple不再允许PushKit应用在非Voip电话的场景下,如果需要使用Pushkit则需要接入Callkit的接口。若需要实现语音播报功能,建议通过通知扩展实现,具体参考官方Demo;

头文件:

  • GeTuiSdk.h

示例:

/// [ 系统回调 ]
- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(NSString *)type {
    //TODO:接收 VOIP 推送中的 Payload 信息进行业务处理。
    NSLog(@"[Voip Payload]:%@,%@", payload, payload.dictionaryPayload);

    //调用个推 VOIP 回执统计接口
    [GeTuiSdk handleVoipNotification:payload.dictionaryPayload];
}

25. 设置后台运行

+ (void)runBackgroundEnable:(BOOL)isEnable;

参数:

  • isEnable:YES:允许,app进入后台后,sdk执行保活逻辑,维持socket通道连接; NO:不允许,app进入后台后,sdk会主动断开socket通道等
  • 默认不设置,app进入后台后, sdk不会执行保活逻辑,也不会断开socket通道,等待系统自动断开socket通道

说明:

  • 设置是否允许后台运行

头文件:

  • GeTuiSdk.h

示例:

[GeTuiSdk runBackgroundEnable:YES];

26. 地理围栏功能

+ (void)lbsLocationEnable:(BOOL)isEnable andUserVerify:(BOOL)isVerify;

参数:

  • isEnable:设置地理围栏功能是否运行,YES:允许,NO:不允许。默认为 NO。
  • isVerify:设置是否SDK主动弹出用户定位请求,YES:允许,NO:不允许。默认为 NO。

说明:

  • 本功能为使用个推2.0智能标签和个推3.0应景推送的必选功能,建议勾选

头文件:

  • GeTuiSdk.h

示例:

[GeTuiSdk lbsLocationEnable:YES andUserVerify:YES];

27. 发送上行消息

+ (NSString *)sendMessage:(NSData *)body error:(NSError **)error;

+ (NSString *)sendMessage:(NSData *)body taskId:(NSString *)taskId error:(NSError **)error;

参数:

  • body: 发送的数据。
  • taskId: 任务ID,UUIDString,非必填。
  • error: 如果发送错误给出错误消息。

返回:

  • NSString*:如果发送成功返回messageid,发送失败返回nil。

说明:

  • 请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidSendMessage:(NSString *)messageId result:(int)result;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件:

  • GeTuiSdk.h

接口调用示例:

 NSError *aError = nil;
 NSData *sendData = [@"sendMessage" dataUsingEncoding:NSUTF8StringEncoding];
 [GeTuiSdk sendMessage:sendData error:&aError]

请求结果处理示例:

- (void)GeTuiSdkDidSendMessage:(NSString *)messageId result:(int)result {
    //消息推送到个推服务器,服务器通过该接口通知sdk到达结果,result 为1 说明消息发送成功,0为失败。
    //注意: 需第三方服务器接入个推,SendMessage 到达第三方服务器后返回 1。
    NSString *msg = [NSString stringWithFormat:@"Received sendmessage:%@ result:%d", messageId, result];
    NSLog(@"[ TestDemo ] [GeTuiSdk DidSendMessage]:%@\n\n",msg);
}

28. 设置App Groups ID

+ (void)setApplicationGroupIdentifier:(NSString*)identifier;

参数:

  • identifier: 通过苹果开发者后台设置的Group Identify。

说明:

  • 需要同时设置[GeTuiSdk setApplicationGroupIdentifier:][GeTuiExtSdk setApplicationGroupIdentifier:],用于回执报表统计。
  • 支持版本2.6.4.0及以上。

头文件:

  • GeTuiSdk.h

接口调用示例:

 [GeTuiSdk setApplicationGroupIdentifier:苹果开发者后台设置的Group Identify];

29. iOS Extension SDK API

29.1.多媒体推送接口

+ (void)handelNotificationServiceRequest:(UNNotificationRequest *)request withAttachmentsComplete:(void (^)(NSArray* attachments, NSArray* errors))completeBlock;

参数:

  • request:推送送达的APNs信息
  • completeBlock:个推统计和多媒体资源下载完成后回调用户操作,用户可在此回调中自行修改通知样式等

返回:

  • NSArray*:SDK 下载完成的资源数组,由UNNotificationAttachment组成的数组
  • NSArray*:资源下载的错误信息,由NSError组成的数组

说明:

1).接收到 APNs 通知后,SDK 判断是否有多媒体资源,如果多媒体资源存在则下载资源,下载完成后以 Block 方式回调返回 attachments 资源数组对象和 errors 错误数组信息。

2).多媒体大小限制:

资源 类型 大小 超时
图片 1 <=10MB 120s
音频 2 <=5MB 60s
视频 3 <=50MB 180s

3).可设置是否仅在 WIFI 下下载资源,参考服务端API。如果为True,数据网络下将不下载资源,展示通知不带附件。默认是False,支持 WIFI 和 数据网络下下载。

4). 资源URL格式注意:不支持中文及转译地址,请使用英文合法地址。

5). 错误信息:

  • 10001:多媒体地址错误,无法下载
  • 10002:不支持 Http URL 下载,修改为支持 ATS 使用 Https 地址或者将 NotificationService 配置为支持 Http 请求
  • 10003:多媒体资源超过大小限制

头文件:

  • GeTuiExtSdk.h

示例:


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

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

    NSLog(@"----将APNs信息交由个推处理----");

    [GeTuiExtSdk handelNotificationServiceRequest:request withAttachmentsComplete:^(NSArray *attachments, NSArray* errors) {

        //TODO:用户可以在这里处理通知样式的修改,eg:修改标题
        self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title]; //修改展示title信息

        self.bestAttemptContent.attachments = attachments; //设置通知中的多媒体附件

        NSLog(@"个推处理APNs消息遇到错误:%@",errors); //如果APNs处理有错误,可以在这里查看相关错误详情

        self.contentHandler(self.bestAttemptContent); //展示推送的回调处理需要放到个推回执完成的回调中
    }];
}

29.2. 多媒体推送接口(仅统计)

+ (void)handelNotificationServiceRequest:(UNNotificationRequest *) request withComplete:(void (^)(void))completeBlock;

参数:

  • request:推送送达的APNs信息
  • completeBlock:个推统计完成后回调用户操作,用户可在此回调中自行修改通知样式等

说明:

  • 接收到 APNs 通知后调用该方法,只统计APNs到达情况,不下载多媒体资源,完成后以 block方式回调,用户可在此回调中自行修改通知样式等。
  • 该接口正常执行后将回调 block 执行, 如果网络异常请求超时,该接口的超时时间最多为5s。5s后将回调 block 执行。
  • block 回调里需调用 self.contentHandler(self.bestAttemptContent) 来完成更新通知栏的正常展示。

头文件:

  • GeTuiExtSdk.h

示例:

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    //通知个推服务器APNs信息送达
    [GeTuiExtSdk handelNotificationServiceRequest:request withComplete:^{

        // Modify the notification content here...
        self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
        //返回新的通知内容,展示APNs通知。
        self.contentHandler(self.bestAttemptContent);
    }];
}

29.3. 停止服务

+ (void)destory;

说明:

  • 销毁SDK,并且释放资源。

头文件:

  • GeTuiExtSdk.h

示例:

- (void)serviceExtensionTimeWillExpire {
    //超时时销毁个推SDK释放资源
    [GeTuiExtSdk destory];
    self.contentHandler(self.bestAttemptContent);
}

30. SDK异常回调

- (void)GeTuiSdkDidOccurError:(NSError *)error;

参数:

  • error:SDK内部发生错误,通知第三方,返回错误信息。

说明:

  • sdk 初始化异常或者运行时出现错误,由该接口返回错误信息。

示例:

/** SDK遇到错误回调 */
- (void)GeTuiSdkDidOccurError:(NSError *)error {
    NSLog(@"[ TestDemo ] [GeTuiSdk GeTuiSdkDidOccurError]:%@\n\n",error.localizedDescription);
}

31. 注册LiveActivity PushToken

+ (BOOL)registerLiveActivity:(NSString *)liveActivityId activityToken:(NSString*)token sequenceNum:(NSString*)sn;

参数:

  • liveActivityId: 业务id,用于绑定token的业务关系。
  • token: LiveActivity 回调的 PushToken。
  • sn: 请求序列码, 不为nil, 用于标识一次注册请求。

返回:

  • BOOL: YES:activityToken长度校验成功,NO:activityToken长度为空。

说明:

  • iOS 16.1 中推出了一个新功能 LiveActivity(灵动岛)。通过该接口注册 activityToken ,从而进行 LiveActivity 推送服务。
  • 支持版本3.0.3.0及以上。

头文件:

  • GeTuiSdk.h

示例:

for await tokenData in current.pushTokenUpdates {
    let mytoken = tokenData.map { String(format: "%02x", $0) }.joined()
    [GeTuiSdk registerLiveActivity:@"订单号" activityToken:mytoken sequenceNum:@"序列号"];
}

请求结果处理示例:

- (void)GeTuiSdkDidRegisterLiveActivity:(NSString *)sequenceNum result:(BOOL)isSuccess error:(NSError *)error {
    NSLog(@"GeTuiSdkDidRegisterLiveActivity SN: %@, isSuccess : %@, error :%@", sequenceNum, @(isSuccess), error);
}

32. 注册LiveActivity PushToStartToken

+ (BOOL)registerLiveActivity:(NSString *)activityAttributes pushToStartToken:(NSString*)pushToStartToken sequenceNum:(NSString*)sn;

参数:

  • activityAttributes: 实时活动的属性,即当前ActivityAttributes结构体名称。不可为空。
  • pushToStartToken: 推送时使用的pushToStartToken
  • sn: 请求序列码, 不为nil, 用于标识一次注册请求。

返回:

  • BOOL: YES:入参长度校验成功,NO:activityAttributes\pushToStartToken\sn长度为空。

    说明:

  • iOS 17.2 中推出了一个新功能 push-to-start LiveActivity。通过该接口注册 pushToStartToken,从而进行APNs推送启动 LiveActivity。

  • 支持版本3.1.7.0及以上。

注意:
当App未启动时,系统收到APNs消息并启动LiveActivity后,会在后台拉活App(运行时间有限)。目的是让App及时汇报当前LiveActivity实例的pushToken,后续开发者可以通过APNs+pushToken对当前实例进行内容更新。
所以,开发者需要在App启动后尽快监听pushTokenUpdates并汇报PushToken给个推,以便后续通过APNs更新LiveActivity内容。

头文件:

  • GeTuiSdk.h

示例:

if #available(iOS 17.2, *) {
    let tokenData = Activity<Attributes>.pushToStartToken

    if let token = tokenData {
        //获取当前
        let pushToStartToken = String(data: token, encoding: .utf8)
        let attributeName = "\(Attributes.self)"
        NSLog("Activity \(Attributes.self) pushToStartToken = \(String(describing: pushToStartToken))")

        //TODO: 开发者上传pushToStartToken
        GeTuiSdk.registerLiveActivity(attributeName, pushToStartToken: pushToStartToken ?? "", sequenceNum: attributeName)
    }

    Task {
        for await tokenData in Activity<Attributes>.pushToStartTokenUpdates {
            //监听token更新
            let mytoken = tokenData.map { String(format: "%02x", $0) }.joined()
            let attributeName = "\(Attributes.self)"
            NSLog("Activity updates \(Attributes.self) pushToStartToken = \(mytoken) ")

            //TODO: 开发者上传pushToStartToken
            GeTuiSdk.registerLiveActivity(attributeName, pushToStartToken: pushToStartToken ?? "", sequenceNum: attributeName)
        }
    }
}

请求结果处理示例:

- (void)GeTuiSdkDidRegisterPushToStartToken:(NSString *)sequenceNum result:(BOOL)isSuccess error:(NSError *)error {
    NSLog(@"GeTuiSdkDidRegisterPushToStartToken SN: %@, isSuccess : %@, error :%@", sequenceNum, @(isSuccess), error);
}

33. 应用内弹窗

// 弹窗展示回调
- (void)GeTuiSdkPopupDidShow:(NSDictionary *)info;

// 弹窗点击回调
- (void)GeTuiSdkPopupDidClick:(NSDictionary *)info;

参数:

  • info: 弹窗内容字段。

返回:

说明:

  • sdk收到应用内弹窗后的回调。
  • 支持版本3.0.3.0及以上。

头文件:

  • GeTuiSdk.h

示例:

// 展示回调
- (void)GeTuiSdkPopupDidShow:(NSDictionary *)info {
    NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] GeTuiSdkPopupDidShow%@", info];
    [self.homePage logMsg:msg];

    //已经集成用户运营SDK的用户, 建议调用IDO的应用内弹窗统计
    [GTCountSDK popupDidShow:info];
}

// 点击回调
- (void)GeTuiSdkPopupDidClick:(NSDictionary *)info {
    NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] GeTuiSdkPopupDidClick%@", info];
    [self.homePage logMsg:msg];

    //已经集成用户运营SDK的用户, 建议调用IDO的应用内弹窗统计
    [GTCountSDK popupDidClick:info];
}

34. 控制中心推送

+ (BOOL)registerControlsTokens:(NSDictionary *)tokens sequenceNum:(NSString*)sn;

参数:

  • tokens: token字典,key为kind,value为token。
  • sn: 用户自定义的请求序列号,用来唯一标识该动作。

返回:

  • BOOL: tokens入参校验是否正确。

说明:

  • 需要iOS 18.0及以上系统版本。
  • 支持版本3.0.9.0及以上。

头文件:

  • GeTuiSdk.h

示例:

- (void)controlsClick {
    if (@available(iOS 18.0, *)) {
      NSDictionary *tokens = @{
            @"kind1":@"token1",
            @"kind2":@"",
            @"kind3":@"token3",
        };
       [GeTuiSdk registerControlsTokens:tokens sequenceNum:@"sn1-uuid"];
    }
}

请求结果处理示例:

- (void)GeTuiSdkDidRegisterControlsTokens:(NSString *)sequenceNum result:(BOOL)isSuccess error:(NSError *)error {
    NSLog(@"GeTuiSdkDidRegisterControlsTokens SN: %@, isSuccess : %@, error :%@", sequenceNum, @(isSuccess), error);
}
开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询