HTTPDNS Android SDK configuration API reference - HTTPDNS

Configure the HTTPDNS Android SDK for initialization, security, caching, network parameters, and performance optimization.

Get a service instance

Returns an HTTPDNS service instance. The SDK supports multiple instances, each mapped to a unique Account ID.

Each Account ID maps to a singleton instance that persists for the application lifecycle.

`getService`

Interface definition

HttpDnsService getService(String accountID)

Version introduced

2.6.3

Class

HttpDns

Parameters

Parameter	Type	Required	Description
accountID	String	Yes	The Account ID for your service. You can find it on the EMAS console > [Project Name] > Platform Services > HTTPDNS > Development Configuration page.

Code examples

Kotlin

val httpdns = HttpDns.getService(accountID)

Java

HttpDnsService httpdns = HttpDns.getService(accountID);

Set context

Sets the application Context for HTTPDNS resolution.

`setContext`

Interface definition

InitConfig.Builder setContext(Context context)

Version introduced

2.6.3

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
context	Context	Yes	The current application's `applicationContext`.

Code example

Kotlin

InitConfig.Builder()
    .setContext(context)

Java

new InitConfig.Builder()
    .setContext(context);

Set the signing key

Sets the signing key used to sign HTTPDNS resolution requests.

The server uses this key to authenticate and verify the integrity of resolution requests.

`setSecretKey`

Interface definition

InitConfig.Builder setSecretKey(String secretKey)

Note

This interface does not affect billing.
To prevent information leakage from decompilation, enable obfuscation and harden your application before publishing.

Version introduced

2.6.3

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
secretKey	String	Yes	The signing key.

Code example

Kotlin

InitConfig.Builder()
    .setSecretKey(secretKey)

Java

new InitConfig.Builder()
    .setSecretKey(secretKey);

Set the encryption key

Sets the AES encryption key for HTTPDNS resolution.

The SDK uses AES to encrypt request parameters and responses, which improves security but affects product billing.

`setAesSecretKey`

Interface definition

InitConfig.Builder setAesSecretKey(String aesSecretKey)

Note

To prevent information leaks from decompilation, enable obfuscation and application hardening before publishing your app.

Version introduced

2.6.3

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
aesSecretKey	String	Yes	The encryption key.

Code example

Kotlin

InitConfig.Builder()
    .setAesSecretKey(aesSecretKey)

Java

new InitConfig.Builder()
    .setAesSecretKey(aesSecretKey);

Enable HTTPS

By default, the SDK sends resolution requests over HTTP. Enable HTTPS for transport-layer security.

HTTP and HTTPS resolution requests are billed at different rates (Product Billing).

`setEnableHttps`

Interface definition

InitConfig.Builder setEnableHttps(boolean enableHttps)

Note

HTTPS secures the transport layer but does not prevent packet inspection of parameters. AES encryption secures the HTTPDNS service layer, hiding plaintext content from packet capture. You can enable either or both.

Version introduced

2.2.2

Class

InitConfig.Builder

Parameters

Parameter

Type

Required

Description

enableHttps

boolean

Yes

Specifies whether to use HTTPS for domain name resolution.

true: Enable HTTPS resolution.
false: Disable HTTPS resolution.

Code example

Kotlin

InitConfig.Builder()
    .setEnableHttps(true)

Java

new InitConfig.Builder()
    .setEnableHttps(true);

Reuse expired IP addresses

The SDK caches resolution results based on TTL. When the cache expires and the application requests an IP address:

Synchronous non-blocking interface: returns null to avoid blocking. The caller must fall back to local DNS.
Synchronous or asynchronous interface: the SDK sends a new resolution request. The synchronous interface blocks until a result arrives; the asynchronous interface triggers a callback when the result is ready.

When set to true, the SDK immediately returns the expired IP in both scenarios and starts an asynchronous refresh. This reduces resolution latency and improves performance.

This has minimal side effects for domains with stable resolution records. If resolution changes, only the first request after cache expiry uses the stale IP, because the SDK immediately requests a resolution update upon detecting expiry.

This feature is enabled by default.

Important

When set to true, the SDK returns the expired IP address while performing an asynchronous update to retrieve the latest IP address.

`setEnableExpiredIp`

Interface definition

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

Version introduced

2.2.2

Class

InitConfig.Builder

Parameters

Parameter

Type

Required

Description

enableExpiredIp

boolean

Yes

Specifies whether to return expired IP addresses.

true: Allow returning expired IP addresses.
false: Do not return expired IP addresses.

Code example

Kotlin

InitConfig.Builder()
    .setEnableExpiredIp(true)

Java

new InitConfig.Builder()
    .setEnableExpiredIp(true);

Enable persistent cache

Persistent caching reduces post-startup resolution time, improving first-screen load speed.

When enabled, the SDK persists the last resolution result. After restart, initial resolutions retrieve cached results from the persistent layer for the fastest response. The first IP may have an expired TTL, but remains usable for domains with stable records.

Use expiredThresholdMillis to discard cached entries expired beyond expiredThresholdMillis when loading from persistent storage. Recommended value: 1 day.

This feature is disabled by default.

`setEnableCacheIp`

Interface definition

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp, long expiredThresholdMillis)

Note

When you enable the local cache, you can configure it to purge cached results that have been expired for longer than a specified duration.

If your business server's IP address changes frequently, use this feature with caution to avoid business disruptions.
The persistent cache only affects the initial domain name resolution. Subsequent resolutions query the HTTPDNS server and update the local cache.
When this feature is enabled, each network resolution updates the local cache. After the app restarts, the local cache is loaded into the memory cache.

Version introduced

2.4.3

Class

InitConfig.Builder

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.

expiredThresholdMillis

long

Yes

When the SDK loads records from the local cache into the memory cache, it discards records that have been expired for longer than expiredThresholdMillis.

The unit is milliseconds. The default is 0, which means any record whose TTL has expired is discarded. The maximum value is 1 year.

Code examples

Kotlin

InitConfig.Builder()
    .setEnableCacheIp(true, DateUtils.YEAR_IN_MILLIS)

Java

new InitConfig.Builder()
    .setEnableCacheIp(true, DateUtils.YEAR_IN_MILLIS);

`setEnableCacheIp`

Interface definition

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp)

Note

Calling this method enables the local cache and configures it to discard all expired records when loading from the persistent cache into the memory cache.

Version introduced

2.2.2

Class

InitConfig.Builder

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.

Code examples

Kotlin

InitConfig.Builder()
    .setEnableCacheIp(true)

Java

new InitConfig.Builder()
    .setEnableCacheIp(true);

Auto-resolve on network change

When the device switches networks (e.g., Wi-Fi to cellular), cached IP addresses may cause cross-network requests, degrading performance. The SDK monitors network changes and clears the global resolution cache as needed.

Enable this option to automatically re-resolve all cached domain names after a network change, reducing resolution time for subsequent requests.

This may slightly increase resolution requests. Disabled by default.

Important

A switch between Wi-Fi, a cellular network, and a disconnected state is considered a network change.
A switch between 4G and 3G is not considered a network change.
The SDK does not have special handling for SIM card switches.

`setPreResolveAfterNetworkChanged`

Interface definition

InitConfig.Builder setPreResolveAfterNetworkChanged(boolean enable)

Version introduced

2.4.0

Class

InitConfig.Builder

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 all domain names in the cache when the network changes.
If set to false or not set, the SDK only clears the global resolution cache when the network changes. The SDK re-resolves a domain name only when it is next accessed.

Code example

Kotlin

InitConfig.Builder()
    .setPreResolveAfterNetworkChanged(true)

Java

new InitConfig.Builder()
    .setPreResolveAfterNetworkChanged(true);

Set resolution timeout

Sets the timeout for resolution requests. Default: 2000 ms.

`setTimeoutMillis`

Interface definition

InitConfig.Builder setTimeoutMillis(int timeoutInterval)

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
timeoutInterval	int	Yes	The timeout for resolution requests, in milliseconds. Default: 2000 ms. Maximum: 5000 ms.

Code example

Kotlin

new InitConfig.Builder()
    .setTimeoutMillis(2 * 1000);

Correct signing time

Enables the SDK to correct device time discrepancies using each network request. Without this, the SDK uses the device's local time.

Important

Use this if the device's time may be inaccurate.
The correction applies only to the current application lifecycle. Call this method again after each restart. You can call this method repeatedly.
Provide a reliable time service. Fetch the current timestamp from your service and pass it to this method. The SDK calculates the time offset and applies a correction.

`setAuthCurrentTime`

Interface definition

void setAuthCurrentTime(long time)

Version introduced

1.3.2

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
time	long	Yes	The current Unix timestamp, in seconds.

Code Example

Kotlin

val httpdns = HttpDns.getService(accountID)
httpdns?.setAuthCurrentTime(System.currentTimeMillis() / 1000L)

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
httpdns.setAuthCurrentTime(System.currentTimeMillis() / 1000L);

Set the service region

If your application uses HTTPDNS outside the Chinese mainland, set the SDK's service region to improve resolution performance. The SDK then uses service nodes in that region to resolve domain names and update the scheduling node list.

`setRegion`

Sets the service region during initialization.

Interface definition

InitConfig.Builder setRegion(Region region)

Version introduced

2.4.2

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
region	Region	Yes	The service region. Specify a region outside the Chinese mainland to use service nodes in that region.

`setRegion`

Updates the service region.

Interface definition

void setRegion(Region region)

Version introduced

2.4.2

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
region	Region	Yes	The service region. Specify a region outside the Chinese mainland to use service nodes in that region.

`setRegion`

Updates the service region.

Interface definition

void setRegion(String region)

Version introduced

1.3.2

Class

HttpDnsService

Parameters

Parameter

Type

Required

Description

region

String

Yes

The service region. Specify a region outside the Chinese mainland to use service nodes in that region. Supported values include hk (China (Hong Kong)), sg (Singapore), de (Germany), and us (US).

Important

To optimize performance for applications outside the Chinese mainland, set an appropriate service region.

Customize TTL

By default, the server TTL determines when a cached result expires. Use this interface to override the TTL.

`configCacheTtlChanger`

Interface definition

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

Version introduced

2.3.0

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
changer	CacheTtlChanger	Yes	The handler for customizing the TTL.

Code examples

Kotlin

InitConfig.Builder().configCacheTtlChanger { host, requestIpType, ttl ->
    if (TextUtils.equals(host, "www.aliyun.com")) {
        // Use www.aliyun.com as an example.
        ttl * 10
    } else ttl
}

Java

new InitConfig.Builder().configCacheTtlChanger(new CacheTtlChanger() {
    @Override
    public int changeCacheTtl(String host, RequestIpType requestIpType, int ttl) {
        // Use www.aliyun.com as an example.
        if (TextUtils.equals(host, "www.aliyun.com")) {
            return ttl * 10;
        }

        return ttl;
    }
});

Configure the HTTPDNS blacklist

Filters specific domain names from HTTPDNS resolution. The SDK returns an empty result for filtered domains, requiring the application to fall back to local DNS.

`setNotUseHttpDnsFilter`

Interface definition

InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
filter	NotUseHttpDnsFilter	Yes	A filter that defines the blacklist policy.

Code examples

Kotlin

InitConfig.Builder().setNotUseHttpDnsFilter { hostName ->
    TextUtils.equals(
        hostName,
        "www.aliyun.com"
    )
}

Java

new InitConfig.Builder().setNotUseHttpDnsFilter(new NotUseHttpDnsFilter() {
    @Override
    public boolean notUseHttpDns(String hostName) {
        return TextUtils.equals(hostName, "www.aliyun.com");
    }
});

Enable IP ranking

Configures domain names for IP probing. The SDK runs speed tests on resolved IP addresses and sorts results by availability.

Note

Only IPv4 addresses are supported for IP probing.

`setIPRankingList`

Interface definition

InitConfig.Builder setIPRankingList(List<IPRankingBean> ipRankingList)

Version introduced

2.3.2

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
ipRankingList	List<IPRankingBean>	Yes	A list of domain names and their corresponding ports for which to perform IP probing.

Code examples

Kotlin

val list = ArrayList<IPRankingBean>()
list.add(IPRankingBean("www.aliyun.com", 8080))
InitConfig.Builder().setIPRankingList(list)

Java

ArrayList<IPRankingBean> list = new ArrayList<IPRankingBean>();
list.add(new IPRankingBean("www.aliyun.com", 8080));
new InitConfig.Builder().setIPRankingList(list);

Set global parameters for custom resolution

Global parameters are merged into every custom resolution request without affecting per-request extra parameters.

`setSdnsGlobalParams`

Interface definition

InitConfig.Builder setSdnsGlobalParams(Map<String, String> params)

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Parameter	Type	Required	Description
params	Map<String, String>	Yes	Global parameters that are included in every custom resolution request.

Code example

Kotlin

val params: MutableMap<String, String> = HashMap()
params["level"] = "1"
InitConfig.Builder()
    .setSdnsGlobalParams(params)

Java

Map<String, String> params = new HashMap<>();
params.put("level", "1");
new InitConfig.Builder()
        .setSdnsGlobalParams(params);

Disable network stack auto-detection

Disables network stack auto-detection. The SDK treats the network type as both. Typically not required.

`disableNetworkDetector`

Interface definition

InitConfig.Builder disableNetworkDetector()

Version introduced

2.6.8

Class

InitConfig.Builder

Parameters

None

Code example

Kotlin

InitConfig.Builder()
    .disableNetworkDetector()

Java

new InitConfig.Builder()
    .disableNetworkDetector();