Install HTTPDNS SDK for iOS - HTTPDNS - Alibaba Cloud Documentation Center

This topic describes how to install HTTPDNS SDK for iOS.

Prerequisites

If you need to manually add dependencies, please download the SDK package. The latest version is V2.0.8-intl.
You need to download the configuration file on the console if you want to add dependencies by using unified access.

Limits

Only static libraries are supported. Dynamic libraries are not supported.
The version of Xcode must be 7.0 or later.

Sample code

For information about the sample projects of HTTPDNS SDK for iOS, see HTTPDNS iOS Demo.

Procedure

Add dependencies
1. Method 1: Use the AlicloudHTTPDNS pod
  1. Specify the CocoaPods master repository and Alibaba Cloud CocoaPods repository:
```
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/aliyun/aliyun-specs.git'
```
  2. Add dependencies:
```
pod 'AlicloudHTTPDNS', '2.0.8-intl'
```
2. Method 2: Manually add dependencies
  1. Decompress the SDK package. In Xcode, drag the framework from the SDK package to the corresponding Target and select Copy items if needed in the dialog box that appears:
```
AlicloudBeacon.framework
AlicloudHttpDNS.framework
UTDID.framework
AlicloudUtils.framework
UTMini.framework
AlicloudSender.framework
EMASRest.framework
```
  2. Find the project, click the Build Phases tab, and then add the following library files in the Link Binary With Libraries section:
```
libsqlite3.0.tbd
libresolv.tbd
CoreTelephony.framework
SystemConfiguration.framework
```
Configure ObjC
On the TARGETS page, click the Build Settings tab. Add the -ObjC flag to Other Linker Flags in the Linking section.
Notice
-ObjC is case-sensitive.

Import the header file

Add the following code:

 #import <AlicloudHttpDNS/AlicloudHttpDNS.h>

Configure SDK initialization
Note
- App Transport Security (ATS) is configured for HTTPDNS SDK for iOS. Requests are sent over HTTPS. You do not need to configure ATS in the Info.plist file.
- You can obtain the account ID from the configuration file.
- Method 1: Manually initialize the SDK
  Run the following code to initialize the SDK:
```
// Specify the account ID of HTTPDNS. When you activate the HTTPDNS service, you can obtain the account ID in the HTTPDNS console.
HttpDnsService *httpdns = [[HttpDnsService alloc] initWithAccountID::*****];
```
- Method 2: Enable the authentication feature and then initialize the SDK
  After you enable the authentication feature in the HTTPDNS console, you must change the initialization method of the SDK. Run the following code to initialize the SDK and configure authentication.
  Note
  - For information about how to enable the authentication feature and obtain the secret that is required for authentication, see Configure authentication.
  - The authentication timestamps of HTTPDNS SDK for iOS are valid for 10 minutes. For more information about authentication, see Authentication.
  - You can use the authentication feature to correct the time of your device. For more information, see Initialization.
```
/**
 * Enable the initialization API of the authentication feature.
 * Initialize the SDK, enable the authentication feature, and specify the HTTPDNS account ID and the secret that is required for the authentication feature. 
 * You can obtain your account ID and secret from the HTTPDNS console. 
 * This initialization in implemented in singleton pattern. 
 * @param accountId: The HTTPDNS account ID.
 * @param secretKey: The secret that is required for authentication.
 */
- (instancetype)initWithAccountID:(int)accountID secretKey:(NSString *)secretKey;
```
Configure a DNS prefetch
When you implement the initialization, you can register domain names that you may use with HTTPDNS SDK for iOS. This way, the SDK can resolve the domain names in advance. This reduces the latency of requests during subsequent DNS resolution.
For more information, see Preference settings.

Usage notes

Write degradation rule code.
Degradation rule code refers to the code that is used when HTTPDNS cannot obtain expected results. For more information, see Configure a degradation policy.
Record the IP address and session ID obtained from HTTPDNS.
A solution is provided to troubleshoot the issues that may occur during resolution based on logs. You must record the IP address and session ID that are obtained from HTTPDNS in logs.

Configure the HOST field in the HTTP request header.

In the standard HTTP protocol, the server resolves the value of the HOST field in the HTTP request header as the domain name of the request. When you use HTTPDNS, you may need to replace the value of the HOST field of the HTTP request header with the resolved IP address. The standard network library assigns your IP address to the HOST field of the HTTP request header. In this case, a resolution error may occur on the server because the server can identify your domain name, but cannot identify the IP address.

To fix the error, you can configure the HOST field of the HTTP request header. Example:

NSString *originalUrl = @"http://www.aliyun.com/";
NSURL* url = [NSURL URLWithString:originalUrl];
NSMutableURLRequest* request = [[NSMutableURLRequest alloc] initWithURL:url];
// Obtain the IP address by calling the synchronization API.
NSString* ip = [httpdns getIpByHostAsync:url.host];
if (ip) {
    // Obtain the IP address by using HTTPDNS, replace the value of the HOST field of the HTTP request header with the resolved IP address, and then configure the HOST Header.
    NSRange hostFirstRange = [originalUrl rangeOfString: url.host];
    if (NSNotFound != hostFirstRange.location) {
        NSString* newUrl = [originalUrl stringByReplacingCharactersInRange:hostFirstRange withString:ip];
        request = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:newUrl]];
        // Configure the HOST field in the HTTP request header.
        [request setValue:url.host forHTTPHeaderField:@"host"];
    }
}

Disable cookies.
Some network libraries automatically store and manage cookies. If you use HTTPDNS to send access requests from a URL, these network libraries store and manage the IP address in your URL as the domain name in cookies, but does not store or manage the value of the host field in the HTTP request header. Therefore, the network libraries cannot store and manage valid information as expected. To fix this issue, you must disable cookies. By default, cookies are disabled.
Connect an iOS app to an IP address in HTTPS, WebView, or SNI scenarios.
For information about how to connect an iOS app to an IP address in HTTPS scenarios, see Connect an iOS app to an IP address over HTTPS (including scenarios in which SNI is required).
For information about how to connect an iOS app to an IP address in WebView scenarios, see Connect an iOS app to an IP address over WebView.

Use HTTPDNS in proxy mode.

If you use an HTTP proxy, absolute URLs are specified in the request line of the requests that are initiated by clients. When you enable HTTPDNS and send access requests from a URL, the HTTP proxy identifies your IP address and pass it to the destination server as the host address. In this case, the destination server cannot process such HTTP requests because the requests do not contain valid host addresses. Mobile Gateway Service (MGS) provides the private fields of the X-Online-Host header to resolve the problem. Example:

Destination URL: http://www.aliyun.com/product/oss/
IP address resolved by HTTPDNS: 1.1.1.1 for www.aliyun.com
HTTP proxy: 10.0.0.172:80

HTTP request header:

GET http://1.1.1.1/product/oss/ HTTP/1.1 # The HTTP request header of the request that is initiated over the proxy. The request line is an absolute URL.
Host: www.aliyun.com.   # This header is ignored by the proxy gateway. The proxy gateway uses the value of the host field (1.1.1.1) in the absolute URL of the request line as the host address of the source site.
X-Online-Host: www.aliyun.com    # The header is the private header added by MGS to pass the actual host address. You must configure the source site to identify the private header and obtain the actual host address

You can also run the following code to configure the X-Online-Host request header and resolve the private header on the server:

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

Note

We recommend that you do not use the HTTPDNS service in proxy mode.