HTTPDNS:Unity integration guide

1.3.1 Import the Unity package

1. Download the httpdns_unity_demo folder from the project.

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

3. Copy the Assets/Editor folder to your project. This step is optional and is used to create a test UI.

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 version

The plugin integrates the native HTTPDNS SDK for each platform. 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

On Android, dependencies are managed by Maven. In the Assets/Plugins/Android/mainTemplate.gradle file, modify the version number in the dependencies block:

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

Note: The API capabilities differ across the Android, iOS, and C platforms. For more information, see the official API documentation for each platform.

After you enable the custom Gradle templates, such as Custom Main Gradle Template, Custom Base Gradle Template, and Custom Proguard, Unity automatically pulls the corresponding version from the repository during the build.

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 version you need
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:

• Obtain the updated C SDK source code.

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

• Place the generated library file into the plugin folder of your Unity project, such as the .dll file in Assets/Plugins/C/x86_64/ or the .dylib file for macOS.

• Return to Unity and rebuild the project to apply the changes.

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

2.2.4 Rebuild the project

After you update the version, you must rebuild the project.

Android:

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

iOS:

# After building in the Unity Editor, cd to the [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 call the log output control method to enable logging. The following code provides an example:

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

3.1.2 Session ID recording

While the application is running, you can call the method to retrieve the session ID and record it in your application's data collection system. The session ID identifies a specific run of the application. You can use the session ID to query resolution logs for that run when you troubleshoot issues online. 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("Pre-resolution 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);

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

Parameters:

• accountId: Your HTTPDNS account ID. This parameter is required.

• secretKey: The AccessKey pair. This parameter is optional and is used for authentication.

• aesSecretKey: The AES encryption key. This parameter is optional and is used for encryption.

build

Builds the HTTPDNS service instance. You must call this method after you complete all configurations.

bool success = HttpDnsHelper.build();

Return value:

• true: The instance is successfully built.

• false: The instance failed to build.

debug

Enables or disables the printing of debug logs.

HttpDnsHelper.debug(bool enable);

setHttpsRequestEnabled

Specifies whether to use an HTTPS request for a DNS query.

HttpDnsHelper.setHttpsRequestEnabled(bool enable);

setTimeout

Sets the timeout period for a DNS query.

HttpDnsHelper.setTimeout(int timeoutMs);

setPersistentCacheIPEnabled

Specifies whether to enable persistent cache.

HttpDnsHelper.setPersistentCacheIPEnabled(bool enable, int cacheTTL);

Parameters

• enable: Specifies whether to enable the feature.

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

setReuseExpiredIPEnabled

Specifies whether to allow the reuse of expired IP addresses.

HttpDnsHelper.setReuseExpiredIPEnabled(bool enable);

setPreResolveAfterNetworkChanged

Specifies whether to automatically refresh pre-resolved domain names after a network transition.

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, this method returns null or an empty list.

getIpsByHost

Synchronously resolves a domain name.

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

resolveHostSyncNonBlocking

Performs 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. Valid values are "auto", "ipv4", "ipv6", and "both".

The returned object contains:

• IPv4: A list of IPv4 addresses.

• IPv6: A list of IPv6 addresses.

• TTL: The cache time to live.

• Extra: Extra information.

setPreResolveHosts

Sets the 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.

HttpDnsHelper.clearCache();

cleanAllHostCache

Clears the cache for all domain names.

HttpDnsHelper.cleanAllHostCache();

getSessionId

Retrieves the current session ID.

string sessionId = HttpDnsHelper.getSessionId();