iOS SDK接入

本章节介绍HTTPDNS iOS SDK的使用方法。

前提条件

  • 使用手动添加依赖方式需提前下载SDK包,请参见EMAS快速入门>下载SDK。

  • 使用统一接入添加依赖需提前下载配置文件,请参见EMAS快速入门>下载配置文件。

使用限制

  • 当前只支持静态库,不支持动态库

  • Xcode版本要求:7.0+

样例代码

HTTPDNS IOS SDK接入工程样例参见HTTPDNS iOS Demo

集成步骤

  1. 添加依赖

    1. 方式一:Pod集成

      1. 指定Master仓库和阿里云仓库

        source 'https://github.com/CocoaPods/Specs.git'
        source 'https://github.com/aliyun/aliyun-specs.git'
      2. 添加依赖

        pod 'AlicloudHTTPDNS', '~> 1.19.2.4'
        说明

        ~>为模糊指定版本号方式,~> 1.19.2.4表明引用版本位于1.19.2.4 <= version < 1.20.0之间的最新版本SDK,用户可参考 Podfile Syntax Reference,根据项目需要指定SDK版本。

    2. 方式二:手动集成

      1. 解压下载好的SDK包,在Xcode中,把SDK包目录中的framework拖入对应Target下即可,在弹出框勾选Copy items if needed

        AlicloudBeacon.framework
        AlicloudHttpDNS.framework
        UTDID.framework
        AlicloudUtils.framework
        UTMini.framework
        AlicloudSender.framework
        EMASRest.framework
      2. 在工程项目中(Build Phases -> Link Binary With Libraries)添加以下库文件。

        libsqlite3.0.tbd
        libresolv.tbd
        CoreTelephony.framework
        SystemConfiguration.framework
  2. ObjC配置

    iOS端集成SDK时需要做-ObjC配置,即应用的 TARGETS -> Build Settings -> Linking -> Other Linker Flags ,需添加上 -ObjC 这个属性。

    如何修改编译选项
    注意

    请注意-ObjC的大小写。

  3. 导入头文件

    添加以下代码段:

     #import <AlicloudHttpDNS/AlicloudHttpDNS.h>
  4. SDK初始化配置

    说明

    • HTTPDNS iOS SDK已经完成ATS适配,请求都以HTTPS发出,无需再Info.plist中进行ATS配置。

    • 您可以在下载好的配置文件中或或者在HTTPDNS控制台概览页面查看AccountID。

    • 方式一:手动初始化

      请参照以下代码完成SDK的初始化。

      // 设置 HTTPDNS AccoutID ,当您开通 HTTPDNS 服务时,您可以在控制台获取到您对应的 Accout ID 信息
      HttpDnsService *httpdns = [[HttpDnsService alloc] initWithAccountID::*****];
    • 方式二:自动初始化

      如果您使用了EMAS统一接入,无需配置手动输入AccountID,调用以下接口可完直接进行初始化。

      说明

      使用EMAS统一接入,AliyunEmasServices-Info.plist配置文件中包含SDK初始化所需的配置信息,您只需调用以下接口即可完成初始化,无需手动输入配置信息。

      - (instancetype)autoInit ;
       示例:
       HttpDnsService *httpdns = [[HttpDnsService alloc] autoInit];
    • 方式三:开启鉴权后初始化

      在控制台开启鉴权功能后,SDK需要更改初始化方式,改用下面的方法进行初始化,即可开启鉴权。

      说明

      • 开启鉴权并获取鉴权所需secretKey请参见鉴权配置

      • 目前iOS SDK鉴权时间戳过期时间统一为10分钟,鉴权机制细节参考鉴权解析接口

      • 同时鉴权功能,支持对设备的时间进行校对,对应的方法为请参见iOS SDK API>校正App签名时间。

      /**
       * 启用鉴权功能的初始化接口
       * 初始化 开启鉴权功能 并设置 HTTPDNS 服务 Account ID 和 鉴权功能对应的 secretKey。
       * 您可以从控制台获取您的 Account ID 、secretKey 信息。
       * 此方法会初始化为单例。
       * @param accountId 您的 HTTPDNS Account ID
       * @param secretKey 鉴权对应的 secretKey
       */
      - (instancetype)initWithAccountID:(int)accountID secretKey:(NSString *)secretKey;
  5. 设置预解析域名

    在您初始化程序时,可以选择性的预先向HTTPDNS SDK中注册您后续可能会使用到的域名,以使SDK提前解析,减少后续解析域名时请求的时延。

    详细设置请参考iOS SDK API中设置预解析域名。

注意事项

  1. 务必编写降级代码

    降级代码指的是HTTPDNS无法获取期望结果时的处理代码。请参见设置降级策略相关接口

  2. 记录从HTTPDNS获取的IP及sessinId

    我们提供了用于解析问题排查的解决方案,需要您将从HTTPDNS获取的IP及sessionId记录到日志中,详请客参考解析异常排查之 “会话追踪方案”

  3. 设置HTTP请求头HOST字段

    标准的HTTP协议中服务端会将HTTP请求头HOST字段的值作为请求的域名信息进行解析。使用HTTPDNS后,您可能需要将HTTP请求URL中的HOST字段替换为HTTPDNS解析获得的IP,这时标准的网络库会将您的IP赋值给HTTP请求头的HOST字段,进而导致服务端的解析异常(服务端认可的是您的域名信息,而非IP信息)。

    为了解决这个问题,您可以主动设置HTTP请求HOST字段的值,如:

    NSString *originalUrl = @"http://www.aliyun.com/";
    NSURL* url = [NSURL URLWithString:originalUrl];
    NSMutableURLRequest* request = [[NSMutableURLRequest alloc] initWithURL:url];
    // 同步接口获取IP
    NSString* ip = [httpdns getIpByHostAsync:url.host];
    if (ip) {
        // 通过HTTPDNS获取IP成功,进行URL替换和HOST头设置
        NSRange hostFirstRange = [originalUrl rangeOfString: url.host];
        if (NSNotFound != hostFirstRange.location) {
            NSString* newUrl = [originalUrl stringByReplacingCharactersInRange:hostFirstRange withString:ip];
            request = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:newUrl]];
            // 设置请求HOST字段
            [request setValue:url.host forHTTPHeaderField:@"host"];
        }
    }
  4. Cookie字段

    部分网络库支持COOKIE的自动存储管理,当您使用HTTPDNS进行IP URL请求时,部分网络库会将您URL中的IP信息作为COOKIE对应的域名信息进行存储管理(而非HTTP请求头HOST字段信息),进而造成COOKIE管理与使用上的困扰,因此您需要关闭COOKIE的自动管理功能(默认关闭)。

  5. HTTPS/WebView/SNI场景

    HTTPS场景 ,请参考iOS端HTTPS(含SNI)业务场景“IP直连”方案说明。

    WebView场景,请参考iOS端WebView " IP直连 " 如何处理 Cookie。

  6. 代理情况下的使用

    当存在中间HTTP代理时,客户端发起的请求中请求行会使用绝对路径的URL,在您开启HTTPDNS并采用IP URL进行访问时,中间代理将识别您的IP信息并将其作为真实访问的HOST信息传递给目标服务器,这时目标服务器将无法处理这类无真实HOST信息的HTTP请求。移动网关提供了X-Online-Host的私有协议字段来解决这个问题,比如:

    目标 URL:http://www.aliyun.com/product/oss/
    通过 HTTPDNS 解析出来的www.aliyun.com的IP:1.1.1.1
    代理:10.0.0.172:80
    
    您的HTTP请求头:
    
    GET http://1.1.1.1/product/oss/ HTTP/1.1     # 通过代理发起的HTTP请求头,请求行是一个绝对路径
    Host: www.aliyun.com   # 这个Header会被代理网关忽略,代理网关会使用请求行绝对路径中的host字段作为源站的host,即1.1.1.1
    X-Online-Host: www.aliyun.com    # 这个Header就是移动网关为了传递真实Host添加的私有头部,源站需要配置识别该私有头部以获取真实的Host信息

    同样您可以通过下述方法进行X-Online-Host请求头域的设置,并在服务端设置对该私有头域的解析。

    [request setValue:url.host forHTTPHeaderField:@"X-Online-Host"];
    说明

    在绝大多数场景下,我们建议您在代理模式下关闭HTTPDNS功能。

集成常见问题

UTDID冲突,可参考:阿里云-移动云产品SDK UTDID冲突解决方案。