使用

• 下载并接入产品配置
• 初始化
  • 前置条件
  • 初始化步骤
    • 初始化示例
• 功能介绍
  • 业务请求
    • 前提条件
    • 请求接口
      • 命令字设置
      • 请求头设置
      • 数据请求示例
    • 取消请求接口
  • 设备标识
    • GUID
      • 同步读取接口
      • 异步获取接口
      • 异步注册/更新接口
    • VID
      • 异步请求接口
  • 国密请求
    • 实现代理方法

下载并接入产品配置

1. 从控制台下载您的产品的配置文件 TMFConfigurations.h，并加入到您的项目中。

2. 在控制台首页的产品列表，找到您的产品，选择应用配置下载 > 下载 iOS 配置，下载 TMFConfigurations.h。

3. 把 TMFConfigurations.h 加入到您的项目。
   
   在 TMFConfigurations.h 中，包含网关的相关配置。

初始化

在通过 TMFShark 发起业务请求前，必须先初始化网关服务配置。

前置条件

请确保在 进程启动后的第一时间、业务请求前，完成对 TMFShark 进行初始化配置（如服务器地址、加密方式、公钥等配置），以确保 TMFShark 能够正常进行网络通信。

推荐在 -[AppDelegate application:didFinishLaunchingWithOptions:] 中，尽可能往前执行 TMFShark 的初始化。

初始化步骤

1. 引入头文件。

   #import "TMFConfigurations.h"    // 产品配置文件
   #import "TMFSharkCenter.h"        // TMFSharkCenter
   

2. 初始化配置，通过 -[TMFSharkCenterConfiguration masterConfiguration] 获得 master configuration 实例，然后进行初始化配置。

    TMFSharkCenterConfiguration *masterConfiguration = [TMFSharkCenterConfiguration masterConfiguration];
   
    masterConfiguration.productID = TMF_PID;                // 产品 ID
    masterConfiguration.HTTPURL = TMF_GW_HTTP_URL;    // HTTP 通道的服务器 URL
   
    masterConfiguration.productKey = TMF_APP_KEY;        // 产品 Key ID
    masterConfiguration.RSAPublicKey = TMF_GW_RKEY;    // RSA 公钥
    masterConfiguration.SM2PublicKey = TMF_GW_SKEY;    // 国密 SM2 公钥
   
    masterConfiguration.customerID = TMF_CUSTOM_ID;    // 客户 ID
    masterConfiguration.delegate = self;                // 国密NSURLSession代理（若需要走国密通道）
   

   其中，TMF_PID、TMF_GW_HTTP_URL 等字段在产品配置 TMFConfigurations.h 文件中定义。

3. 执行初始化，完成 master configuration 的配置后，调用 TMFSharkCenter 的初始化接口执行初始化。

   [[TMFSharkCenter masterCenter] initialize];
   

初始化示例

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

      // 初始化配置
    TMFSharkCenterConfiguration *masterConfiguration = [TMFSharkCenterConfiguration masterConfiguration];

    masterConfiguration.productID = TMF_PID;                // 产品 ID
    masterConfiguration.HTTPURL = TMF_GW_HTTP_URL;    // HTTP 通道的服务器 URL

    masterConfiguration.productKey = TMF_APP_KEY;        // 产品 Key ID
    masterConfiguration.RSAPublicKey = TMF_GW_RKEY;    // RSA 公钥
    masterConfiguration.SM2PublicKey = TMF_GW_SKEY;    // 国密 SM2 公钥

    masterConfiguration.customerID = TMF_CUSTOM_ID;    // 客户 ID

    masterConfiguration.delegate = self;                // 国密NSURLSession代理（若需要走国密通道）
      // 执行初始化
    [[TMFSharkCenter masterCenter] initialize];
}

功能介绍

业务请求

若要通过网关进行业务请求，请使用 -[TMFSharkCenter masterCenter] 获得 master center 实例，然后进行业务请求。

前提条件

若要通过网关进行业务请求，必须先初始化网关服务配置。请参见 初始化配置。

请求接口

通过调用数据请求接口，以进行业务接口的请求，并通过接口回调，取得业务请求的结果。

接口定义

- (TMFSharkRequestIdentifier)requestWithCmdSettings:(TMFOCSharkCmdSettings *)cmdSettings
                                     requestHeaders:(nullable TMFSharkRequestHeaders *)requestHeaders
                                        requestData:(nullable NSData *)requestData
                                  completionHandler:(nullable TMFSharkRequestDataCompletionHandler)completionHandler;

其中，TMFSharkRequestDataCompletionHandler 的定义如下：

typedef void (^TMFSharkRequestDataCompletionHandler) (
      TMFSharkResponseHeaders * _Nullable responseHeaders,
       NSData * _Nullable responseData,
      NSError * _Nullable error
);

参数说明

• completionHandler 回调

• 返回值

命令字设置

业务命令字设置包含当前业务请求的关键信息，如当前业务请求的业务命令字（cmd）、配置、数据类型等。

通过创建 TMFOCSharkCmdSettings 实例进行命令字设置。

TMFOCSharkCmdSettings

• +settings

  创建 TMFOCSharkCmdSettings 实例。

  + (instancetype)settings;
  

• cmd

  设置当前请求的业务 cmd，相当于服务端业务接口的名字。

  @property (nonatomic, copy, nullable) NSString *cmd;
  

• timeoutIntervalForRequest

  设置当前请求的超时时间。

  @property (nonatomic, assign) NSTimeInterval timeoutIntervalForRequest;
  

  默认为 0，表示与当前请求的 TMFSharkCenter 的 configuration.timeoutIntervalForRequest 保持一致。

请求头设置

设置请求的头部，如 HTTP 头部、Cookies、URL queries 等，网关会把客户端请求的头部信息转发到服务端的业务侧。

TMFSharkRequestHeaders

• +headers

  创建 TMFSharkRequestHeaders 实例。

• headers

  设置业务 HTTP 头部。

  @property (nonatomic, retain, readonly) NSMutableDictionary<NSString *, NSString *> *headers;
  

• cookies

  设置业务 HTTP Cookies。

  @property (nonatomic, retain, readonly) NSMutableDictionary<NSString *, NSString *> *cookies;
  

• queries

  设置业务 HTTP URL queries。

  @property (nonatomic, retain, readonly) NSMutableDictionary<NSString *, NSString *> *queries;
  

数据请求示例

    // 业务命令字设置
    TMFOCSharkCmdSettings *cmdSettings = [TMFOCSharkCmdSettings settings];
    cmdSettings.cmd = @"TMFEcho"; // 设置业务命令字 ID

    // 业务请求头部
    TMFSharkRequestHeaders *requestHeaders = [TMFSharkRequestHeaders headers];
    requestHeaders.headers[@"header_key1"] = @"header_value1";
    requestHeaders.cookies[@"cookie_key1"] = @"cookie_value1";
    requestHeaders.queries[@"query_key1"]  = @"query_value1";

    // 请求的数据
    NSString *requestString = @"Hello TMF";
    NSData *requestData = [requestString dataUsingEncoding:NSUTF8StringEncoding];

    /** 发起请求 **/
    TMFSharkRequestIdentifier requestID = [[TMFSharkCenter masterCenter] requestWithCmdSettings:cmdSettings requestHeaders:requestHeaders requestData:requestData completionHandler:^(TMFSharkResponseHeaders * _Nullable responseHeaders, NSData * _Nullable responseData, NSError * _Nullable error) {
        /** 处理请求回调 **/

          // 业务解析数据
        NSString *responseString = nil;
        if (responseData) {
            responseString = [[[NSString alloc] initWithData:responseData encoding:NSUTF8StringEncoding] autorelease];
        }
        NSLog(@"did finish request, data: %@, error: %@", responseString, error);
    }];

取消请求接口

若要取消一个已发送、但未完成的业务请求，可以通过调用取消请求接口进行取消。

接口定义

- (void)cancelRequest:(TMFSharkRequestIdentifier)requestIdentifier;

参数

设备标识

GUID

GUID 是 App 级别的设备 ID，其生命周期与 App 安装、卸载的生命周期一致。 如果卸载 App 然后重装，GUID 将发生变化。

终端的移动网关组件在注册 GUID 时，会上报各种软硬件信息。服务端生成 GUID，并会把这些信息和 GUID 关联，下发到终端。终端的移动网关组件接收到 GUID 后，会把 GUID 存储在 App 内。

每次业务请求时，组件会把 GUID 带上，服务端即可知道当前请求来源于哪个设备。

同步读取接口

同步读取接口会读取终端组件存储的 GUID 并返回。如果终端组件还没注册 GUID，则返回 nil。

接口定义

@property (nonatomic, readonly, nullable) NSString *GUID;

异步获取接口

异步获取接口会判断终端组件是否已注册 GUID 并存储。 如果终端组件已注册 GUID，则异步返回已注册的 GUID。否则，终端组件将发起注册 GUID 的请求，并异步回调服务端返回的结果。

接口定义

- (void)fetchGUID:(TMFSharkGUIDCompletion)completion;

其中，TMFSharkGUIDCompletion 的定义如下：

typedef void (^TMFSharkGUIDCompletion)(
      NSString * _Nullable GUID,
      NSError * _Nullable error
);

• 参数

• completion 回调

异步注册/更新接口

异步注册/更新接口会强制发起注册/更新 GUID 的请求，并异步回调服务端返回的结果。

接口定义

- (void)updateGUID:(TMFSharkGUIDCompletion)completion;

其中，TMFSharkGUIDCompletion 的定义如下：

typedef void (^TMFSharkGUIDCompletion)(
      NSString * _Nullable GUID,
      NSError * _Nullable error
);

• 参数

• completion 回调

VID

VID 是设备级别的设备 ID，其生命周期与设备 iOS 系统的生命周期一致。 如果卸载 App 然后重装，VID 不会发生变化。

终端的移动网关组件在注册 VID 时，会上报各种软硬件信息。服务端生成 VID 和 token，并会把这些信息和 VID 关联，把 token 下发到终端。终端的移动网关组件接收到 token 后，会把 token 存储起来。

注意，终端只会存储 token，不会存储 VID。

每次业务请求的时候，组件会把 token 带上，服务端获取到 token 后，可以反查出 VID，即可知道当前请求来源于哪个设备。

异步请求接口

异步请求接口会使用终端组件存储的 token 发起获取 VID 的请求，并异步回调服务端返回的结果。

接口定义

- (void)fetchVID:(TMFSharkVIDCompletion)completion;

其中，TMFSharkVIDCompletion 的定义如下：

typedef void (^TMFSharkVIDCompletion)(
      NSString * _Nullable VID,
      NSError * _Nullable error
);

• 参数

• completion 回调

国密请求

实现代理方法

在初始化网关的TMFSharkCenterConfiguration设置的delegate对象中，实现：

- (NSURLSession *_Nonnull)sessionWithConfiguration:(NSURLSessionConfiguration *_Nonnull)configuration delegate:(_Nonnull id)delegate delegateQueue:(nullable NSOperationQueue *)queue{
    if (!self.session) {
        self.session = [TMFGMURLSession sessionWithConfiguration:configuration delegate:delegate delegateQueue:queue];
        self.session.cipher_list = @"xx";
        self.session.cacert = @"xx";
        self.session.signcert = @"xx";
        self.session.signkey = @"xx";
        self.session.enccert = @"xx";
        self.session.enckey = @"xx";
        self.session.verifyPeer = @"xx";
        self.session.verifyHost = @"xx";
        self.session.host = @"xx";
        self.session.tls13_ciphers = @"xx";
    }
    return self.session;
}

当产生网络请求时，实现：

- (NSURLSessionTask *_Nonnull)dataTaskWithRequest:(NSURLRequest *_Nonnull)request{
    TMFGMSessionDataTask *secondtask = [self.session dataTaskWithRequest:request completionHandler:nil];
    return secondtask;
}

或参考TMFBase的方式实现国密。