This topic describes the basic configuration operations of HTTPDNS SDK for iOS.
Initialization
You can use this API to create a global HTTPDNS service instance. This instance uses the singleton design pattern and persists throughout the app's lifecycle after initialization. You do not need to create the instance again. After you create the instance for the first time, you can call the [HttpDnsService sharedInstance] API to retrieve the service instance whenever you need it.
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.
API 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 use the following APIs to retrieve the service instance whenever you need to configure HTTPDNS or resolve a domain name.
If you initialize multiple `HttpDnsService` instances with different account IDs, calling `sharedInstance` returns only the first instance that was successfully initialized. In this scenario, you must specify the account ID to retrieve a specific instance and avoid ambiguity.
Interface Definition
+ (instancetype)sharedInstance;
+ (nullable instancetype)getInstanceByAccountId:(NSInteger)accountID; // (Available from version 3.3.0)
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
accountId | int | Yes | The AccountId assigned by the system. After you activate HTTPDNS, you can get the AccountId for your Alibaba Cloud account in the console. |
Return description
Parameter | Description |
HttpDnsService * | If the initialization API has not been called for the specified accountId, this API returns nil. |
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 use the underlying CFNetwork and are not restricted by App Transport Security (ATS).
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.
Interface 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 or asynchronous API, the SDK initiates a resolution request to retrieve a new resolution from the server. This process takes some time. The synchronous API blocks the thread until a new resolution result is obtained. The asynchronous API calls back
completionHandleronly after a new resolution result is obtained.
The SDK provides a setting to allow the reuse of expired IP addresses. If you set this option to YES, the API can immediately return the expired IP address in the preceding two situations, even if the cached IP address has expired. This reduces the processing time of the DNS phase and improves the performance of network requests. At the same time, after the SDK detects that the IP address has expired and returns it, the SDK immediately starts an asynchronous thread to resolve the domain name and retrieve a new resolution result.
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, this is not allowed.
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 versions 2.x.x and earlier, this API is defined as
- (void)setExpiredIPEnabled:(BOOL)enable.
API 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 (Allow) NO: The action is not permitted. |
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 prevent the app from reusing a cache that has been expired for a long time after startup (for example, if the app was last started a month ago), this API provides the discardRecordsHasExpiredFor:(NSTimeInterval)duration parameter from version 3.1.2. This parameter determines whether to discard resolution results that have been expired for longer than the specified duration when the app loads the cache from the persistent layer to memory after startup. We recommend that you set this value to one 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 versions 2.x.x and earlier, this API 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: Enabled NO: disables the persistent cache feature |
duration | NSTimeInterval | No | This parameter is valid only when the persistent cache 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.
Interface Definition
- (void)setPreResolveAfterNetworkChanged:(BOOL)enable;
Class
HttpDnsService
Parameters
Parameter | Type | Required | Description |
enable | BOOL | Yes | Valid values: Enabled NO: disables automatic resolution after network changes |