Get a service instance
You can obtain an HTTPDNS service instance. The HTTPDNS software development kit (SDK) supports multiple instances. Different instances are returned for different account IDs.
Each instance that is initialized with an account ID uses the singleton design pattern. After initialization, the instance persists throughout the app lifecycle and is not created again.
getService
Interface definition
HttpDnsService getService(Context applicationContext, String accountID);
Class
HttpDns
Introduced in version
1.2.3
Deprecated in version
2.6.3
Replacement interfaces
HttpDnsService getService(String accountID)
InitConfig.Builder setContext(Context context)
Parameters
Parameter | Type | Required | Description |
applicationContext | Context | Yes | Your Android app Context. |
accountID | String | Yes | The account ID assigned by the system. After you activate HTTPDNS, you can obtain your account ID in the EMAS console. Go to [Project Name] > Platform Services > HTTPDNS > Developer Configuration. |
getService
Interface definition
HttpDnsService getService(Context applicationContext, String accountID, String secretKey);
Class
HttpDns
Introduced in version
1.3.2
Deprecated in version
2.6.3
Replacement interfaces
HttpDnsService getService(String accountID)
InitConfig.Builder setContext(Context context)
InitConfig.Builder setSecretKey(String secretKey)
Parameters
Parameter | Type | Required | Description |
applicationContext | Context | Yes | Your Android app Context. |
accountID | String | Yes | The account ID assigned by the system. After you activate HTTPDNS, you can obtain your account ID in the EMAS console. Go to [Project Name] > Platform Services > HTTPDNS > Developer Configuration. |
secretKey | String | Yes | The secret key for authentication. |
Use HTTPS requests
By default, the HTTPDNS SDK sends domain name resolution requests over HTTP. To send these requests over HTTPS, you must configure the SDK to use the HTTPS protocol.
Using HTTPS requests provides higher security. Note that the billing for HTTP and HTTPS requests is different. For more information about billing, see Billing.
setHTTPSRequestEnabled
Interface definition
void setHTTPSRequestEnabled(boolean enableHttps)
Class
HttpDnsService
Introduced in version
1.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setEnableHttps(boolean enableHttps)
Parameters
Parameter | Type | Required | Description |
enableHttps | boolean | Yes | Specifies whether to use the HTTPS protocol for domain name resolution.
|
Allow the use of expired IP addresses
The SDK follows the DNS protocol and caches domain name resolution results based on their Time-to-Live (TTL) values. This improves the efficiency of retrieving IP addresses when the app initiates network requests. When the cache expires and the app calls a resolution interface to retrieve an IP address, different scenarios can occur:
If the app calls a synchronous non-blocking interface, the interface returns an empty result. This happens because the cache is expired and the SDK cannot immediately retrieve a new resolution result from the server. To avoid blocking the thread, the caller must handle the fallback to Local DNS resolution.
If the app calls a synchronous or asynchronous interface, the SDK sends a resolution request to retrieve a new result from the server. This process takes time. The synchronous interface blocks the thread until it retrieves the new result. The asynchronous interface invokes the callback only after it retrieves the new result.
The SDK provides an option to reuse expired IP addresses. If you set this option to true, the interface can immediately return the expired IP address in both scenarios. This reduces the processing time for domain name resolution and improves network request performance. After returning the expired IP address, the SDK also starts an asynchronous thread to resolve the domain name and retrieve a new result.
This option has minimal side effects. This is especially true when the DNS records for the resolved domain name do not change frequently, such as for primary site domains or static gateway domains. If a DNS record does change, enabling this option only affects the first request after the cache for that domain name expires. This is because the SDK always starts a resolution update immediately when it is called and finds an expired IP address.
This feature is enabled by default.
When set to true, the SDK returns the expired IP address in real time and also performs an asynchronous update to retrieve the latest IP information.
setExpiredIPEnabled
Interface definition
void setExpiredIPEnabled(boolean enableExpiredIp)
Class
HttpDnsService
Introduced in version
1.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)
Parameters
Parameter | Type | Required | Description |
enableExpiredIp | boolean | Yes | Specifies whether to allow returning IP addresses that have exceeded their TTL.
|
Enable local cache
The persistent cache feature optimizes the time spent on domain name resolution after startup. This improves the loading speed of the first screen.
When enabled, HTTPDNS saves the last resolution result to a local persistence layer. After the app restarts, the first resolution for each domain name prioritizes retrieving the cached result from the persistence layer for the fastest resolution. Because of this, the first IP address used might be an expired one, meaning its cached TTL has passed. However, in most cases, this IP address can still be used. This is especially true for domain names with stable DNS records.
setCachedIPEnabled
Interface definitions
void setCachedIPEnabled(boolean enableCacheIp)
void setCachedIPEnabled(boolean enableCacheIp, boolean cleanLocalCache)
Class
HttpDnsService
Introduced in version
1.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setEnableCacheIp(boolean enableCacheIp)
Parameters
Parameter | Type | Required | Description |
enableCacheIp | boolean | Yes | Controls whether to enable the local cache.
|
cleanLocalCache | boolean | No | Specifies whether to clear the local cache after reading it. This parameter takes effect when the persistent cache is enabled.
The default value is false. |
Enable auto-resolution on network changes
When the device's network changes, such as switching from a Wi-Fi network to a cellular network, the HTTPDNS SDK might continue to return previously cached IP addresses. This can cause cross-network requests, which affects request performance and success rates. To prevent this, the SDK listens for network change events and intelligently decides whether to clear the global resolution cache.
This interface sets whether the SDK automatically refreshes the resolution results for all domain names after it clears the global resolution cache due to a network change. If enabled, business network requests can retrieve new results immediately after a network switch. This reduces the time for domain name resolution and improves request performance.
Enabling this feature may slightly increase the number of resolution requests. This feature is disabled by default.
A switch between Wi-Fi, a cellular network, and no network is considered a network transition.
A switch between 4G and 3G is not considered a network transition.
A SIM card switch is not handled separately.
setPreResolveAfterNetworkChanged
Interface definition
void setPreResolveAfterNetworkChanged(boolean enable)
Class
HttpDnsService
Introduced in version
1.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setPreResolveAfterNetworkChanged(boolean enable)
Parameters
Parameter | Type | Required | Description |
enable | boolean | Yes | Specifies whether to re-resolve all domain names in the cache when the network changes.
|
Timeout configuration
You can set the timeout period for domain name resolution. The default is 2000 ms.
setTimeout
Interface definition
InitConfig.Builder setTimeout(int timeoutInterval)
Class
InitConfig.Builder
Introduced in version
2.0.2
Deprecated in version
2.4.0
Replacement interface
InitConfig.Builder setTimeoutMillis(int timeoutInterval)
Parameters
Parameter | Type | Required | Description |
timeoutInterval | int | Yes | Sets the timeout period for domain name resolution, in milliseconds. The default is 2000 ms. The maximum is 5000 ms. |
Code example
InitConfig.Builder()
.setTimeout(2 * 1000)new InitConfig.Builder()
.setTimeout(2 * 1000);setTimeoutInterval
Interface definition
void setTimeoutInterval(int timeoutInterval)
Class
HttpDnsService
Introduced in version
1.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setTimeoutMillis(int timeoutInterval)
Parameters
Parameter | Type | Required | Description |
timeoutInterval | int | Yes | Sets the timeout period for domain name resolution, in milliseconds. The default timeout is 2000 ms. The maximum is 5000 ms. |
Set the region node
If your app needs to use HTTPDNS outside China, you can set the SDK's startup service node to improve resolution efficiency. After you set the node, the SDK uses it for domain name resolution and for subsequent updates to the scheduling node list.
setRegion
You can set the region node during initialization.
Interface definition
InitConfig.Builder setRegion(String region)
Class
InitConfig.Builder
Introduced in version
1.3.2
Deprecated in version
2.4.2
Replacement interface
InitConfig.Builder setRegion(Region region)
Parameters
Parameter | Type | Required | Description |
region | String | Yes | The region node. Set a region outside China for service area selection. Currently, only `hk` (China (Hong Kong) node), `sg` (Singapore node), `de` (Germany node), and `us` (US node) are supported. If you specify a region, the local service node is returned. If you do not specify a region, the service node in the Chinese mainland is used. |
Code example
InitConfig.Builder()
.setRegion("hk");new InitConfig.Builder()
.setRegion("hk");Set the blacklist for HTTPDNS domain names
To prevent specific domain names from being resolved by HTTPDNS, you can filter them out using this interface. Filtered domain names return an empty resolution result. You must fall back to Local DNS for resolution.
setDegradationFilter
Interface definition
InitConfig.Builder setDegradationFilter(DegradationFilter filter)
Class
InitConfig.Builder
Introduced in version
2.4.0
Deprecated in version
2.4.0
Replacement interface
InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)
Parameters
Parameter | Type | Required | Description |
filter | Yes | Configures the blacklist policy. |
setIPRankingList
Interface definition
void setIPRankingList(List<IPRankingBean> ipRankingList)
Class
HttpDnsService
Introduced in version
2.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setIPRankingList(List<IPRankingBean> ipRankingList)
Parameters
Parameter | Type | Required | Description |
ipRankingList | List<IPRankingBean> | Yes | Sets the IP ranking list. After you set this interface, if a corresponding domain name is resolved, the SDK probes the returned IP addresses. It then dynamically sorts the list to ensure that the first IP address has better availability. |
setIPProbeList
Interface definition
void setIPProbeList(List<IPRankingBean> ipProbeList)
Class
HttpDnsService
Introduced in version
1.3.2
Deprecated in version
2.3.2
Removed in version
2.3.2
Replacement interface
InitConfig.Builder setIPRankingList(List<IPRankingBean> ipRankingList)
Parameters
Parameter | Type | Required | Description |
ipProbeList | List<IPProbeItem> | Yes | Sets the IP ranking list. After you set this interface, if a corresponding domain name is resolved, the SDK probes the returned IP addresses. It then dynamically sorts the list to ensure that the first IP address has better availability. |
Set global parameters for custom resolution
These global parameters do not affect the extra parameter settings of the custom resolution interface. They are merged with the extra parameters of the custom resolution interface.
setSdnsGlobalParams
Interface definition
void setSdnsGlobalParams(Map<String, String> params)
Class
HttpDnsService
Introduced in version
1.3.2
Removed in version
2.4.0
Replacement interface
InitConfig.Builder setSdnsGlobalParams(Map params)
Parameters
Parameter | Type | Required | Description |
params | Map<String, String> | Yes | Global parameters for custom resolution. Each custom resolution request carries these global parameters. |