All Products
Search
Document Center

iOS SDK Developer Guide

Last Updated: Sep 16, 2020

This topic describes Alibaba Cloud public DNS SDK for iOS and how to use the SDK.

1. Overview

Alibaba Cloud public DNS SDK is developed by Alibaba Cloud to provide a DNS resolution service for mobile developers.

The SDK allows mobile developers to use Alibaba Cloud public DNS in their iOS apps. This prevents DNS resolution errors and implements precise scheduling of DNS queries at a low cost. The demo project source code provides you with an example of integrating the SDK with an iOS app and using Alibaba Cloud public DNS in the iOS app.

The SDK encapsulates the JSON API for DoH of Alibaba Cloud public DNS. Specifically, it provides Java function interfaces for iOS apps to perform DNS resolution. The SDK also supports efficient domain name caching based on time to live (TTL) and least recently used (LRU) policies. Based on the features of Alibaba Cloud public DNS, the SDK has the following benefits:

  • Easy to use:

    To use Alibaba Cloud public DNS, you only need to integrate the SDK with your app. This allows you to use the resolution service in an easier and more convenient manner.

  • DNS resolution without delay:

    The SDK implements the LRU caching algorithm so that the IP addresses obtained from DNS resolution are cached on your local server. The SDK also automatically updates the cache and deletes expired data based on TTL. This way, the cached data is always valid and DNS resolution can be effectively implemented without delay.

2. SDK integration

2.1 SDK integration

  1. Log on to the Alibaba Cloud DNS console. In the left-side navigation pane, click Public DNS. On the Public DNS page, activate Alibaba Cloud public DNS. The Overview tab displays the unique account ID that is automatically generated for your Alibaba Cloud account. You can use this account ID to use Alibaba Cloud public DNS in your app.

  2. On the SDK Download tab, click the download link for iOS to download Alibaba Cloud public DNS SDK for iOS.

  3. Add the pdns-sdk-ios.framework folder in the SDK to your iOS app.

  4. Import the following system libraries to your app:

    • Foundation.framework

    • SystemConfiguration.framework

    • CoreFoundation.framework

  5. Call the application:didFinishLaunchingWithOptions: method in your app to initialize the SDK. Use the following code in the method:

DNSResolver *resolver = [DNSResolver share];
resolver.accountId = @"Account ID that was generated after you activated Alibaba Cloud public DNS";

2.2 Auto-integration (Cocoapods)

1.Specify the warehouse location in the Profile (Don't leave the Master repository out)

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/aliyun/aliyun-specs.git'

2.Add dependencies for the project Target:

pod 'AlicloudPDNS'

3. API reference

3.1 accountId

The accountId parameter specifies the account ID that is automatically generated after you activate Alibaba Cloud public DNS. The account ID is required for calling each service API operation by using Alibaba Cloud public DNS SDK.

3.2 ipv6Enable

Alibaba Cloud public DNS supports IPv4 and IPv6 dual-stack access. By default, the SDK uses IPv4 addresses to connect to the DNS server.

If you need to use IPv6 addresses to connect to the DNS server, make sure that the current network supports IPv6 addresses and then use the ipv6Enable parameter to enable IPv6 access, as shown in the following code snippet:

[DNSResolver share].ipv6Enable = YES;

3.3 shortEnable

Data that is returned by the JSON APIs for DoH of Alibaba Cloud public DNS can be in the JSON format or an array of IP addresses. By default, the SDK uses the JSON format.

If you need returned data to be arrays of IP addresses, use the shortEnable parameter to enable the short mode, as shown in the following code snippet:

[DNSResolver share].shortEnable = YES;

3.4 scheme

You can use the scheme parameter to specify whether to use HTTP or HTTPS for DNS resolution.

By default, the SDK uses HTTP for resolution. We recommend that you do not change the default configuration because HTTP-based resolution is faster. If you need to use HTTPS for resolution, use the scheme parameter, as shown in the following code snippet:

[DNSResolver share].scheme = DNSResolverSchemeHttps;

3.5 cacheCountLimit

The SDK provides the cache feature. When a domain name is resolved for the first time, the resolution result is cached, so that subsequent resolution of this domain name becomes much quicker.

By default, resolution results for a maximum of 100 domain names can be cached by using the SDK. You can use the cacheCountLimit parameter to set a custom maximum cache size, as shown in the following code snippet:

// Set a custom maximum cache size.
[DNSResolver share].cacheCountLimit = 200;

3.6 timeout

The timeout parameter specifies a timeout period for DNS resolution. The default timeout period is 3 seconds. You can set a custom timeout period as needed. We recommend that you set the timeout period in the range of 2 to 5 seconds.

3.7 Preload domain names to be resolved

The cache feature provided by the SDK makes it quicker to resolve a domain name that has been resolved before. We recommend that after you start your app, you preload the domain names to be resolved.

The following code snippet shows an example of preloading domain names to be resolved:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Override point for customization after application launch.
   
    DNSResolver *resolver = [DNSResolver share];
   resolver.accountId = @"Account ID that was generated after you activated Alibaba Cloud public DNS";

   // Preload domain names to be resolved.
   [resolver preloadIpv4Domains:@[@"Domain name 1", @"Domain name 2", @"Domain name 3"] complete:^{
       // All the specified domain names are preloaded.
       
   }];
   
   return YES;
}

4. Service API operations

The following code snippet shows all the service API operations that you can call by using Alibaba Cloud public DNS SDK for iOS:

/// Obtain an array of information about IPv4 addresses to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return information about all the IPv4 addresses to which the domain name is resolved.
- (void)getIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// Obtain an array of information about IPv6 addresses to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return information about all the IPv6 addresses to which the domain name is resolved.
- (void)getIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// Obtain information about an IPv4 address to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return information about one of the IPv4 addresses to which the domain name is resolved.
- (void)getRandomIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// Obtain information about an IPv6 address to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return information about one of the IPv6 addresses to which the domain name is resolved.
- (void)getRandomIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// Obtain an array of IPv4 addresses to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return all the IPv4 addresses to which the domain name is resolved.
- (void)getIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Obtain an array of IPv6 addresses to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return all the IPv6 addresses to which the domain name is resolved.
- (void)getIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Obtain an IPv4 address to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return one of the IPv4 addresses to which the domain name is resolved.
- (void)getRandomIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// Obtain an IPv6 address to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return one of the IPv6 addresses to which the domain name is resolved.
- (void)getRandomIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// Pre-resolve an array of domain names to IPv4 addresses. Call this operation after you start your app. This accelerates subsequent DNS resolution.
/// @param domainArray  The array of domain names to be resolved.
/// @param complete         Return resolution results.
- (void)preloadIpv4Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Pre-resolve an array of domain names to IPv6 addresses. Call this operation after you start your app. This accelerates subsequent DNS resolution.
/// @param domainArray  The array of domain names to be resolved.
/// @param complete         Return resolution results.
- (void)preloadIpv6Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Query cache to obtain an IPv4 address that maps a domain name to be resolved.  If the domain name has not been resolved before or its resolution result has expired in the cache, the response is nil.
/// @param domain   The domain name to be resolved.
- (NSArray<NSString *> *)getIpv4ByCacheWithDomain:(NSString *)domain;

/// Query cache to obtain an IPv6 address that maps a domain name to be resolved.  If the domain name has not been resolved before or its resolution result has expired in the cache, the response is nil.
/// @param domain   The domain name to be resolved.
- (NSArray<NSString *> *)getIpv6ByCacheWithDomain:(NSString *)domain;

5. API call examples

5.1 Initialize the SDK in your app

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Override point for customization after application launch.

    // The only method for initialization.
   DNSResolver *resolver = [DNSResolver share];
// The required parameter.
   resolver.accountId = @"Account ID that was generated after you activated Alibaba Cloud public DNS";
   
   return YES;
}

5.2 Resolve a domain name by calling an operation

Alibaba Cloud public DNS SDK supports resolving domain names to IPv4 and IPv6 addresses. All the preceding service API operations are described in the header file DNSResolver.h in the SDK. In this example, the getRandomIpv4DataWithDomain operation is called to resolve a domain name to an IPv4 address.

The following code snippet shows the declaration of the getRandomIpv4DataWithDomain operation:

/// Obtain an IPv4 address to which a domain name is resolved.
/// @param domain           The domain name to be resolved.
/// @param complete       Return one of the IPv4 addresses to which the domain name is resolved.
- (void)getRandomIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

The following code snippet shows an example of calling the operation:

[[DNSResolver share] getRandomIpv4DataWithDomain:@"www.taobao.com" complete:^(NSString *data) {
   // The data string is the returned IPv4 address that maps the domain name www.taobao.com.
   if (data.length > 0) {
       // TODO: Use the IP address to send a business request.
       
   }
}];

5.3 Query cache to obtain an IP address that maps a domain name to be resolved

The following code snippet shows the declarations of the getIpv4ByCacheWithDomain and getIpv6ByCacheWithDomain operations:

/// Query cache to obtain an IPv4 address that maps a domain name to be resolved.  If the domain name has not been resolved before or its resolution result has expired in the cache, the response is nil.
/// @param domain   The domain name to be resolved.
- (NSArray<NSString *> *)getIpv4ByCacheWithDomain:(NSString *)domain;
 
/// Query cache to obtain an IPv6 address that maps a domain name to be resolved.  If the domain name has not been resolved before or its resolution result has expired in the cache, the response is nil.
/// @param domain   The domain name to be resolved.
- (NSArray<NSString *> *)getIpv6ByCacheWithDomain:(NSString *)domain;
 

The following code snippet shows an example of calling the getIpv4ByCacheWithDomain operation:

NSArray *result = [[DNSResolver share] getIpv4ByCacheWithDomain:@"Domain name"];
// An IP address that maps the domain name is obtained from the cache.
if (result.count > 0) {
   // TODO: Use the IP address to send a business request.
   
}

It is quicker to query resolution results from the cache than to perform DNS resolution. Note that if the domain name to be resolved has not been resolved before or its resolution result has expired in the cache, the response is nil.

6. Usage notes

  1. The pdns-sdk-ios.framework folder supports only iOS 9.0 or higher.

  2. If you use HTTP for DNS resolution, you must set App Transport Security Settings->Allow Arbitrary Loads to YES in the Info.plist file.

  3. After you use Alibaba Cloud public DNS to resolve a domain name to an IP address, you can use the IP address to send business requests. You must specify the host field in the HTTP request header as the domain name that has been resolved.

    The following code snippet shows an example:

    // Specify the ip string as an IP address to which a domain name is resolved.
    NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"https://%@", ip]];
    NSMutableURLRequest *mutableReq = [NSMutableURLRequest requestWithURL:url cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval: 10];
    // Specify the host field as the domain name.
    [mutableReq setValue:@"Domain name" forHTTPHeaderField:@"host"];

  4. A demo project makes it easy for you to understand how to use Alibaba Cloud public DNS SDK.

    You can download it for reference. For more information, download the demo project.