全部产品

iOS接入手册

更新时间:2020-07-17 10:06:42

1. SDK依赖配置

SDK仓库配置信息,参考以下文档“接入准备”一节的介绍:https://help.aliyun.com/document_detail/87885.html

在Podfile中添加依赖:

  1. pod 'AliEMASConfigure', '0.0.1.19'
  2. pod 'NetworkSDK', '10.0.4.6'
  3. pod 'TBAccsSDK', '10.0.11'
  4. pod 'PushCenterSDK', '10.0.11'

2. 接入准备

在EMAS后台下载脚手架配置文件AliyunEmasServices-Info.plist,将配置文件添加到项目中。

AliEMASConfigure会自动读取配置文件,并将配置传递给推送SDK。

3. 接入API

3.1 初始化

在AppDelegate中初始化EMAS推送SDK:

  1. // --自初始化头文件
  2. #import <AliEMASConfigure/AliEMASConfigure.h>
  3. // --基础库头文件
  4. #import <NetworkSDK/NetworkCore/NWNetworkConfiguration.h>
  5. #import <NetworkSDK/NetworkCore/NetworkDemote.h>
  6. #import <NetworkSDK/NetworkCore/NWuserLoger.h>
  7. #import <NetworkSDK/AliReachability/NWLog.h>
  8. // --ACCS头文件
  9. #import <TBAccsSDK/TBAccsManager.h>
  10. // --PUSH头文件
  11. #import <PushCenterSDK/TBSDKPushCenterConfiguration.h>
  12. #import <PushCenterSDK/TBSDKPushCenterEngine.h>
  13. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  14. [NWLog setLogLevel:NW_LOG_DEBUG];
  15. [self initAccsConfig];
  16. [self initPushConfig];
  17. [self registerNotificationSetting];
  18. }
  19. // ACCS初始化部分
  20. - (void)initAccsConfig {
  21. void tbAccsSDKSwitchLog(BOOL logCtr);
  22. tbAccsSDKSwitchLog(YES); // 打开调试日志
  23. TBAccsManager *accsManager = [TBAccsManager accsManagerByConfigureName:nil];
  24. [accsManager startAccs];
  25. [accsManager bindAppWithAppleToken: nil
  26. callBack:^(NSError *error, NSDictionary *resultsDict) {
  27. if (error) {
  28. NSLog(@"\n\n绑定App出错了 %@\n\n", error);
  29. }
  30. else {
  31. NSLog(@"\n\n绑定App成功了\n\n");
  32. }
  33. }];
  34. }
  35. // PUSH
  36. - (void)initPushConfig {
  37. TBSDKPushCenterEngine *pce = [TBSDKPushCenterEngine sharedInstanceWithDefaultConfigure];
  38. [TBSDKPushCenterConfiguration shareInstance].scheduleLocalNotificationWhenAppBackground = NO;
  39. [pce start];
  40. }

3.2 配置APNS推送

  1. @interface AppDelegate () <UNUserNotificationCenterDelegate>
  2. @end
  3. // 注册推送
  4. - (void)registerNotificationSetting {
  5. if (@available(iOS 10.0, *)) {
  6. UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
  7. center.delegate = self;
  8. [center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge) completionHandler:^(BOOL granted, NSError * _Nullable error) {
  9. if(error) {
  10. NSLog( @"Push registration FAILED" );
  11. NSLog( @"ERROR: %@ - %@", error.localizedFailureReason, error.localizedDescription );
  12. NSLog( @"SUGGESTIONS: %@ - %@", error.localizedRecoveryOptions, error.localizedRecoverySuggestion );
  13. return;
  14. }
  15. [[UIApplication sharedApplication] registerForRemoteNotifications];
  16. NSLog( @"Push registration success." );
  17. }];
  18. } else {
  19. [[UIApplication sharedApplication] registerUserNotificationSettings:
  20. [UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge)
  21. categories:nil]];
  22. [[UIApplication sharedApplication] registerForRemoteNotifications];
  23. NSLog(@"[APNS] registerNotificationSetting");
  24. }
  25. }
  26. // 注册deviceToken
  27. - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  28. NSLog(@"[APNS] device token: %@", deviceToken);
  29. TBSDKPushCenterEngine *pce = [TBSDKPushCenterEngine sharedInstanceWithDefaultConfigure];
  30. [pce upLoaderDeviceToken:deviceToken userInfo:nil callback:^(NSDictionary *result, NSError *error){
  31. if ( error ) {
  32. NSLog(@"[APNS] update token error: %@", error);
  33. } else {
  34. [self initPushParameters];
  35. NSLog(@"[APNS] update token successfully!");
  36. }
  37. }];
  38. }
  39. - (void)application:(UIApplication *)app didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  40. NSLog(@"[APNS] register error: %@", error);
  41. }
  42. // iOS6及以下系统接收通知
  43. - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
  44. NSLog(@">>>>>>> [AGOO MESSAGE]: %@", userInfo);
  45. }
  46. // iOS7及iOS10以下系统接收通知
  47. - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler: (void (^)(UIBackgroundFetchResult))completionHandler {
  48. NSLog(@">>>>>>> [AGOO MESSAGE]: %@", userInfo);
  49. completionHandler(UIBackgroundFetchResultNewData);
  50. }
  51. // iOS10及以上系统接收通知
  52. - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler API_AVAILABLE(ios(10.0)){
  53. NSDictionary *userInfo = response.notification.request.content.userInfo;
  54. NSLog(@">>>>>>> [AGOO MESSAGE]: %@", userInfo);
  55. }

3.3 绑定/解绑别名

PushCenterSDK 升级到 10.0.11 后,别名的绑定关系变更为多对多。一个别名和绑定多台设备,一个设备可以绑定多台别名。接口方法名也变更为 addAlias: userInfo: callback:removeAlias: userInfo: callback:。升级后要注意,别名绑定后要进行解绑。

  1. - (IBAction)bindUser {
  2. NSString *alias = @"myAlias";
  3. TBSDKPushCenterEngine *pce = [TBSDKPushCenterEngine sharedInstanceWithDefaultConfigure];
  4. [pce addAlias:alias userInfo:nil callback:^(NSDictionary * _Nullable userInfo, NSError * _Nullable error) {
  5. if (error) {
  6. [self displayText:[NSString stringWithFormat:@"绑定别名错误:%@", error]];
  7. } else {
  8. [self displayText:[NSString stringWithFormat:@"绑定别名成功"]];
  9. }
  10. }];
  11. }
  12. - (IBAction)unbindUser {
  13. TBSDKPushCenterEngine *pce = [TBSDKPushCenterEngine sharedInstanceWithDefaultConfigure];
  14. [pce removeAlias:alias userInfo:nil callback:^(NSDictionary * _Nullable userInfo, NSError * _Nullable error) {
  15. if (error) {
  16. [self displayText:[NSString stringWithFormat:@"解绑别名发生错误: %@", error]];
  17. } else {
  18. [self displayText:[NSString stringWithFormat:@"解除绑定别名成功"]];
  19. [userDefault removeObjectForKey:user_alias];
  20. [userDefault synchronize];
  21. }
  22. }];
  23. }

3.4 消息通道

如果应用运行在后台,会接收苹果的APNS推送,如果运行在前台,推送消息则来自于ACCS通道。PushCenterSDK 升级到 10.0.11 后,新增了一个消息接收方式,用于更快速便利的接入。

只需要注册/监听通知,用于接收消息即可。

  1. #pragma mark 注册接收accs推送下来的消息
  2. - (void) registerMsgReceive {
  3. [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onMessageReceived:) name:@"EMASACCSReceiveMessageNotification" object:nil]; // 注册
  4. }
  5. - (void)onMessageReceived:(NSNotification *)notification {
  6. NSDictionary *userInfo = notification.userInfo;
  7. NSLog(@">>>>>>> [AGOO MESSAGE]: %@", userInfo);
  8. NSString *text = [userInfo description];
  9. if (!text ) {
  10. text = @"消息解析失败!";
  11. }
  12. UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"AGOO 消息" message:text delegate:self cancelButtonTitle:@"确认" otherButtonTitles:nil, nil];
  13. [alert show];
  14. }
  1. #pragma mark 注册接收accs推送下来的消息
  2. - (void) registerMsgReceive {
  3. [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onMessageReceived:) name:@"EMASACCSReceiveMessageNotification" object:nil]; // 注册
  4. }

原来利用 plist 来注册接收类的方式依然适用。这种方式的好处是对于离线的accs消息,在 app 冷启动时可以在SDK 初始化前就完成注册,避免消息丢失。

为了接收到ACCS推送的长连消息, 需要先创建一个 AccsReceiverTable.plist 文件,用来注册 ACCS 的消息接收类,文件内容如下:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  3. <plist version="1.0">
  4. <dict>
  5. <key>agooSend</key>
  6. <dict>
  7. <key>class</key>
  8. <string>TBSDKPushAccsReceiver</string>
  9. </dict>
  10. </dict>
  11. </plist>

然后再创建一个PushSDKReceiverConfig.plist文件,用来注册推送的消息接收类,接收 ACCS 消息的派发,plist文件内容如下:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  3. <plist version="1.0">
  4. <dict>
  5. <key>ReceiverList</key>
  6. <array>
  7. <dict>
  8. <key>class</key>
  9. <string>PushMessageReceiver</string>
  10. <key>isSingleton</key>
  11. <true/>
  12. </dict>
  13. </array>
  14. </dict>
  15. </plist>

最后创建一个PushMessageReceiver类接收派发的 ACCS 消息:

  1. @implementation PushMessageReceiver
  2. - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
  3. NSLog(@">>>>>>> [AGOO MESSAGE]: %@", userInfo);
  4. }
  5. @end

3.5 上报消息的到达和点开事件

  1. // 4表示消息到达,8表示消息被点开
  2. [TBSDKPushCenterUserTrackEngine uploadAgooPoint:@"message_id" MsgStatus:@"4"];
  3. [TBSDKPushCenterUserTrackEngine uploadAgooPoint:@"message_id" MsgStatus:@"8"];

4. 推送验证

在EMAS后台的移动推送->设备查询界面,选择查询类型“别名”,输入myAlias,如果一切配置无误,搜索结果会显示当前建连成功的设备信息;

在移动推送->推送消息界面可以给App发送推送消息,由于带图推送是iOS10以后才引入,如果需要测试配图推送,需要自己创建Notification Content Extension。

常见的几种推送收不到情况:

  1. 推送证书问题:可以在EMAS后台的移动推送->配置管理界面,使用测试Token功能测试证书的有效性;
  2. 保证Xcode的Capabilities推送开关开启;
  3. 保证ACCS SDK的[TBAccsManager bindAppWithAppleToken:callBack:]回调绑定App成功;
  4. 保证Appdelegate的application:didRegisterForRemoteNotificationsWithDeviceToken:能够成功获得deviceToken;

5. 调试和错误码

  1. /**
  2. * LOG 打印级别
  3. */
  4. typedef enum {
  5. kTBPushLogNone = 0, // 关闭,不打印
  6. kTBPushLogError = 1, // 打印 ERROR 级别
  7. kTBPushLogDebug = 2 // 打印 DEBUG 级别
  8. } TBPushLogLevel;
  9. // 因为PushCenterSDK 强依赖 TBAccsSDK 与 NetworkSDK, 需要是可以打开下级SDK日志
  10. [TBSDKPushCenterConfiguration setLogLevelWithPushSDK:kTBPushLogDebug
  11. withAccsSDK:kTBPushLogDebug
  12. withNetworkSDK:kTBPushLogDebug];

设备相关

错误码 描述
-100 设备未注册
-101 构造设备注册消息失败
-102 设备注册返回空
-103 设备注册失败

上传Token相关

错误码 描述
-200 空 TOKEN
-201 构造UploadToken消息失败
-202 发送UploadToken失败
-203 UploadToken返回失败

绑定用户相关

错误码 描述
-300 空 Alias
-301 构造BindUser消息失败
-302 上传BindUser失败
-303 BindUser返回空
-305 BindUser返回空
-306 UnbindUser失败

应用内push相关

错误码 描述
-400 ACCS payload 空
-401 ACCS payload 解析失败
-402 MESSAGE BODY EMPTY
-403 MESSAGE ID EMPTY
-405 MESSAGE 解析错误
-406 MESSAGE 解析错误
-407 MESSAGE BODY 解密失败
-408 MESSAGE 为送达

基础accs通道相关

错误码 描述
-500 ACCS SDK 未接入
-501 ACCS 无 payload
-502 ACCS 通道错误