全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网
移动推送

iOS API介绍

更新时间:2017-09-06 16:06:09

iOS SDK最新版本v1.9.1。

移动推送iOS Demo,点击这里

API索引:

1. CloudPushSDK接口

【注意】提供回调的接口均为异步执行。

1.1 基本信息获取


SDK初始化

  • 输入appKeyappSecret初始化推送SDK。
参数
  • appKey AppKey
  • appSecret AppSecret
  • callback 回调
  1. + (void)asyncInit:(NSString *)appKey
  2. appSecret:(NSString *)appSecret
  3. callback:(CallbackHandler)callback;

打开调试日志

  • 打开推送SDK日志;
  • 测试时可选择打开,App上线后建议关闭。
  1. + (void)turnOnDebug;

获取SDK版本号

  • 版本号也可以在CloudPushSDK.h中查看。
返回
  • SDK版本号。
  1. + (NSString *)getVersion;

获取推送通道状态

  • 查询推送应用内通道状态。
返回
  • 推送通道是否打开。
  1. + (BOOL)isChannelOpened;

获取设备deviceId

  • deviceId为阿里云移动推送过程中对设备的唯一标识(并不是设备UUID/UDID);
  • 推送通道正确打开(需要联网)后,可以获取。
返回
  • 设备唯一标识deviceId。
  1. + (NSString *)getDeviceId;

1.2 账号API


绑定账号

  • 将应用内账号和推送通道相关联,可以实现按账号的定点消息推送;
  • 设备只能绑定一个账号,同一账号可以绑定到多个设备;
  • 同一设备更换绑定账号时无需进行解绑,重新调用绑定账号接口即可覆盖生效;
  • 若业务场景需要先解绑后绑定,在解绑账号成功回调中进行绑定绑定操作,以此保证执行的顺序性;
  • 账户名设置支持64字节。
参数
  • account 绑定账号名
  • callback 回调
  1. + (void)bindAccount:(NSString *)account
  2. withCallback:(CallbackHandler)callback;

解绑账号

  • 将应用内账号和推送通道取消关联。
参数
  • callback 回调
  1. + (void)unbindAccount:(CallbackHandler)callback;

1.3 标签API


绑定标签

  • 绑定标签到指定目标;
  • 支持向设备、账号和别名绑定标签,绑定类型由参数target指定;
  • 绑定标签在10分钟内生效;
  • App最多支持绑定1万个标签【请谨慎使用,避免标签绑定达到上限】,单个标签最大支持128字符。
参数
  • target 目标类型,1:本设备;2:本设备绑定账号;3:别名
  • tags 标签(数组输入)
  • alias 别名(仅当target = 3时生效)
  • callback 回调
  1. + (void)bindTag:(int)target
  2. withTags:(NSArray *)tags
  3. withAlias:(NSString *)alias
  4. withCallback:(CallbackHandler)callback;

解绑标签

  • 解绑指定目标标签;
  • 支持解绑设备、账号和别名标签,解绑类型由参数target指定;
  • 解绑标签在10分钟内生效;
  • 解绑标签不等同于删除标签,目前不支持标签的删除。
参数
  • target 目标类型,1:本设备;2:本设备绑定账号;3:别名
  • tags 标签(数组输入)
  • alias 别名(仅当target = 3时生效)
  • callback 回调
  1. + (void)unbindTag:(int)target
  2. withTags:(NSArray *)tags
  3. withAlias:(NSString *)alias
  4. withCallback:(CallbackHandler)callback;

查询标签

  • 查询目标绑定标签,当前仅支持查询设备标签;
  • 查询结果可从callback的data中获取;
  • 标签绑定成功且生效(10分钟内)后即可查询。
参数
  • target 目标类型,1:本设备
  • callback 回调
  1. + (void)listTags:(int)target
  2. withCallback:(CallbackHandler)callback;

1.4 别名API


添加别名

  • 设备添加别名;
  • 单个设备最多添加128个别名,且同一别名最多添加到128个设备;
  • 别名支持128字节。
参数
  • alias 别名
  • callback 回调
  1. + (void)addAlias:(NSString *)alias
  2. withCallback:(CallbackHandler)callback;

删除别名

  • 删除设备别名;
  • 支持删除指定别名和删除全部别名(alias为nil or length = 0)。
参数
  • alias 别名(alias为nil or length = 0时,删除设备全部别名)
  • callback 回调
  1. + (void)removeAlias:(NSString *)alias
  2. withCallback:(CallbackHandler)callback;

查询别名

  • 查询设备别名;
  • 查询结果可从callback的data中获取。
参数
  • callback 回调
  1. + (void)listAliases:(CallbackHandler)callback;

1.5 deviceToken API


上报设备deviceToken

  • 向阿里云推送注册该设备的deviceToken;
  • 可在APNs注册成功回调中调用该接口。
参数
  • deviceToken 苹果APNs服务器返回的deviceToken
  • callback 回调
  1. + (void)registerDevice:(NSData *)deviceToken
  2. withCallback:(CallbackHandler)callback;

获取设备deviceToken

  • 返回获取APNs返回的deviceToken;
  • 调用registerDevice()接口后可获取。
返回
  • 设备deviceToken。
  1. + (NSString *)getApnsDeviceToken;

1.6 通知上报API


上报“通知点击事件”

  • 上报“通知点击事件”ACK到推送服务器;
  • 用于替换SDK v1.8.1之前的handleLaunching:handleReceiveRemoteNotification:上报接口;
参数
  • userInfo 通知payload
  1. + (void)sendNotificationAck:(NSDictionary *)userInfo;

1.7 角标API


同步角标数到服务端

  • 同步设备当前角标数到推送服务端,配合角标自增功能(参考 OpenAPI 2.0 高级推送接口,搜索iOSBadgeAutoIncrement)使用;
  • SDK >= v1.9.5 支持。
参数
  • num 角标数,取值范围[0,99999]
  • callback 回调
  1. + (void)syncBadgeNum:(NSUInteger)num
  2. withCallback:(CallbackHandler)callback;

上报“通知点击事件”(App处于关闭状态)(Deprecated from v1.8.1)

  • 上报“通知点击事件”到推送服务器;
  • 点击通知将App从关闭状态拉起时,在didFinishLaunchingWithOptions回调中调用该接口。
参数
  • launchOptions didFinishLaunchingWithOptions 回调中的launchOptions参数
  1. + (void)handleLaunching:(NSDictionary *)launchOptions;

上报“通知点击事件”(App处于打开状态)(Deprecated from v1.8.1)

  • 上报“通知点击事件”到推送服务器;
  • App处于打开状态(前台 or 后台),在didReceiveRemoteNotification回调中调用该接口;
  • App处于前台,通知不弹窗,直接触发回调;App处于后台,通知弹窗并触发回调。
参数
  • userInfo didReceiveRemoteNotification回调中的参数userInfo
  1. + (void)handleReceiveRemoteNotification:(NSDictionary *)userInfo;

2. 推送通道监听接口

2.1 监听推送通道建立

  • 通知中心注册事件名为CCPDidChannelConnectedSuccess的广播监听;
  • 推送通道成功建立后,发出事件名为CCPDidChannelConnectedSuccess的广播通知。
  1. - (void)listenerOnChannelOpened {
  2. [[NSNotificationCenter defaultCenter] addObserver:self
  3. selector:@selector(onChannelOpened:)
  4. name:@"CCPDidChannelConnectedSuccess"
  5. object:nil];
  6. }
  7. // 通道打开通知
  8. - (void)onChannelOpened:(NSNotification *)notification {
  9. }

2.2 消息接收监听

  • 通知中心注册事件名为CCPDidReceiveMessageNotification的广播监听;
  • 推送通道成功建立后,发出事件名为CCPDidReceiveMessageNotification的广播通知。
  1. - (void) registerMessageReceive {
  2. [[NSNotificationCenter defaultCenter] addObserver:self
  3. selector:@selector(onMessageReceived:)
  4. name:@"CCPDidReceiveMessageNotification"
  5. object:nil];
  6. }
  7. - (void)onMessageReceived:(NSNotification *)notification {
  8. CCPSysMessage *message = [notification object];
  9. NSString *title = [[NSString alloc] initWithData:message.title encoding:NSUTF8StringEncoding];
  10. NSString *body = [[NSString alloc] initWithData:message.body encoding:NSUTF8StringEncoding];
  11. NSLog(@"Receive message title: %@, content: %@.", title, body);
  12. }

2.3 通知打开监听

iOS 10+

  • App处于前台收到通知;
  1. /**
  2. * 处理iOS 10通知(iOS 10+)
  3. */
  4. - (void)handleiOS10Notification:(UNNotification *)notification {
  5. UNNotificationRequest *request = notification.request;
  6. UNNotificationContent *content = request.content;
  7. NSDictionary *userInfo = content.userInfo;
  8. // 通知时间
  9. NSDate *noticeDate = notification.date;
  10. // 标题
  11. NSString *title = content.title;
  12. // 副标题
  13. NSString *subtitle = content.subtitle;
  14. // 内容
  15. NSString *body = content.body;
  16. // 角标
  17. int badge = [content.badge intValue];
  18. // 取得通知自定义字段内容,例:获取key为"Extras"的内容
  19. NSString *extras = [userInfo valueForKey:@"Extras"];
  20. // 通知打开回执上报
  21. [CloudPushSDK sendNotificationAck:userInfo];
  22. NSLog(@"Notification, date: %@, title: %@, subtitle: %@, body: %@, badge: %d, extras: %@.", noticeDate, title, subtitle, body, badge, extras);
  23. }
  24. /**
  25. * App处于前台时收到通知(iOS 10+)
  26. */
  27. - (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  28. NSLog(@"Receive a notification in foregound.");
  29. // 处理iOS 10通知相关字段信息
  30. [self handleiOS10Notification:notification];
  31. // 通知不弹出
  32. //completionHandler(UNNotificationPresentationOptionNone);
  33. // 通知弹出,且带有声音、内容和角标(App处于前台时不建议弹出通知)
  34. completionHandler(UNNotificationPresentationOptionSound | UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionBadge);
  35. }
  • 触发通知动作时回调,比如点击、删除通知和点击自定义action(iOS 10+);
  1. /**
  2. * 触发通知动作时回调,比如点击、删除通知和点击自定义action(iOS 10+)
  3. */
  4. - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
  5. NSString *userAction = response.actionIdentifier;
  6. // 点击通知打开
  7. if ([userAction isEqualToString:UNNotificationDefaultActionIdentifier]) {
  8. NSLog(@"User opened the notification.");
  9. // 处理iOS 10通知,并上报通知打开回执
  10. [self handleiOS10Notification:response.notification];
  11. }
  12. // 通知dismiss,category创建时传入UNNotificationCategoryOptionCustomDismissAction才可以触发
  13. if ([userAction isEqualToString:UNNotificationDismissActionIdentifier]) {
  14. NSLog(@"User dismissed the notification.");
  15. }
  16. NSString *customAction1 = @"action1";
  17. NSString *customAction2 = @"action2";
  18. // 点击用户自定义Action1
  19. if ([userAction isEqualToString:customAction1]) {
  20. NSLog(@"User custom action1.");
  21. }
  22. // 点击用户自定义Action2
  23. if ([userAction isEqualToString:customAction2]) {
  24. NSLog(@"User custom action2.");
  25. }
  26. completionHandler();
  27. }

iOS 10以下版本

  • App处于关闭状态时,点击打开通知;
  1. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  2. // 点击通知将App从关闭状态启动时,将通知打开回执上报
  3. // [CloudPushSDK handleLaunching:launchOptions];(Deprecated from v1.8.1)
  4. [CloudPushSDK sendNotificationAck:launchOptions];
  5. return YES;
  6. }
  • App处于打开状态时,点击打开通知;
  1. - (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo {
  2. NSLog(@"Receive one notification.");
  3. // 取得APNS通知内容
  4. NSDictionary *aps = [userInfo valueForKey:@"aps"];
  5. // 内容
  6. NSString *content = [aps valueForKey:@"alert"];
  7. // badge数量
  8. NSInteger badge = [[aps valueForKey:@"badge"] integerValue];
  9. // 播放声音
  10. NSString *sound = [aps valueForKey:@"sound"];
  11. // 取得Extras字段内容
  12. NSString *Extras = [userInfo valueForKey:@"Extras"]; //服务端中Extras字段,key是自己定义的
  13. NSLog(@"content = [%@], badge = [%ld], sound = [%@], Extras = [%@]", content, (long)badge, sound, Extras);
  14. // iOS badge 清0
  15. application.applicationIconBadgeNumber = 0;
  16. // 通知打开回执上报
  17. // [CloudPushSDK handleReceiveRemoteNotification:userInfo];(Deprecated from v1.8.1)
  18. [CloudPushSDK sendNotificationAck:userInfo];
  19. }
本文导读目录