All Products
Search

This Product

    HTTPDNS:Client integration overview

    Document Center

    HTTPDNS:Client integration overview

    Last Updated:Jan 21, 2026

    This topic describes the key principles and steps for integrating a client with HTTPDNS.

    1. Introduction

    HTTPDNS is a client-side DNS solution that replaces traditional local DNS. It helps prevent issues such as domain hijacking, resolution latency, high failure rates, and inaccurate scheduling. HTTPDNS provides mobile terminals with more stable, faster, and secure resolution. The integration process involves the following main steps:

    1. Activate the service

    2. Add domain names to the resolution list

    3. Obtain development configurations

    4. Obtain the resolved IP address

    5. Apply the resolution result to the network library

    6. Verify successful integration

    Note

    If you use custom parsing to implement service scheduling, you also need to configure a custom parsing policy. For more information, see Custom parsing.

    The first three steps are operations performed in the console. If you have not completed these steps, see Product workflow. The last three steps are part of the client integration process. This topic focuses on the client integration process. Before you proceed, it is helpful to understand how DNS resolvers work.

    2. DNS resolvers

    A DNS resolver is a network service component that receives domain name queries and returns the corresponding IP addresses. When an app client initiates a network request, it typically first calls its integrated network library, such as NSURLSession, OkHttp, or libcurl. Before establishing a connection, the network library uses a DNS resolver to resolve the target domain name to an IP address to establish a TCP/UDP connection. DNS resolvers can be divided into two types:

    • System DNS resolver: A domain name resolution component, such as a library or system service, that is provided and maintained by the operating system. Applications trigger the system resolver to perform domain name resolution through standard API calls, such as POSIX getaddrinfo(), Windows DnsQuery(), or Apple Network.framework. The system resolver initiates a query based on the current network configuration, such as the local hosts file, DNS cache, and network adapter settings. It ultimately requests the resolution result from a recursive DNS server. These recursive DNS servers are typically ISP DNS servers that are automatically assigned by DHCP, or public DNS servers that are manually configured by the user, such as 8.8.8.8 or 1.1.X.X.

    • Custom DNS resolver: A custom DNS resolver uses resolution logic implemented by an application or a third-party library that partially or completely bypasses the system resolver. The application can directly bypass the recursive DNS provided by the carrier and instead access a specified resolution service, such as an HTTPDNS server, to obtain an authoritative IP address. One common method is for an application to override the network library's DNS interface, such as OkHttp's Dns interface or libcurl's resolve mechanism, to inject the resolution result directly at the application layer. Another method is to intercept request traffic through a proxy and perform a DNS hook and domain-to-IP mapping at the proxy layer. This process enables customized domain name resolution and connection scheduling.

    Integrating a client with HTTPDNS is the process of implementing a custom DNS resolver based on the HTTPDNS service. The following figure shows an example of an HTTP request. It illustrates how a client uses a custom DNS resolver or the DNS-over-HTTPS (DoH) protocol to apply the resolution result from the HTTPDNS server to its network library. This ensures that the network request uses the optimal IP address to establish a connection.

    image

    3. Integration process

    After you activate the service and add domain names to the resolution list in the console, you can implement a custom DNS resolver using HTTPDNS. This process involves three core steps:

    • Obtain the resolved IP address: Access the HTTPDNS server to obtain the IP address for a domain name.

    • Apply the resolution result: Inject the obtained IP address into the network request.

    • Verify successful integration: Use logs or packet captures to confirm that the previous two steps were successful.

    3.1 Get the resolved IP address

    You can obtain domain name resolution results from the HTTPDNS server in one of three ways: using a software development kit (SDK), the HTTP API, or DNS-over-HTTPS (DoH).

    In most scenarios, using an SDK is the recommended approach.

    3.2 Apply the resolution result

    After you obtain the resolved IP address, you must apply it during the DNS resolution step of your network requests. The method you use depends on whether your network library supports custom DNS resolution. If the network library provides a DNS hook or a domain name mapping interface, you can directly inject the resolution result. If not, you can use other methods, such as direct IP connection, protocol replacement, or a local proxy. This document lists adaptation solutions for common network libraries and frameworks.

    Note

    For adaptation solutions for other network libraries or frameworks, such as Socket.io, HttpClient, Glide, SwiftNIO, and Libcurl, contact Technical support.

    3.3 Verify successful integration

    After you integrate the client with HTTPDNS, you can verify that the previous two steps were successful in one of the following two ways:

    1. Log verification (Recommended)

      • Method: Use client-side instrumentation to log the list of resolved IP addresses that you obtained from the HTTPDNS API. Then, check whether business requests are initiated correctly.

      • Features: This method is simple, lightweight, and suitable for most scenarios.

    • Hijacking simulation:

      • Method: Set the DNS server for the mobile device's Wi-Fi network to an invalid address. Then, observe whether business requests are still initiated normally to determine if the HTTPDNS integration was successful.

      • Features: This method effectively blocks interference from the system DNS and provides more accurate results.

    4. Summary

    Integrating with HTTPDNS is the process of building a custom DNS resolver. This topic describes the three core steps: obtaining a resolved IP address, applying it to the network library, and verifying the integration. For more information, including API descriptions and important notes, see the user guide for your chosen integration method: