HTTPDNS:Basic configurations

Context configuration

The SDK uses HarmonyOS APIs for data storage and requires a Context parameter. Set the Context parameter during initialization.

The following code provides an example:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'
        
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // ************* Start of initialization configuration *************
    httpdns.configService(ACCOUNT_ID, {
      // Configure the Harmony context.
      context: this.context,
    });
    // ************* End of initialization configuration *************
  }
  // Other code is omitted.
}

Use HTTPS requests

Specify whether the SDK uses HTTPS to send resolution requests. By default, the SDK uses HTTP.

HTTPS requests provide higher security but are billed differently than HTTP requests. For more information, see Product Billing.

The following code shows how to configure the SDK to use HTTPS:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to use HTTPS requests *************
      useHttps: true,
      // ************* End: Configure whether to use HTTPS requests *************
    });
  }
  // Other code is omitted.
}

Allow the use of expired IP addresses

The SDK caches resolution results based on their time-to-live (TTL) to improve the efficiency of IP address lookups. If the cache expires when the application requests an IP address, the following situations may occur:

1. If the application calls a synchronous non-blocking API operation, an empty result is returned. This happens because the cache is expired and the SDK cannot immediately retrieve a new result from the server. To avoid blocking the thread, fall back to resolution using Local DNS.

2. When an app calls an asynchronous API, the SDK requests a new resolution result from the server. Because this process takes time, a synchronous API call blocks the thread until the new result is returned.

The SDK can reuse expired IP addresses. If this option is set to YES, the API immediately returns a cached IP address even if it has expired, reducing DNS resolution time and improving network request performance. The SDK then starts an asynchronous thread to resolve the domain name and refresh the cache.

This option has minimal side effects, especially for domain names whose resolution rarely changes, such as primary sites or static gateways. If a domain name's resolution does change, only the first request after cache expiry is affected. The SDK starts a resolution update as soon as it detects an expired IP address.

The following code shows how to disallow the use of expired IP addresses:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to allow the use of expired IP addresses *************
      enableExpiredIp: false,
      // ************* End: Configure whether to allow the use of expired IP addresses *************
    })
  }
  // Other code is omitted.
}

Enable local caching

The enableDiskCache parameter controls whether resolution results are stored in the local cache. By default, this feature is disabled (false).

When enabled, resolution results are cached locally. On the next application startup, the SDK loads cached results from local storage, which speeds up initial resolution.

You can also use expiredThresholdMillis to set a cache expiration threshold. At startup, the SDK loads cached results into memory and discards any that have been expired longer than the specified duration. The default value is 0 ms.

The following code shows how to enable local caching:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to enable local caching *************
      enableDiskCache: true,
      expiredThresholdMillis: 3600000,
      // ************* End: Configure whether to enable local caching *************
    })
  }
  // Other code is omitted.
}

Enable automatic resolution on network changes

Configure whether the SDK automatically re-resolves previously resolved domain names when the network changes. By default, this feature is enabled (true).

Network changes can invalidate cached resolution results, so re-resolution is needed to obtain correct results.

The following code shows how to disable automatic resolution on network changes:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to enable automatic resolution on network changes *************
      reResolveCachedHostsAfterNetworkChanged: false,
      // ************* End: Configure whether to enable automatic resolution on network changes *************
    })
  }
  // Other code is omitted.
}

Timeout configuration

You can configure the timeout for domain name resolution requests. The default timeout is 2000 ms.

The following code shows the configuration:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure timeout duration *************
      timeoutInMs: 3000
      // ************* End: Configure timeout duration *************
    })
  }
  // Other code is omitted.
}

Resolution parameter encryption

Configure an encryption key for domain name resolution parameters. When enabled, the SDK encrypts the domain name, client IP address, custom business parameters, and resolution type before sending the request. The data is transmitted as ciphertext, which improves security. By default, encryption is disabled.

The following code shows the configuration:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'
const AES_SECRET_KEY = 'Replace this with the AES encryption key from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure interface encryption key *************
      aesSecretKey: AES_SECRET_KEY,
      // ************* End: Configure interface encryption key *************
    })
  }
  // Other code is omitted.
}