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:認證頁面域名比如 //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	未知場景下的一些錯誤	未知錯誤