iOS接入

一. ACCS SDK 初始化

• 指定仓库：

source 'git@gitlab-ce.emas-poc.com:EMAS-iOS/emas-specs.git'

• 添加依赖：

pod 'TBAccsSDK', '10.0.7'
pod 'NetworkSDK', '10.0.4.4'
pod 'tnet', '10.3.0'

• 初始化设置：
• 引入头文件

#import <TBAccsSDK/TBAccsManager.h>

• 作为基础中间件请使用方尽量早的初始化TBAccsSDK，建议在程序启动后AppDelegate中的didFinishLaunchingWithOptions回调中就完成初始化的工作：

// 初始化参数
TBAccsConfiguration *config =  [[TBAccsConfiguration alloc] initWithHost:@"accs.domain.com"];
// App唯一标识，必填
config.appkey = @"12345";
// 请求加密加签使用，必填
config.appsecret = @"abcdefghijklmnopqrst";
// 连接指定IP
config.defaultIP = @"10.10.10.10";
// 连接指定端口
config.defaultPort = 443;
// 设置EMAS专用公钥
config.slightSSLPublickeyIndex = ACCS_PUBKEY_PSEQ_EMAS;
// 根据config构建ACCS实例,并启动
TBAccsManager *accsManager = [TBAccsManager createAccsWithConfiguration:config];
[accsManager startAccs];

• 若不指定IP+Port, 亦可设置通过Local DNS的方式建立连接:

// 初始化参数
TBAccsConfiguration *config = [[TBAccsConfiguration alloc] initWithHost:@"accs.domain.com"];
// App唯一标识，必填
config.appkey = @“12345”;
// 请求加密加签使用，必填
config.appsecret = @“abcdefghijklmnopqrst”;
// 指定使用local dns
config.supportLocalDnsWhenNoPolicy = YES;
// 设置EMAS专用公钥
config.slightSSLPublickeyIndex = ACCS_PUBKEY_PSEQ_EMAS;
// 根据config构建ACCS实例,并启动
TBAccsManager *accsManager = [TBAccsManager createAccsWithConfiguration:config];
[accsManager startAccs];

• 相关概念解释：

  1. 上行

     客户端向服务单主动发送数据，我们称之为上行数据

     • REQ/RES模式

     客户端每次向服务端请求后，服务端响应一个数据应答包,这种方式与传统的http请求类似。

     • Data模式:

     客户端向服务端发送数据，没有应答数据包，只有ACK，且业务层无须接收ACK。

     • ACK:

     accs的每条下行数据都会返回服务端ack, ack可以透传给业务, 业务可以选择接收或不接收。

  2. 下行

     服务端主动向客户端推送数据，我们称之为下行数据。

二. SDK 接口调用

2.1 Bind App

• app启动后，马上调用此接口。appleDeviceToken参数可以传入空。此接口可以被多次调用。

 [_accsManager bindAppWithAppleToken: appleDeviceToken
                            callBack:^(NSError *error, NSDictionary *resultsDict) {
         if (error) {
             AccsLog(@"\n\n绑定App出错了 %@\n\n", error);
         }
         else {
             AccsLog(@"\n\n绑定App成功了\n\n");
         }
     }];

只有绑定APP成功，ACCS 实例才能正常接收下行消息，否则只能发送上行消息。

• BindApp 在端上有6小时状态缓存，也即在6小时后，真实的BindApp请求只会向服务端发送一次， 若需要强制发送BindApp请求至服务端：

[_accsManager bindAppWithAppleToken: appleDeviceToken
                                     force: YES
                           callBack:^(NSError *error, NSDictionary *resultsDict) {
        if (error) {
            AccsLog(@"\n\n绑定App出错了 %@\n\n", error);
        }
        else {
            AccsLog(@"\n\n绑定App成功了\n\n");
        }
    }];

2.2 绑定/解绑用户

绑定用户动作在ACCS中不是必须的，ACCS设备检索是依赖deviceid (就是utdid)。端上通过bind user之后，业务端可以使用业务自己的userid来检索设备, 实现用户维度运维发送消息。注意同一个userId最多只能绑定20个设备，超出该限制后，绑定会失败。

    [_accsManager bindUserWithUserId:  _userId.text
                        callBack:^(NSError *error, NSDictionary *resultsDict) {
         if (error) {
             AccsLog(@"\n\n绑定用户出错了 %@\n\n", error);
         }
         else {
             AccsLog(@"\n\n绑定用户成功了\n\n");
         }
     }];
    [_accsManager unbindUserWithUserId:_userId.text callBack:^(NSError *error, NSDictionary *resultsDict) {
        if (error) {
            AccsLog(@"解绑用户出错: %@", error);
        } else {
            AccsLog(@"解绑用户成功");
        }
    }];

2.3 发送上行数据

参数说明：

• data: 需要发送的数据
• serviceId: 目标服务；
• userId: 发送用户标识，一般为nil
• otherParameters: 没有使用，填nil
• callBack: 发送结果回调

[_accsManager sendRequestWithData: [_message.text dataUsingEncoding: NSUTF8StringEncoding]
                        serviceId: @“your_service_id”
                           userId: @"your_user_id"
                  otherParameters: nil
                         callBack:^(NSError *error, NSDictionary *resultsDict) {
                                 if (error) {
                                     AccsLog(@"发送数据失败sendRequest: %@", error);
                                 }
                                 else{
                                     AccsLog(@"发送数据成功sendRequest");
                                 }
                             }];

2.4 订阅下行消息

订阅下行消息通过API: Bind Service 来完成：

参数说明：

• serviceId: 需要监听下行数据的服务id, 需要找服务端同学来获取；（如果服务端尚未完成接入，在测试阶段可以使用测试用的serviceId，即emas-test）
• callback: 函数调用结果回调，error==nil 时表示成功，resultsDict表示绑定时ACCS后端返回的response;
• receviceDataBlock: 即下行数据监听回调，若绑定成功后，目标服务有下行数据，将会在改block中接收具体下行数据

[_accsManager bindServiceWithServiceId: _serviceId.text
                              callBack:^(NSError *error, NSDictionary *resultsDict) {
         if (error){
             AccsLog(@"绑定Service出错了");
         }
         else{
             AccsLog(@"绑定Service成功了");
         }
     }
                         receviceDataBlock:^(NSError *error, NSDictionary *resultsDict){
         if (error){
             AccsLog(@"接收 Accs 数据出错 %@", error.description);
         }
         else{
             AccsLog(@"接收 Accs 数据成功 %@", resultsDict[@"jsonString"]);
         }
     }];

返回的数据在 resultDict 中，解析如下：

// message id
NSString *dataId = [resultsDict objectForKey:@"dataId"];
// from which service
NSString *serviceId = [resultsDict objectForKey:@"serviceId"];
// message payload, binary data
NSData *payload = [resultsDict objectForKey:@"resultData"];
// 例如业务端发送payload 是一个字符串，则解析成字串
NSString *text =  [[NSString alloc] initWithData:payload encoding:NSUTF8StringEncoding];

2.5 注册离线消息监听

“离线消息”概念：

当ACCS连接在线时，服务端通过ACCS推送下来的消息称之为“在线消息”；当ACCS连接离线时，服务端把需要的下行消息缓存起来，当设备再次上线时，再推下去，这些消息称之为“离线消息”

因连接一旦建立成功，服务端即会立即推送缓存的离线消息，因为业务使用SDK时的时序不可控，有可能数据到达SDK时，业务尚未bind service, 导致消息被丢弃。为解决此问题，业务可在AccsReceiverTable.plist中注册下行消息接收handler, ACCS在初始化时，通过反射创建注册的handler, 把收到的消息投递出去，避免业务bind service过晚而导致的消息丢失。注意：大小写敏感！

AccsReceiverTable.plist文件路径无特殊需求，添加到主客工程中即可。

注册格式如下：

{
    "im": {
        "class": "TBIMAccsAdapter"
    }
}

im表示自己申请的serviceID，class表示需要实现以下协议的类，accs会根据类名和协议方法动态调用此类，其中 TBIMAccsAdapter 需要实现以下接口：

@protocol TBAccsCallbackProtocol <NSObject>
@required
+ (TBAccsManagerResponseBlock)callBack;
+ (NSString *)serviceID;
@optional
+ (NSString *)accsHost; // ACCS Host, 可以不写
@end

三. 调试日志

• TBAccsSDK 日志

在接入调试的时候，若出现异常&错误不便排查，可以打开SDK日志，通过日志排查问题原因：

// 先声明日志开关函数
void tbAccsSDKSwitchLog(BOOL logCtr);
// 打开日志
tbAccsSDKSwitchLog(YES);

• NetworkSDK 日志

因为TBAccsSDK中连接的建连、保活等基础逻辑是在网络库中实现，所以有时我们需要进一步查看网络库的日志：

#import "NWLog.h"
[NWLog setLogLevel:NW_LOG_DEBUG];

四. 错误码

所有上行接口的回调参数中的NSError* 若为nil, 则表示无错误；若非空，其解释如下：