HTTPDNS:Configuration interfaces

Configuration interfaces are the core interfaces of the HTTPDNS Android SDK. They handle SDK initialization, parameter configuration, and runtime adjustments. These interfaces allow you to customize the SDK's behavior, such as security settings, cache policies, network parameters, and performance optimizations, to meet your application's specific needs.

Get a service instance

You can 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 uses the singleton design pattern. After initialization, the instance persists throughout the application lifecycle and is not created again.

getService

Interface definition

HttpDnsService getService(String accountID)

Version introduced

2.6.3

Class

HttpDns

Parameters

Code examples

val httpdns = HttpDns.getService(accountID)

HttpDnsService httpdns = HttpDns.getService(accountID);

Set the context

Sets the application environment context used for HTTPDNS resolution.

setContext

Interface definition

InitConfig.Builder setContext(Context context)

Version introduced

2.6.3

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setContext(context)

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

Set the signing key for resolution interfaces

Sets the key used to sign requests for HTTPDNS resolution.

After you set the key, the SDK signs requests sent to the server. This allows the HTTPDNS server to perform identity authentication and tamper-proofing on resolution requests, which improves the security of interactions between the SDK and the server.

setSecretKey

Interface definition

InitConfig.Builder setSecretKey(String secretKey)

Version introduced

2.6.3

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setSecretKey(secretKey)

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

Set the encryption key for resolution interfaces

Sets the key used for encryption during HTTPDNS resolution.

After you set the encryption key, the SDK uses the Advanced Encryption Standard (AES) algorithm to encrypt request parameters and response results. Encryption provides higher security, but the billing logic is different. For more information about billing, see Product Billing.

setAesSecretKey

Interface definition

InitConfig.Builder setAesSecretKey(String aesSecretKey)

Version introduced

2.6.3

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setAesSecretKey(aesSecretKey)

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

Use HTTPS requests

By default, the HTTPDNS SDK uses the HTTP protocol to send resolution requests. To use the HTTPS protocol instead, you must configure the SDK to use HTTPS for domain name resolution.

Using HTTPS requests provides higher security, but the billing for HTTP and HTTPS requests is different. For more information about billing, see Product Billing.

setEnableHttps

Interface definition

InitConfig.Builder setEnableHttps(boolean enableHttps)

Version introduced

2.2.2

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setEnableHttps(true)

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

Allow use of expired IP addresses

The SDK follows the DNS protocol and caches domain name resolution results based on their Time to Live (TTL). This improves the efficiency of obtaining an IP address when your application initiates a network request. When the cache expires, different scenarios occur if the application calls a resolution interface to obtain an IP address:

1. If the application calls a synchronous non-blocking interface when the cache is expired, the SDK cannot immediately retrieve a new resolution result from the server. To avoid blocking the thread, the interface returns an empty result. The caller must then fall back to Local DNS resolution.

2. If the application calls a synchronous or asynchronous interface, the SDK sends a resolution request to retrieve a new result from the server. This process takes some time. The synchronous interface blocks the thread until a new result is obtained, while the asynchronous interface invokes a callback only after a new result is obtained.

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 of the preceding scenarios, even if the cached IP address has expired. This reduces the processing time for DNS resolution and improves network request performance. At the same time, when the SDK finds that the IP address is expired, it immediately starts an asynchronous thread to resolve the domain name and retrieve a new result.

This option has a minimal side effect, especially when the resolution configuration of the domain name does not change frequently, such as for primary site or static gateway domain names. If the domain name resolution does change, enabling this option affects only the first request after the domain name's cache expires. This is because when the SDK is called and finds an expired IP address, it always immediately initiates an update for that domain name's resolution.

This feature is enabled by default.

setEnableExpiredIp

Interface definition

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

Version introduced

2.2.2

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setEnableExpiredIp(true)

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

Enable local cache

The persistence cache feature is designed to optimize the time spent on domain name resolution after startup, which improves the loading speed of the first screen.

When enabled, HTTPDNS saves the last resolution result to the local persistence layer. After the application restarts, the first resolution for each domain name preferentially retrieves the cached result from the persistence layer. This achieves the fastest resolution efficiency. Because of this, the first IP address used might be an expired IP address, meaning its cached TTL has expired. However, in most cases, this IP address can still be used, especially for domain names with stable DNS records.

To avoid reusing a cache that has been expired for too long after the application starts (for example, if the application was last started a month ago), this interface provides the expiredThresholdMillis parameter. When the application starts and loads the cache from the persistence layer into memory, this parameter determines whether to discard resolution results that have been expired for longer than the expiredThresholdMillis duration. We recommend setting this value to one day.

This feature is disabled by default.

setEnableCacheIp

Interface definition

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp, long expiredThresholdMillis)

Version introduced

2.4.3

Class

InitConfig.Builder

Parameters

Code examples

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

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

setEnableCacheIp

Interface definition

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp)

Version introduced

2.2.2

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setEnableCacheIp(true)

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

Enable auto-resolution on network change

When the device's network changes (for example, switching from a Wi-Fi network to a cellular network, or from one mobile carrier to another), the IP addresses previously cached by the HTTPDNS SDK may cause cross-network business requests. This can affect request performance and success rates. Therefore, the SDK internally listens for network change events and intelligently decides whether to purge the global resolution cache.

This interface is used to configure whether the SDK automatically refreshes the resolution results for all domain names after the network environment changes and the global resolution cache is purged. If enabled, business network requests can immediately retrieve new results after a network switch. This reduces the time spent on domain name resolution and improves request performance.

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

setPreResolveAfterNetworkChanged

Interface definition

InitConfig.Builder setPreResolveAfterNetworkChanged(boolean enable)

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Code examples

InitConfig.Builder()
    .setPreResolveAfterNetworkChanged(true)

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

Timeout configuration

Sets the timeout period for domain name resolution. The default is 2000 ms.

setTimeoutMillis

Interface definition

InitConfig.Builder setTimeoutMillis(int timeoutInterval)

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Code examples

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

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

Correct the app signing time

After you perform this operation, if a time drift occurs, the device's time is corrected with each network request. If you do not perform this operation, the device's time is used.

setAuthCurrentTime

Interface definition

void setAuthCurrentTime(long time)

Version introduced

1.3.2

Class

HttpDnsService

Parameters

Code examples

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

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

Set the region node

If your application needs to use HTTPDNS in an environment outside China, you can set the startup service node for this SDK to improve resolution efficiency. After you set the node, the SDK uses that node for domain name resolution and for subsequent updates to 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

setRegion

Updates the service region.

Interface definition

void setRegion(Region region)

Version introduced

2.4.2

Class

HttpDnsService

Parameters

setRegion

Updates the service region.

Interface definition

void setRegion(String region)

Version introduced

1.3.2

Class

HttpDnsService

Parameters

Customize the TTL of resolution results

By default, the TTL provided by the server is used to determine whether each resolution result has expired. To modify the TTL of a resolution result, you can configure it using the following interface.

configCacheTtlChanger

Interface definition

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

Version introduced

2.3.0

Class

InitConfig.Builder

Parameter definition

Code examples

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

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;
    }
});

Set the domain name blacklist for HTTPDNS

To prevent specific domain names from being resolved using HTTPDNS, you can filter them out using this interface. Filtered domain names will return an empty resolution result. You must then fall back to local DNS for domain name resolution.

setNotUseHttpDnsFilter

Interface definition

InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Code examples

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

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

Enable IP probing

Sets the IP probing list. After you set this interface, if a corresponding domain name is resolved, the SDK performs IP speed tests on the returned IP addresses. It then dynamically sorts the returned list to ensure that the first IP address has better availability.

setIPRankingList

Interface definition

InitConfig.Builder setIPRankingList(List<IPRankingBean> ipRankingList)

Version introduced

2.3.2

Class

InitConfig.Builder

Parameters

Code examples

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

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

These global parameters are merged with the extra parameters of the custom resolution interface. This merge operation does not affect the parameter settings of the custom resolution interface.

setSdnsGlobalParams

Interface definition

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

Version introduced

2.4.0

Class

InitConfig.Builder

Parameters

Code examples

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

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