HTTPDNS:Unity integration guide

1.3.1 Import the Unity package

1. Download the httpdns_unity_demo directory.

2. Copy the entire Assets/Plugins directory to your Unity project.

3. Copy the Assets/Editor directory (optional, used to create a test UI) to your project.

Your project structure should look like this:

YourUnityProject/
├── Assets/
│   ├── Plugins/
│   │   ├── HttpDnsHelper.cs           # Main interface file
│   │   ├── AndroidHttpDnsHelper.cs     # Android platform implementation
│   │   ├── iOSHttpDnsHelper.cs        # iOS platform implementation  
│   │   ├── CHttpDnsHelper.cs          # C SDK platform implementation
│   │   ├── Android/                   # Android JAR library
│   │   ├── iOS/                       # iOS Bridge file
│   │   └── C/                         # C SDK
│   └── Editor/                        # Test UI creator
├── ProjectSettings/
└── ...

1.3.2 Verify the native SDK versions

The plugin integrates the native HTTPDNS SDKs for the corresponding platforms. The current versions are:

• Android: com.aliyun.ams:alicloud-android-httpdns:2.6.5

• iOS: AlicloudHTTPDNS:3.2.1

• C: alibabacloud-httpdns-c-sdk:2.2.5

2.2.1 Update the Android SDK version

The Android SDK is managed through Maven dependencies. Modify the version number in the dependencies section of Assets/Plugins/Android/mainTemplate.gradle:

dependencies {
    // Other dependencies...
    implementation 'com.aliyun.ams:alicloud-android-httpdns:2.6.5' // Change to the required version
}

Note that the API operations for Android, iOS, and C platforms may differ. For more information, see the official documentation for each platform.

After you enable custom Gradle templates (Custom Main/Base Gradle Template, Custom Proguard), Unity Build automatically pulls the corresponding version from the repository.

For available versions, see Android SDK release notes.

2.2.2 Update the iOS SDK version

Edit the CocoaPods dependency version in the post-build processor:

// Update the version in HttpDnsIOSPostProcessor.cs
podfileContent += "  pod 'AlicloudHTTPDNS', '~> 3.2.1'\n";

// Update to the required version
podfileContent += "  pod 'AlicloudHTTPDNS', '~> new_version_number'\n";

For available versions, see iOS SDK release notes.

2.2.3 Update the C SDK version

Perform the following steps:

• Download the updated C SDK source code.

• Compile the source code on your local machine to generate native library files.

• Place the generated library files in the plugin directory of your Unity project. For example, place the .dll file for Windows or the .dylib file for macOS in the Assets/Plugins/C/x86_64/ directory.

• Return to Unity and rebuild the project for the changes to take effect.

For more information and version details, see C SDK release notes.

2.2.4 Rebuild the project

After updating the version, you need to rebuild the project.

Android:

# In the Unity Editor
File -> Build Settings -> Android -> Build

iOS:

# After building in the Unity Editor, cd [iOS build directory]
pod install --repo-update
open Unity-iPhone.xcworkspace

C (Windows/macOS):

# In the Unity Editor
File -> Build Settings -> PC, Mac & Linux Standalone -> Build

3.1.1 Log configuration

During application development, you can enable logging for HTTPDNS by calling the log output control method. The following code provides an example:

HttpDnsHelper.debug(true);
Debug.Log("Log output is enabled");

3.1.2 SessionId recording

While the application is running, you can call the getSessionId method to obtain the sessionId and record it in your application's data collection system. The sessionId identifies a specific application session. You can use it to query resolution logs for a specific session during online troubleshooting. The following code provides an example:

string sessionId = HttpDnsHelper.getSessionId();
Debug.Log($"SessionId = {sessionId}");

3.2 Domain name resolution

var hosts = new List<string> { "www.aliyun.com", "www.example.com" };
HttpDnsHelper.setPreResolveHosts(hosts, "both");
Debug.Log("Preresolution is set successfully");

public void ResolveDomain(string hostname)
{
    // Synchronous non-blocking resolution
    var result = HttpDnsHelper.resolveHostSyncNonBlocking(hostname, "auto");
    if (result != null)
    {
        Debug.Log($"IPv4 addresses: {result.IPv4.Count}");
        Debug.Log($"IPv6 addresses: {result.IPv6.Count}");
        Debug.Log($"TTL: {result.TTL} seconds");
    }
}

4.2.1 HttpClient

using System;
using System.Net.Http;
using UnityEngine;

public class HttpDnsHttpClient : MonoBehaviour
{
    private static readonly HttpClient httpClient = new HttpClient();
    
    public async void MakeRequest(string url)
    {
        try
        {
            var uri = new Uri(url);
            string hostname = uri.Host;
            
            // Resolve the domain name using HTTPDNS
            var result = HttpDnsHelper.resolveHostSyncNonBlocking(hostname, "auto");
            if (result != null && result.IPv4 != null && result.IPv4.Count > 0)
            {
                string resolvedIP = result.IPv4[0];
                string newUrl = url.Replace(hostname, resolvedIP);
                
                using (var requestMessage = new HttpRequestMessage(HttpMethod.Get, newUrl))
                {
                    // Important: Set the Host header to ensure SSL/SNI correctness
                    requestMessage.Headers.Host = hostname;
                    
                    var response = await httpClient.SendAsync(requestMessage);
                    string content = await response.Content.ReadAsStringAsync();
                    
                    Debug.Log($"Request successful: {response.StatusCode}");
                }
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"Request failed: {e.Message}");
        }
    }
}

4.2.2 HttpWebRequest

using System;
using System.IO;
using System.Net;
using UnityEngine;

public class HttpDnsWebRequest : MonoBehaviour
{
    public void MakeRequest(string url)
    {
        try
        {
            var uri = new Uri(url);
            string hostname = uri.Host;
            
            // Resolve the domain name using HTTPDNS
            var result = HttpDnsHelper.resolveHostSyncNonBlocking(hostname, "auto");
            if (result != null && result.IPv4 != null && result.IPv4.Count > 0)
            {
                string resolvedIP = result.IPv4[0];
                string newUrl = url.Replace(hostname, resolvedIP);
                
                HttpWebRequest request = (HttpWebRequest)WebRequest.Create(newUrl);
                request.Method = "GET";
                // Important: Set the Host header to ensure SSL/SNI correctness
                request.Host = hostname;
                
                using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
                using (Stream stream = response.GetResponseStream())
                using (StreamReader reader = new StreamReader(stream))
                {
                    string content = reader.ReadToEnd();
                    Debug.Log($"Request successful: {response.StatusCode}");
                }
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"Request failed: {e.Message}");
        }
    }
}

4.2.3 UnityWebRequest (Not recommended)

using System;
using System.Collections;
using UnityEngine;
using UnityEngine.Networking;

public class HttpDnsUnityWebRequest : MonoBehaviour
{
    public IEnumerator MakeRequest(string url)
    {
        var uri = new Uri(url);
        string hostname = uri.Host;
        
        // Resolve the domain name using HTTPDNS
        var result = HttpDnsHelper.resolveHostSyncNonBlocking(hostname, "auto");
        if (result != null && result.IPv4 != null && result.IPv4.Count > 0)
        {
            string resolvedIP = result.IPv4[0];
            string newUrl = url.Replace(hostname, resolvedIP);
            
            using (UnityWebRequest request = UnityWebRequest.Get(newUrl))
            {
                // Important: Set the Host header
                request.SetRequestHeader("Host", hostname);
                
                yield return request.SendWebRequest();
                
                if (request.result == UnityWebRequest.Result.Success)
                {
                    Debug.Log($"Request successful: {request.responseCode}");
                }
                else
                {
                    Debug.LogError($"Request failed: {request.error}");
                }
            }
        }
    }
}

init

Initializes the HTTPDNS service.

// Basic initialization
HttpDnsHelper.init(string accountId, string secretKey);

// Complete initialization
HttpDnsHelper.init(string accountId, string secretKey, string aesSecretKey);

Parameters:

• accountId: The HTTPDNS account ID (Required).

• secretKey: The AccessKey pair (Optional, used for authentication).

• aesSecretKey: The AES encryption key (Optional, used for encryption).

build

Builds the HTTPDNS service instance. Call this method after setting all configurations.

bool success = HttpDnsHelper.build();

Return value:

• true: The instance is built successfully.

• false: The instance failed to be built.

debug

Controls whether to print debug logs.

HttpDnsHelper.debug(bool enable);

setHttpsRequestEnabled

Sets whether to use HTTPS for DNS queries.

HttpDnsHelper.setHttpsRequestEnabled(bool enable);

setTimeout

Sets the timeout period for DNS queries.

HttpDnsHelper.setTimeout(int timeoutMs);

setPersistentCacheIPEnabled

Sets whether to enable persistent caching.

HttpDnsHelper.setPersistentCacheIPEnabled(bool enable, int cacheTTL);

Parameters:

• enable: Specifies whether to enable the feature.

• cacheTTL: The cache time to live (TTL) in seconds.

setReuseExpiredIPEnabled

Sets whether to allow the reuse of expired IP addresses.

HttpDnsHelper.setReuseExpiredIPEnabled(bool enable);

setPreResolveAfterNetworkChanged

Sets whether to automatically refresh pre-resolved domain names when the network changes.

HttpDnsHelper.setPreResolveAfterNetworkChanged(bool enable);

getIpsByHostAsync

Asynchronously resolves a domain name.

List<string> ips = HttpDnsHelper.getIpsByHostAsync(string hostname);

Returns: A list of IP addresses. If the resolution fails, it returns null or an empty list.

getIpsByHost

Synchronously resolves a domain name.

List<string> ips = HttpDnsHelper.getIpsByHost(string hostname);

resolveHostSyncNonBlocking

Performs a synchronous, non-blocking resolution and returns detailed information.

HttpDnsResult result = HttpDnsHelper.resolveHostSyncNonBlocking(string hostname, string ipType);

Parameters:

• hostname: The domain name to resolve.

• ipType: The IP address type ("auto", "ipv4", "ipv6", or "both").

The returned object contains:

• IPv4: A list of IPv4 addresses.

• IPv6: A list of IPv6 addresses.

• TTL: The cache TTL.

• Extra: Extra information.

setPreResolveHosts

Sets a list of domain names to pre-resolve.

// Single domain name
HttpDnsHelper.setPreResolveHosts(string hostname);

// Multiple domain names
HttpDnsHelper.setPreResolveHosts(List<string> hostnames, string ipType);

clearCache

Clears the cache for a specified domain name.

HttpDnsHelper.clearCache();

cleanAllHostCache

Clears the cache for all domain names.

HttpDnsHelper.cleanAllHostCache();

getSessionId

Retrieves the current session ID.

string sessionId = HttpDnsHelper.getSessionId();