AOne SDK iOS客户端接入

1.开发者后台证书配置

1. 主APP的bundid和NE插件进程的bundid。需遵循NE插件进程的bundid是主APP的bundid.network-extension的规则。（比如主APP的bundid是com.app.example,则NE插件进程的bundid是com.app.example.network-extension）
2. AppGroup配置为group.bundid.（比如主APP的bundid是com.app.example,则group配置为group.com.app.example）

1.1.应用权限配置

1.1.1.配置主AppID的配置权限

1. 增加Identifiers
   
2. 选择权限
   
   

1.1.2配置NE(NetworkExtension)插件AppID的配置权限

1. 增加Identifiers
   
2. 选择权限
   
   

2.应用集成

2.1.配置应用权限

2.1.1.配置NetworkExtension权限

应用需要在Signing&Capabilities界面配置APPGroup和NetworkExtension权限。

2.1.2配置AppGroup权限

对应的Groupid为客户集成项目自身的GroupId，请不要配置错误（重要重要重要）。

2.2.SDK和隧道插件加入工程

使用客户自己的网络插件的证书签名，对应的Groupid为客户集成项目自身的GroupId，请不要配置错误（重要重要重要）。

2.2.1.重签名隧道插件

2.2.2.隧道插件/SDK配置

请注意SDK和插件的嵌入方式，参考截图：

2.2.3.配置NE插件的目标

2.2.4.配置APP的plist字段

plist文件增加com.wireguard.ios.app_group_id的配置，用于配置AppGroup的配置字段，对应的Groupid为客户集成项目自身的GroupId，请不要配置错误（重要重要重要）。

2.3.NE插件重签名流程补充说明

1. 选择给到的TyyAppResign.app的签名工具打开如下图。
2. Input File:选择给到的开发SDK中的LXR-VPNNetworkExtension.appex插件。
3. 选择开发者的签名证书。
4. 选择开发者的签名描述文件（需要具备前面章节描述的权限的描述文件）。
5. VPN APP Groups ID 配置为当前appid配置的groupid。
6. 点击start完成重改签名。

3.整体流程介绍

3.1.获取id_token

3.1.1.获取方式一（跳转到浏览器）

1. 拼接跳转到浏览器的地址。
2. 配置app的URL types，URL Schemes配置上ctyunaone。
3. 通过web界面完成anoeid的认证，并接收回调数据。
4. 解析回调成功后的id_token。

3.1.2拼接跳转链接

1. 需要拿到跳转页面的地址，如参考代码中的address。（联系零信任对接人员获取）
2. 需要拿到租户id，如参考代码中的pollid。（联系零信任对接人员获取）
3. 需要拿到认证地址的key，如参考代码中的key。（联系零信任对接人员获取）

参考demo
/*
 address:认证页面域名比如 https://aoneid-dev.ctcdn.cn
 pollid:认证的租户id比如 fsiofjiosfjoaisf
 key:认证地址的key比如 fjioregjoiertgjo
 */
-(NSString*)jointUrl:(NSString*)address Pollid:(NSString*)pollid Key:(NSString*)key{
    return [NSString stringWithFormat:@"%@/%@/app/%@",address,pollid,key];
}

3.1.3.URLtypes配置参考

特别注意scheme本文全部以"ctyunaone"表示，具体在接入的时候，这个scheme以真实配置的为准（重要），配置方式可参考配置文档：

3.1.4.跳转到web，并接收回调数据

{
   [[UIApplication sharedApplication] openURL:[NSURL URLWithString:thirdUrl] options:@{} completionHandler:nil];
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options
{
    return [self handleOpenURL:url];
}
//解析url
- (NSDictionary*)parseQueryParameters:(NSURL *)url {
    NSMutableDictionary<NSString *, NSString *> *queryParameters = [NSMutableDictionary dictionary];
    NSURLComponents *urlComponents = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO];
    NSArray<NSURLQueryItem *> *queryItems = urlComponents.queryItems;
    for (NSURLQueryItem *queryItem in queryItems) {
        if (queryItem.value) {
            queryParameters[queryItem.name] = queryItem.value;
        }
    }
    return [queryParameters copy]; // 返回不可变字典
}
//处理回调url
- (BOOL)handleOpenURL:(NSURL*)url
{
    NSLog(@"URL end with 'aa': %@", url.absoluteString);
    if ([url.absoluteString hasPrefix:@"ctyunaone://aoneid"]) {
        // 在这里处理以 "aa" 开头的 URL
        NSDictionary* queryDic = [self parseQueryParameters:url];
        NSLog(@"URL starts with 'aa': %@", url.absoluteString);
        // 发送通知
        NSDictionary *userInfo = @{@"url": url, @"query": queryDic}; // 可选的用户信息
        [[NSNotificationCenter defaultCenter] postNotificationName:@"AoneidLoginNotification"
                                                            object:nil
                                                          userInfo:userInfo];
        NSLog(@"Notification sent: %@", userInfo);
        return YES; // 返回 YES 表示成功处理
    }
  
    // 处理其他 URL
    return NO; // 返回 NO 表示未处理该 URL
}

3.1.5.解析回调成功后的id_token

// 处理通知的方法
- (void)handleNotification:(NSNotification *)info {
    NSDictionary *dic = info.userInfo;
    NSDictionary *query = dic[@"query"];
    if (!query[@"id_token"] || !((NSString *)query[@"id_token"]).length) {
        self.skipBtn.text = @"获取token失败";
      return;
    }
    self.id_token = query[@"id_token"];
    self.skipBtn.text = @"获取token成功";
    NSLog(@"webAuth response:%@",self.skipBtn.text);
}

特别注意。需要按照零信任认证之后的返回配置URL Schemes，否则无法返回到集成零信任SDK的app内。

3.2.注册监听

• (BOOL)RegistGlobalNotification:(id)observer selector:(SEL)aSelector;

全局监听零信任通知到业务层的回调事件，目前主要是隧道状态。

• 调用示例

[LXRVPNSDKClient RegistGlobalNotification:self selector:@selector(sdkGlobalMessageNotification:)];

- (void)sdkGlobalMessageNotification:(NSNotification*)noti
{
    NSLog(@"sdkTopicMessageNotification noti = %@", noti);
    if(noti)
    {
        NSDictionary* topicDic = [noti object] ;
        if(topicDic)
        {
            NSLog(@"SdkInit response:%@",topicDic);
        }
    }
}

3.3.SDK初始化

• (void)SdkInit:(NSDictionary*)params completion:(TrustCompletion _Nullable)completion;

将外部传入的token传递给SDK，完成零信任SDK的初始化。

• 调用示例

[LXRVPNSDKClient SdkInit:@{ @"token":@"ffnefnoeof"} completion:^(NSDictionary * _Nullable response) {
        NSLog(@"SdkInit response:%@",response);
}];

3.4.启动隧道

• (void)SdkStartVPN:(NSDictionary*)params completion:(TrustCompletion _Nullable)completion;

启动零信任的隧道。

• 调用示例

[LXRVPNSDKClient SdkStartVPN:@{} completion:^(NSDictionary * _Nullable response) {
    NSLog(@"SdkStartVPN response:%@",self.skipBtn.text);
}];

4.接口介绍

4.1.SDK初始化

函数介绍

• (void)SdkInit:(NSDictionary*)params completion:(TrustCompletion _Nullable)completion;

函数用于初始化零信任SDK。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注
token	NSString	外部传入的AoneIdToken	是	用于换Accesstoken
urlPrefix	NSString	多镜像的备用域名	否	支持多镜像的时候传
tunFlag	NSString	是否可以切换多镜像	否	支持多镜像的时候传

请求示例

{
    "token": "sefijiaosfjaiosrjfioasjfois;ajrfmo;isarjf"
}

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
code	NSString	接口状态码	是	0：成功非0:失败
message	NSString	接口返回信息	是	接口返回的提示信息
data	NSDictionary	返回的参数	是	具体响应数据信息

参数	参数类型	参数含义	是否必传	备注
aoneSdkToken	NSString	返回的sdktoken	是

响应示例

成功

{
    "message": "",
    "code": "0x00000"
}

失败

{
    "message": "软件内部错误，请稍后重试",
    "code": "0x00002"
}

4.2.VPN启动

函数介绍

• (void)SdkStartVPN:(NSDictionary*)params completion:(TrustCompletion _Nullable)completion;

函数用于启动零信任SDK的隧道。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注

请求示例

{
   
}

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
code	NSString	接口状态码	是	0：成功非0:失败
message	NSString	接口返回信息	是

响应示例

成功

{
    "message": "",
    "code": "0x00000"
}

失败

{
    "message": "软件内部错误，请稍后重试",
    "code": "0x00002"
}

4.3.VPN停止

函数介绍

• (void)SdkStopVPN:(NSDictionary*)params completion:(TrustCompletion _Nullable)completion;

函数用于停止零信任SDK的隧道。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注

请求示例

{
   
}

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
code	NSString	接口状态码	是	0：成功非0:失败
message	NSString	接口返回信息	是

响应示例

成功

{
    "message": "",
    "code": "0x00000"
}

失败

{
    "message": "软件内部错误，请稍后重试",
    "code": "0x00002"
}

4.4.注册回调

函数介绍

• (BOOL)RegistGlobalNotification:(id)observer selector:(SEL)aSelector;

函数用于注册零信任SDK的全局回调。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注
observer	id	回调的实例	是	回调实例
aSelector	SEL	回调的函数	是	回调函数

请求示例

{
    //注册全局回调
    [LXRVPNSDKClient RegistGlobalNotification:self selector:@selector(sdkGlobalMessageNotification:)];

    //触发全局回调响应函数
    - (void)sdkGlobalMessageNotification:(NSNotification*)noti
    {
        NSLog(@"sdkTopicMessageNotification noti = %@", noti);
        if(noti)
        {
            NSDictionary* topicDic = [noti object] ;
            if(topicDic)
            {
                NSLog(@"sdkGlobalMessageNotification:%@",topicDic);
            }
        }
    }
}

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
tunnelState	NSDictionary	隧道状态主题	否	表示当前通知类型是隧道状态

参数	参数类型	参数含义	是否必传	备注
status	NSNumber	隧道状态	是	1｜2｜3｜ 断开｜连接中 ｜已连上

响应示例

成功

{
    "tunnelState": {
        "status": 1
    }
}

4.5.查询隧道状态

函数介绍

• (void)getTunnelStatus:(TrustCompletion _Nullable)completion;

函数用于注册零信任SDK的全局回调。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注

请求示例

[LXRVPNSDKClient getTunnelStatus:^(NSDictionary * _Nullable response) {
        self.skipBtn.text = [self jsonStringFromDictionary:response];
    }];

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
status	NSNumber	隧道状态	是	1｜2｜3｜ 断开｜连接中 ｜已连上

响应示例

成功

{
    "status": 1
}

4.6.分享日志

函数介绍

• (void)SdkShareLog;

函数用于获取日志的存储路径。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注

请求示例

{
   
}

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
无	NSString	日志路径	是	返回日志的路径

响应示例

成功

4.7.获取日志路径

函数介绍

• (NSArray*)SdkGetLogPath;

函数用于获取日志的存储路径。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注

请求示例

{
   
}

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
无	NSString	日志路径	是	返回日志的路径

响应示例

成功

/private/var/mobile/Containers/Shared/AppGroup/CAC670B0-B7B2-48B0-831B-C419325C4358/tunnel-log.log

4.8.获取设备id

函数介绍

• (NSString*) getAoneSDKDeviceid;

函数用于获取设备id。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注

请求示例

NSString*deviceid = [LXRVPNSDKClient getAoneSDKDeviceid];

响应

参数列表

参数	参数类型	参数含义	是否必传	备注
无	NSString	设备id	是	返回设备id

响应示例

成功

4.9.更新隐私政策状态

函数介绍

• (void)updateAoneSDKPrivateState:(int)privateState;

函数用于更新隐私政策是否同意状态。

请求

参数列表

参数	参数类型	参数含义	是否必传	备注
privateState	int	隐私政策同意状态	是	1（不同意）｜2（同意）

请求示例

[LXRVPNSDKClient updateAoneSDKPrivateState:2];

响应

参数列表

参数	参数类型	参数含义	是否必传	备注

响应示例

成功

5.错误码

错误码	含义	业务报错
0x10101	初始化的token已过期	初始化token已过期
0x10102	刷新token失败	获取token失败
0x10301	获取资源接口返回数据异常	获取资源接口异常，请重新登陆
0x10302	获取资源接口返回报错（soc）	应用获取异常，请重新登陆
0x10311	获取资源接口返回数据异常	获取资源接口异常，请重新登陆
0x10312	获取资源接口返回报错（aoneid）	应用获取异常，请重新登陆
0x10321	获取边缘节点接口异常	获取资源接口，返回参数异常，请重新登陆
0x10322	获取边缘节点网关返回异常	网关接入异常，请稍后再试
0x10331	获取隧道信息网关数据异常	认证中心返回的隧道内容为空
0x10332	获取隧道信息接口异常	建立隧道失败，请重试
0x11001	隧道启动接口报启动失败	建立隧道失败，请重试
0x90000	未知场景下的一些错误	未知错误