Integrasikan SDK HTTPDNS dalam aplikasi Unity - HTTPDNS

Topik ini menjelaskan cara mengintegrasikan dan menggunakan HTTPDNS dalam aplikasi Unity.

Unity adalah platform untuk membuat dan mengoperasikan konten interaktif 3D real-time. Platform ini membantu kreator dalam pengembangan game, seni, arsitektur, desain otomotif, dan film mewujudkan ide mereka menjadi kenyataan. Unity menyediakan solusi perangkat lunak lengkap untuk membuat, mengoperasikan, dan memonetisasi konten interaktif 2D dan 3D real-time di berbagai perangkat, termasuk ponsel, tablet, PC, konsol game, serta perangkat augmented reality (AR) dan virtual reality (VR).

Seiring meningkatnya penggunaan Unity untuk mengembangkan berbagai jenis aplikasi seluler, kami kini menyediakan plugin HTTPDNS khusus untuk Unity. Plugin ini memungkinkan developer Unity mengintegrasikan fitur HTTPDNS dengan pendekatan yang sudah dikenal.

Bagian berikut memberikan petunjuk dan praktik terbaik untuk menggunakan plugin tersebut.

1. Mulai Cepat

1.1 Aktifkan layanan

Untuk informasi lebih lanjut tentang cara mengaktifkan HTTPDNS, lihat Mulai Cepat.

1.2 Dapatkan konfigurasi

Ambil AccountId, SecretKey, dan AESSecretKey Anda dari halaman konfigurasi Development di Konsol EMAS. Informasi ini diperlukan untuk menginisialisasi software development kit (SDK). Untuk informasi lebih lanjut, lihat Konfigurasi Development.

1.3 Integrasikan plugin ke dalam proyek Anda

Plugin ini disediakan dalam bentuk source code dan dipublikasikan di GitHub. Anda dapat mengintegrasikan plugin ini dengan menyalinnya ke proyek Unity Anda.

1.3.1 Impor paket Unity

Unduh direktori httpdns_unity_demo.
Salin seluruh direktori Assets/Plugins ke proyek Unity Anda.
Salin direktori Assets/Editor (opsional, digunakan untuk membuat UI uji coba) ke proyek Anda.

Struktur proyek Anda seharusnya tampak seperti berikut:

YourUnityProject/
├── Assets/
│   ├── Plugins/
│   │   ├── HttpDnsHelper.cs           # File antarmuka utama
│   │   ├── AndroidHttpDnsHelper.cs     # Implementasi platform Android
│   │   ├── iOSHttpDnsHelper.cs        # Implementasi platform iOS  
│   │   ├── CHttpDnsHelper.cs          # Implementasi platform SDK C
│   │   ├── Android/                   # Pustaka JAR Android
│   │   ├── iOS/                       # File Bridge iOS
│   │   └── C/                         # SDK C
│   └── Editor/                        # Pembuat UI pengujian
├── ProjectSettings/
└── ...

Penting

Plugin ini menggunakan file seperti baseProjectTemplate, mainTemplate, proguard-user, dan settingsTemplate. Jika bagian lain dari proyek Anda juga perlu menyesuaikan file-file ini, pastikan untuk menggabungkan perubahannya.

1.3.2 Verifikasi versi native SDK

Plugin ini mengintegrasikan native HTTPDNS SDK untuk platform yang sesuai. Versi saat ini adalah:

Android: com.aliyun.ams:alicloud-android-httpdns:2.6.5
iOS: AlicloudHTTPDNS:3.2.1
C: alibabacloud-httpdns-c-sdk:2.2.5

2. Instalasi dan konfigurasi

2.1 Tambahkan dependensi Unity

Lakukan konfigurasi berikut dalam proyek Unity Anda:

# Pengaturan proyek Unity
Player Settings:
  - Android: 
      Minimum API Level: 19+
      Internet Permission: Enabled
  - iOS:
      Deployment Target: 12.0+
      Internet Capability: Enabled
  - C:
      Platforms: Windows/macOS
      Architectures: x64/arm64
      Scripting Backend: Mono atau IL2CPP

Plugin ini menggunakan dependensi source code lokal. Setelah Anda menambahkan plugin ke proyek, Anda harus mengonfigurasinya untuk platform target.

2.2 Perbarui versi native SDK

Untuk memperbarui versi SDK HTTPDNS native, lakukan langkah-langkah berikut:

2.2.1 Perbarui versi SDK Android

Android SDK dikelola melalui dependensi Maven. Ubah nomor versi di bagian dependencies pada file Assets/Plugins/Android/mainTemplate.gradle:

dependencies {
    // Dependensi lainnya...
    implementation 'com.aliyun.ams:alicloud-android-httpdns:2.6.5' // Ubah ke versi yang diperlukan
}

Perhatikan bahwa operasi API untuk platform Android, iOS, dan C mungkin berbeda. Untuk informasi lebih lanjut, lihat dokumentasi resmi masing-masing platform.

Setelah Anda mengaktifkan template Gradle kustom (Custom Main/Base Gradle Template, Custom Proguard), Unity Build secara otomatis menarik versi yang sesuai dari repositori.

Untuk daftar versi yang tersedia, lihat Catatan rilis SDK Android.

2.2.2 Perbarui versi SDK iOS

Edit versi dependensi CocoaPods di prosesor pasca-build:

// Perbarui versi di HttpDnsIOSPostProcessor.cs
podfileContent += "  pod 'AlicloudHTTPDNS', '~> 3.2.1'\n";

// Perbarui ke versi yang dibutuhkan
podfileContent += "  pod 'AlicloudHTTPDNS', '~> new_version_number'\n";

Untuk daftar versi yang tersedia, lihat Catatan rilis SDK iOS.

2.2.3 Perbarui versi SDK C

Lakukan langkah-langkah berikut:

Unduh source code C SDK yang telah diperbarui.
Kompilasi source code tersebut di mesin lokal Anda untuk menghasilkan file library native.
Letakkan file library yang dihasilkan di direktori plugin proyek Unity Anda. Misalnya, letakkan file .dll untuk Windows atau file .dylib untuk macOS di direktori Assets/Plugins/C/x86_64/.
Kembali ke Unity dan rebuild proyek agar perubahan berlaku.

Untuk informasi lebih lanjut dan detail versi, lihat Catatan rilis SDK C.

2.2.4 Membangun ulang Proyek

Setelah memperbarui versi, Anda perlu merebuild proyek.

Android:

# Di Unity Editor
File -> Build Settings -> Android -> Build

iOS:

# Setelah membangun di Unity Editor, cd [direktori build iOS]
pod install --repo-update
open Unity-iPhone.xcworkspace

C (Windows/macOS):

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

3. Konfigurasi dan penggunaan

3.1 Inisialisasi

Setelah aplikasi Anda dimulai, Anda harus menginisialisasi plugin sebelum dapat memanggil operasi HTTPDNS. Inisialisasi mencakup konfigurasi AccountId, SecretKey, dan sakelar fitur lainnya. Kode berikut memberikan contoh:

using UnityEngine;

public class HttpDnsManager : MonoBehaviour 
{
    void Start()
    {
        // Inisialisasi HTTPDNS - Mode inisialisasi bertahap
        HttpDnsHelper.init("YOUR_ACCOUNT_ID", "YOUR_SECRET_KEY");
        
        // Atur opsi fitur
        HttpDnsHelper.setHttpsRequestEnabled(true);
        HttpDnsHelper.debug(true);
        HttpDnsHelper.setTimeout(3000);
        
        // Konfigurasi fitur lanjutan
        HttpDnsHelper.setPersistentCacheIPEnabled(true, 3600); // Aktifkan cache persisten selama 1 jam
        HttpDnsHelper.setReuseExpiredIPEnabled(true);          // Izinkan penggunaan ulang alamat IP yang kedaluwarsa
        HttpDnsHelper.setPreResolveAfterNetworkChanged(true);  // Aktifkan preresolusi otomatis saat transisi jaringan
        
        // Bangun instans layanan
        bool success = HttpDnsHelper.build();
        if (success) 
        {
            Debug.Log("HTTPDNS berhasil diinisialisasi");
            
            // Preresolve nama domain yang sering digunakan
            var hosts = new List<string> { "www.aliyun.com", "ecs.console.alibabacloud.com" };
            HttpDnsHelper.setPreResolveHosts(hosts, "auto");
        }
        else 
        {
            Debug.LogError("Inisialisasi HTTPDNS gagal");
        }
    }
}

Penting

Jika Anda mengatur parameter setHttpsRequestEnabled ke true, biaya Anda akan meningkat. Untuk informasi lebih lanjut, lihat Penagihan Produk.
Jika Anda memiliki persyaratan keamanan tinggi untuk informasi nama domain atau parameter SDNS, Anda dapat mengatur parameter aesSecretKey untuk mengaktifkan enkripsi konten pada permintaan resolusi. Penggunaan enkripsi konten akan meningkatkan biaya Anda. Untuk informasi lebih lanjut, lihat Penagihan Produk.

3.1.1 Konfigurasi log

Saat pengembangan aplikasi, Anda dapat mengaktifkan logging untuk HTTPDNS dengan memanggil metode kontrol output log. Kode berikut memberikan contoh:

HttpDnsHelper.debug(true);
Debug.Log("Output log diaktifkan");

3.1.2 Pencatatan SessionId

Saat aplikasi berjalan, Anda dapat memanggil metode getSessionId untuk mendapatkan sessionId dan mencatatnya di sistem pengumpulan data aplikasi Anda. SessionId mengidentifikasi sesi aplikasi tertentu. Anda dapat menggunakannya untuk mengkueri log resolusi untuk sesi tertentu selama troubleshooting online. Kode berikut memberikan contoh:

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

3.2 Resolusi nama domain

3.2.1 Preresolusi

Jika Anda perlu meresolusi nama domain sebelumnya, panggil metode pra-resolusi. Contoh kodenya sebagai berikut:

var hosts = new List<string> { "www.aliyun.com", "www.example.com" };
HttpDnsHelper.setPreResolveHosts(hosts, "both");
Debug.Log("Preresolusi berhasil diatur");

Setelah metode ini dipanggil, plugin akan memulai resolusi nama domain dan menyimpan hasilnya di cache memori untuk digunakan langsung pada permintaan berikutnya.

3.2.2 Resolusi nama domain

Saat Anda perlu meresolusi nama domain, Anda dapat memanggil metode resolusi nama domain untuk mendapatkan alamat IP. Kode berikut memberikan contoh:

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

Catatan: resolveHostSyncNonBlocking adalah metode resolusi sinkron non-blocking yang mungkin mengembalikan null atau tidak ada hasil. Kami menyarankan Anda menggunakan fitur ini bersama preresolusi. Jika tidak ada hasil resolusi yang dikembalikan, kembalikan ke DNS sistem untuk permintaan tersebut.

4. Praktik terbaik Unity

4.1 Cara kerja

Contoh ini menunjukkan solusi lengkap untuk mengintegrasikan HTTPDNS di Unity:

Antarmuka lintas-platform terpadu: Gunakan HttpDnsHelper untuk menyediakan API terpadu.
Implementasi spesifik platform: Sediakan implementasi dasar yang berbeda untuk SDK Android, iOS, dan C.
Penggantian DNS otomatis: Secara otomatis mengganti nama domain dengan alamat IP yang telah diresolusi sebelum permintaan jaringan.
Pengaturan header Host: Pastikan Server Name Indication (SNI) diatur dengan benar untuk koneksi HTTPS/SSL.

4.2 Integrasi permintaan jaringan

Saat Anda menggunakan modul jaringan berbeda untuk mengirim permintaan, Anda perlu mengonfigurasi header permintaan dan melakukan operasi terkait lainnya. Bagian-bagian berikut memberikan contoh untuk HttpClient, HttpWebRequest, dan UnityWebRequest.

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;
            
            // Resolusi nama domain menggunakan 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))
                {
                    // Penting: Atur header Host untuk memastikan kebenaran SSL/SNI
                    requestMessage.Headers.Host = hostname;
                    
                    var response = await httpClient.SendAsync(requestMessage);
                    string content = await response.Content.ReadAsStringAsync();
                    
                    Debug.Log($"Permintaan berhasil: {response.StatusCode}");
                }
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"Permintaan gagal: {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;
            
            // Resolusi nama domain menggunakan 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";
                // Penting: Atur header Host untuk memastikan kebenaran SSL/SNI
                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($"Permintaan berhasil: {response.StatusCode}");
                }
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"Permintaan gagal: {e.Message}");
        }
    }
}

4.2.3 UnityWebRequest (Tidak disarankan)

Penting

UnityWebRequest tidak dapat mengonfigurasi SNI dengan benar. Jika server bergantung pada SNI untuk mengembalikan sertifikat nama domain tertentu, autentikasi SSL akan gagal. Oleh karena itu, kami menyarankan Anda menggunakan dua metode permintaan jaringan pertama untuk menangani nama domain tersebut.

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;
        
        // Resolusi nama domain menggunakan 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))
            {
                // Penting: Atur header Host
                request.SetRequestHeader("Host", hostname);
                
                yield return request.SendWebRequest();
                
                if (request.result == UnityWebRequest.Result.Success)
                {
                    Debug.Log($"Permintaan berhasil: {request.responseCode}");
                }
                else
                {
                    Debug.LogError($"Permintaan gagal: {request.error}");
                }
            }
        }
    }
}

4.3 Gunakan UI pengujian

Proyek ini menyediakan dua pembuat UI pengujian:

UI Uji Coba Dasar: Buat dari menu HttpDNS/Create DNS Test UI.
UI Uji Coba Lanjutan: Buat dari menu HttpDNS/Create Advanced Test UI.

UI uji coba mencakup demo fitur lengkap untuk membantu Anda memverifikasi integrasi dengan cepat.

5. Referensi API

5.1 Metode inisialisasi

init

Menginisialisasi layanan HTTPDNS.

// Inisialisasi dasar
HttpDnsHelper.init(string accountId, string secretKey);

// Inisialisasi lengkap
HttpDnsHelper.init(string accountId, string secretKey, string aesSecretKey);

Parameter:

accountId: ID akun HTTPDNS (Wajib).
secretKey: Pasangan Kunci Akses (Opsional, digunakan untuk autentikasi).
aesSecretKey: Kunci enkripsi AES (Opsional, digunakan untuk enkripsi).

Penting

Jika Anda memiliki persyaratan keamanan tinggi untuk informasi nama domain atau parameter SDNS, Anda dapat mengatur parameter aesSecretKey untuk mengaktifkan enkripsi konten pada permintaan resolusi. Penggunaan enkripsi konten akan meningkatkan biaya Anda. Untuk informasi lebih lanjut, lihat Penagihan Produk.

build

Membangun instans layanan HTTPDNS. Panggil metode ini setelah mengatur semua konfigurasi.

bool success = HttpDnsHelper.build();

Nilai kembalian:

true: Instans berhasil dibangun.
false: Instans gagal dibangun.

5.2 Metode konfigurasi

debug

Mengontrol apakah akan mencetak log debug.

HttpDnsHelper.debug(bool enable);

setHttpsRequestEnabled

Mengatur apakah akan menggunakan HTTPS untuk kueri DNS.

HttpDnsHelper.setHttpsRequestEnabled(bool enable);

Penting

Jika Anda mengatur parameter setHttpsRequestEnabled ke true, biaya Anda akan meningkat. Untuk informasi lebih lanjut, lihat Penagihan Produk.

setTimeout

Mengatur periode timeout untuk kueri DNS.

HttpDnsHelper.setTimeout(int timeoutMs);

setPersistentCacheIPEnabled

Mengatur apakah akan mengaktifkan caching persisten.

HttpDnsHelper.setPersistentCacheIPEnabled(bool enable, int cacheTTL);

Parameter:

enable: Menentukan apakah akan mengaktifkan fitur tersebut.
cacheTTL: Masa hidup cache (TTL) dalam detik.

setReuseExpiredIPEnabled

Mengatur apakah akan mengizinkan penggunaan ulang alamat IP yang kedaluwarsa.

HttpDnsHelper.setReuseExpiredIPEnabled(bool enable);

setPreResolveAfterNetworkChanged

Mengatur apakah akan memperbarui otomatis nama domain yang telah dipreresolusi saat jaringan berubah.

HttpDnsHelper.setPreResolveAfterNetworkChanged(bool enable);

5.3 Metode resolusi

getIpsByHostAsync

Meresolusi nama domain secara asinkron.

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

Mengembalikan: Daftar alamat IP. Jika resolusi gagal, mengembalikan null atau daftar kosong.

getIpsByHost

Meresolusi nama domain secara sinkron.

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

resolveHostSyncNonBlocking

Menjalankan resolusi sinkron non-blocking dan mengembalikan informasi detail.

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

Parameter:

hostname: Nama domain yang akan diresolusi.
ipType: Jenis alamat IP ("auto", "ipv4", "ipv6", atau "both").

Objek yang dikembalikan berisi:

IPv4: Daftar alamat IPv4.
IPv6: Daftar alamat IPv6.
TTL: TTL cache.
Extra: Informasi tambahan.

5.4 Metode preresolusi

setPreResolveHosts

Mengatur daftar nama domain untuk dipreresolusi.

// Nama domain tunggal
HttpDnsHelper.setPreResolveHosts(string hostname);

// Beberapa nama domain
HttpDnsHelper.setPreResolveHosts(List<string> hostnames, string ipType);

5.5 Manajemen cache

clearCache

Menghapus cache untuk nama domain tertentu.

HttpDnsHelper.clearCache();

cleanAllHostCache

Menghapus cache untuk semua nama domain.

HttpDnsHelper.cleanAllHostCache();

5.6 Metode pembantu

getSessionId

Mengambil ID sesi saat ini.

string sessionId = HttpDnsHelper.getSessionId();

6. FAQ

6.1 Masalah build Android

Masalah: Gradle tidak dapat menyelesaikan dependensi com.aliyun.ams:alicloud-android-httpdns atau build gagal.

Solusi:

Aktifkan template Gradle kustom (Player Settings -> Publishing Settings -> Custom Main/Base Gradle Template).
Periksa file Assets/Plugins/Android/mainTemplate.gradle:
- Verifikasi bahwa bagian repositories dikonfigurasi dengan mirror repositori remote Alibaba Cloud.
- Verifikasi bahwa bagian dependencies berisi implementation 'com.aliyun.ams:alicloud-android-httpdns:version_number'.

6.2 Masalah build iOS

Masalah: Dependensi CocoaPods tidak ditemukan setelah build iOS.

Solusi: Pastikan untuk menjalankan perintah pod install seperti yang dijelaskan dalam instruksi build. Kemudian, buka proyek menggunakan file .xcworkspace.

6.3 Masalah platform SDK C

Masalah: Platform C SDK kehilangan dependensi library native.

Solusi:

Windows: Pastikan VCPKG terinstal dan variabel lingkungan telah diatur.
macOS: Pastikan library dependensi Homebrew telah terinstal.
Periksa apakah post-build processor telah menyalin file library dengan benar.
Salin secara manual pustaka dependensi ke direktori build.

6.4 Masalah permintaan jaringan

Masalah: Permintaan HTTPS gagal dengan error sertifikat.

Solusi: Pastikan untuk mengatur header Host yang benar. Gunakan nama domain asli sebagai SNI, bukan alamat IP.