Configuration interfaces (Deprecated) - HTTPDNS - Alibaba Cloud Documentation Center

Get a service instance

Obtain an HTTPDNS service instance. The HTTPDNS SDK supports multiple instances, and different account IDs return different instances.

Each instance initialized with an account ID follows the singleton pattern. After initialization, it persists throughout the app lifecycle and is not recreated.

`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 use HTTPS instead, configure the SDK accordingly.

HTTPS requests provide higher security but are billed differently from HTTP requests. For more information, 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.

true: Enables HTTPS resolution.
false: Disables HTTPS resolution.

Allow the use of expired IP addresses

The SDK caches domain name resolution results based on their Time-to-Live (TTL) values to speed up IP address retrieval. When the cache expires and the app calls a resolution interface, 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.

If you enable expired IP reuse by setting this option to true, the interface immediately returns the expired IP address in both scenarios, reducing resolution time and improving network request performance. The SDK also starts an asynchronous thread to resolve the domain name and retrieve a new result.

This option has minimal side effects, especially for domain names with stable DNS records, such as primary site domains or static gateway domains. If a DNS record changes, only the first request after cache expiry is affected, because the SDK always starts a resolution update immediately when it finds an expired IP address.

This feature is enabled by default.

Important

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.

true: Allows returning expired IP addresses.
false: Does not return expired IP addresses.

Enable local cache

Persistent caching optimizes domain name resolution time after startup, improving first-screen loading speed.

When enabled, HTTPDNS saves the last resolution result locally. After the app restarts, the first resolution for each domain name retrieves the cached result for the fastest response. The first IP address used might have an expired TTL, but in most cases it remains usable, especially 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.

true: Enables the local cache.
false: Disables 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.

true: Clears the local cache after reading it.
false: Does not clear the local cache after reading it.

The default value is false.

Enable auto-resolution on network changes

When the device switches networks, such as from Wi-Fi to cellular, the HTTPDNS SDK might continue returning previously cached IP addresses. This can cause cross-network requests that affect performance and success rates. To prevent this, the SDK listens for network change events and clears the global resolution cache as needed.

This interface controls whether the SDK automatically refreshes resolution results for all domain names after clearing the cache due to a network change. When enabled, network requests retrieve new results immediately after a network switch, reducing resolution time and improving performance.

Enabling this feature may slightly increase the number of resolution requests. This feature is disabled by default.

Important

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.

If set to true, the SDK re-resolves and refreshes all domain names in the cache when the network changes.
If set to false or not set, the SDK only deletes the cache for all domain names when the network changes. The domain names are re-resolved only when they are next accessed.

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

Kotlin

InitConfig.Builder()
    .setTimeout(2 * 1000)

Java

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

To use HTTPDNS outside China, set the SDK's startup service node to improve resolution efficiency. The SDK uses this node for domain name resolution and for subsequent scheduling node list updates.

`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

Kotlin

InitConfig.Builder()
    .setRegion("hk");

Java

new InitConfig.Builder()
    .setRegion("hk");

Set the blacklist for HTTPDNS domain names

Use this interface to prevent specific domain names from being resolved by HTTPDNS. Filtered domain names return an empty resolution result, and you must fall back to Local DNS.

`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	Common data structure interfaces	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 are merged with the extra parameters of the custom resolution interface but do not override them.

`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.