This topic describes the basic configuration operations of HTTPDNS SDK for iOS.
Initialization
You can use this operation to create a global HTTPDNS service instance. This instance uses the singleton design pattern. After the instance is initialized, it exists throughout the lifecycle of the app. You do not need to create the instance repeatedly. After the instance is created for the first time, you can directly call the [HttpDnsService sharedInstance] operation to obtain the service instance when you need to use it during the lifecycle of the app.
This operation provides two versions, which are used for scenarios that do not require encryption and scenarios that require encryption. If you enable encryption, the SDK uses the Advanced Encryption Standard (AES) algorithm to encrypt request parameters and response results when the SDK sends requests to the server. Encryption provides higher security, but the billing logic is different. For more information about billing, see Product billing.
Make sure that you call this operation to complete initialization before you use the HTTPDNS resolution operation. Otherwise, the resolution fails. We recommend that you complete initialization in applicationDidFinishLaunching.
Operation definition
- (nonnull instancetype)initWithAccountID:(NSInteger)accountID secretKey:(NSString * _Nonnull)secretKey;
- (nonnull instancetype)initWithAccountID:(NSInteger)accountID secretKey:(NSString * _Nonnull)secretKey aesSecretKey:(NSString * _Nullable)aesSecretKey;
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
accountId | int | Yes | The account ID assigned by the system. After you activate HTTPDNS, you can obtain the Alibaba Cloud account ID in the console. |
secretKey | NSString | Yes | The secret key for authentication. You can obtain the secret key in the HTTPDNS console. |
aesSecretKey | NSString | No | The AES secret key for encryption. You can obtain the AES secret key in the HTTPDNS console. If you set this parameter, the SDK enables the encryption feature. |
Obtain a service instance
After you create a global HTTPDNS service instance, you can obtain a global singleton by calling this operation when you need to configure HTTPDNS or use HTTPDNS to resolve domain names.
Operation definition
+ (instancetype)sharedInstance;
Class
HttpDnsService
Use HTTPS requests
You can use this operation to specify whether to use HTTPS when the SDK sends resolution requests to the server. If you do not call this operation, HTTP is used by default.
HTTPS requests provide higher security, but you need to pay attention to the differences in billing between HTTP and HTTPS. For more information about billing, see Product billing.
HTTP requests are processed based on the underlying CFNetwork framework, and are not affected by applicant tracking systems (ATSs).
Whether encryption is still required when HTTPS requests are used: The two features work at different layers. The HTTPS protocol ensures transport layer security, but parameters and response details can still be viewed through packet capture. AES encryption ensures the security of the HTTPDNS business layer. Even if packets are captured, the plaintext content cannot be viewed. Therefore, you can decide whether to enable both features based on your requirements.
Operation definition
- (void)setHTTPSRequestEnabled:(BOOL)enable;
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
enable | BOOL | Yes | Valid values: YES: uses HTTPS NO: uses HTTP |
Allow expired IP addresses
HTTPDNS SDK for iOS follows the DNS protocol and caches domain name resolution results based on the time to live (TTL) to improve the efficiency of obtaining IP addresses when the app initiates network requests. When the cache expires, different situations may occur if the app calls the resolution operation to obtain IP addresses:
If the app calls a synchronous non-blocking operation, the cache has expired, but the SDK cannot immediately obtain new resolution results from the server. To avoid blocking the thread, the operation returns an empty result. The caller needs to handle the fallback to local DNS resolution.
If the app calls a synchronous operation or an asynchronous operation, the SDK initiates a resolution request to obtain new resolution results from the server. This process takes some time. The synchronous operation blocks the thread until new resolution results are obtained. The asynchronous operation calls back
completionHandleronly after new resolution results are obtained.
The SDK provides a setting option to allow the reuse of expired IP addresses. If you set this option to YES, in the preceding two situations, even if the cached IP address has expired, the operation can immediately return the expired IP address to reduce the processing time of the DNS phase and improve the performance of network requests. At the same time, after the SDK detects that the IP address has expired and returns the IP address, the SDK immediately starts an asynchronous thread to resolve the domain name to obtain new resolution results.
Therefore, the side effects of enabling this option are minimal, especially when the resolution configuration of the domain name to be resolved does not change frequently (such as the domain name of the primary site or the domain name of the static gateway). If the domain name resolution changes, enabling this option affects only the first request after the domain name cache expires. This is because when the SDK is called and detects that the IP address has expired, the SDK immediately initiates a resolution update for the domain name.
By default, expired IP addresses cannot be returned.
If the IP addresses of your business servers change frequently, we recommend that you enable this feature with caution to avoid affecting your business.
In version 2.x.x and earlier, this operation is defined as
- (void)setExpiredIPEnabled:(BOOL)enable.
Operation definition
- (void)setReuseExpiredIPEnabled:(BOOL)enable;
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
enable | BOOL | Yes | Specifies whether to allow the resolution operation to return cached resolution results with an expired TTL. YES: allows expired IP addresses to be returned NO: does not allow expired IP addresses to be returned |
Enable persistent cache
The persistent cache feature is designed to optimize the time consumed by domain name resolution after startup, thereby improving the loading speed of the first screen.
If you enable this feature, HTTPDNS saves the latest resolution result to the local persistent layer. After your app restarts, the first resolution for each domain name will prioritize fetching the cached result from the persistent layer to achieve the fastest resolution efficiency. However, this approach may result in the initial IP address being an expired one, because the TTL of the cached result may have expired. In most cases, this IP address is available, particularly for domain names with stable and consistent resolution records.
To avoid the app reusing cached results that have been expired for too long after startup (for example, the app was last started a month ago), this operation provides the discardRecordsHasExpiredFor：(NSTimeInterval)duration parameter from version 3.1.2. This parameter determines whether to discard resolution results that have been expired for more than duration when the app loads the cache from the persistent layer to the memory after startup. We recommend that you set this parameter to 1 day.
This switch is turned off by default.
If the IP addresses of your business servers change frequently, we recommend that you enable this feature with caution to avoid affecting your business.
The persistent cache feature affects only the result of the first domain name resolution. Subsequent resolution requests are sent to the HTTPDNS server, and the local cache is updated.
After the persistent cache feature is enabled, the DNS records are updated to the local cache. After the app is restarted, the local cache is loaded to the memory.
In version 2.x.x and earlier, this operation is defined as
- (void)setCachedIPEnabled:(BOOL)enable;
Operation definition
- (void)setPersistentCacheIPEnabled:(BOOL)enable;
- (void)setPersistentCacheIPEnabled:(BOOL)enable discardRecordsHasExpiredFor:(NSTimeInterval)duration; // (Available from version 3.1.2)
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
enable | BOOL | Yes | Valid values: YES: enables the persistent cache feature NO: disables the persistent cache feature |
duration | NSTimeInterval | No | This parameter is only valid when the persistent cache feature is enabled. In this case, when the SDK loads records from the local persistent cache to the memory cache after startup, the SDK clears records whose expiration time has exceeded this Unit: seconds. Default value: 0. The default value indicates that expired records are cleared by default. |
Enable automatic resolution after network changes
When the device network changes (such as switching from a Wi-Fi network to a cellular network, or from a China Mobile network to a China Unicom network), if the HTTPDNS SDK continues to return the previously cached resolution IP address, cross-network requests may occur, affecting request performance and success rate. Therefore, the SDK internally listens for network change events and intelligently determines whether to clear the global resolution cache.
This operation is used to specify whether to automatically refresh the resolution results of all domain names after the SDK clears the global resolution cache when the network environment changes. If you enable this feature, the SDK ensures that the business network requests can immediately obtain new results after the network is switched, reducing the time consumed by domain name resolution and improving request performance.
Enabling this feature may slightly increase the number of resolutions. This switch is turned off by default.
Operation definition
- (void)setPreResolveAfterNetworkChanged:(BOOL)enable;
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
enable | BOOL | Yes | Valid values: YES: enables automatic resolution after network changes NO: disables automatic resolution after network changes |