Konfigurasi Situs

Tujuan

Kelola konfigurasi lanjutan situs, termasuk URL terenkripsi, skrip, emulasi browser, proxy, pencatatan header request/response, kontrol halaman, dan perilaku akses.

Prasyarat

• Situs target sudah dibuat.
• Sebelum menerbitkan skrip, uji situs terlebih dahulu.

Langkah

1. Masuk ke "Manajemen Situs > Daftar Situs".
2. Temukan situs target lalu klik konfigurasi.
3. Aktifkan URL terenkripsi bila perlu agar frontend pengguna tidak menampilkan alamat situs asal secara langsung.
4. Konfigurasikan emulasi browser, proxy, header request, header response, kontrol halaman, dan skrip.
5. Simpan konfigurasi situs.
6. Gunakan akun uji untuk mengakses situs target dan verifikasi pembukaan, login, navigasi, data API, serta pemrosesan event SSE.
7. Untuk menyesuaikan perilaku berdasarkan kategori akun, kembali ke daftar situs dan buka "Konfigurasi Kategori Akun".

Referensi Konfigurasi

Élément	Utilité	Remarques
URL terenkripsi	Menyembunyikan alamat situs asal yang tampil di frontend pengguna	Tidak menggantikan autentikasi situs target
Emulasi browser	Menyesuaikan brand browser, model perangkat mobile, zona waktu, dan data identifikasi lain	Validasi ulang kompatibilitas situs target setelah perubahan
Pengaturan proxy	Mengatur akses langsung, proxy sistem, PAC, atau server proxy tetap untuk situs	Kesalahan proxy dapat membuat situs gagal dibuka atau login bermasalah
Header request	Mencatat header request tertentu agar dapat dibaca skrip halaman melalui api.header(name, true)	Hanya header yang dikonfigurasi dan benar-benar melewati browser jarak jauh yang dicatat
Header response	Mencatat header response tertentu agar dapat dibaca skrip halaman melalui api.header(name, false)	Nama header dikonversi menjadi huruf kecil saat dibaca
Skrip halaman	Memproses DOM, formulir, tombol, navigasi, dan peningkatan halaman	Batasi URL yang cocok untuk menghindari efek tidak diinginkan
Skrip SSE	Mengubah data stream Server-Sent Events	Cocok untuk skenario lanjutan; uji terlebih dahulu
Skrip intersepsi API normal	Mengubah body response API non-SSE	Skrip harus mengembalikan string body response baru
Kontrol halaman	Menyembunyikan atau menghapus elemen halaman berdasarkan URL dan selector	Selector dapat gagal setelah situs target berubah
Konfigurasi kategori akun	Mengatur logika login berbeda untuk kategori akun berbeda	Digunakan bersama akun browser situs

Konfigurasi Skrip

Area "Konfigurasi Skrip" pada halaman konfigurasi situs digunakan untuk menambahkan kumpulan aturan skrip bagi situs target. Setiap aturan dijalankan saat browser jarak jauh mengakses situs target, sesuai URL yang cocok dan tipe skripnya.

Champ	Type	Description
name	string	Nama skrip. Format yang disarankan adalah "situs-tujuan-versi", misalnya crm-login-v1.
url	string	URL pencocokan. Jika kosong biasanya dianggap *; di produksi sebaiknya ditulis sepresisi mungkin.
pageScript	boolean	Apakah ini skrip halaman. Jika aktif, skrip berjalan dalam konteks halaman dan dapat menggunakan window.api.
sseScript	boolean	Apakah ini skrip intersepsi SSE. Hanya tampil dan berlaku saat pageScript = false.
selector	string	Kondisi eksekusi skrip halaman. Jika diisi, skrip hanya berjalan saat halaman cocok dengan selector CSS atau XPath ini.
content	string	Konten JavaScript skrip. Parameter dan nilai kembali berbeda menurut tipe skrip.

Skrip Halaman

Saat pageScript = true, skrip berjalan sebagai skrip halaman. Ini cocok untuk DOM, formulir, klik tombol, navigasi, overlay, baca/tulis data pengguna, dan peningkatan halaman.

Perilaku runtime:

1. Browser jarak jauh mengakses halaman target.
2. Sistem menginisialisasi window.api di halaman dan iframe yang dapat diakses.
3. Jika selector dikonfigurasi, skrip hanya berjalan saat selector cocok dengan elemen.
4. Skrip dapat langsung menggunakan api.config, api.user, api.dom, api.utils, dan api.header(). Lihat lampiran API Skrip untuk API lengkap.

Contoh: menunggu elemen muncul, menyembunyikan area iklan, dan membaca konfigurasi produk.

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.main-panel'),
  10000,
  200
);

const envName = api.config.envName || 'default';
console.log('current env:', envName);

const banner = api.dom.querySelector(document, '.ad-banner');
if (banner) {
  banner.style.display = 'none';
}

Skrip SSE

Saat pageScript = false dan sseScript = true, skrip digunakan untuk mencegat data Server-Sent Events. Sistem membungkus EventSource dan fetch di halaman, lalu memproses stream dengan URL yang cocok dan content type text/event-stream.

Bentuk eksekusi:

async (data) => {
  // Konten skrip yang diisi di content
}

Paramètre	Type	Description
data	string	Pesan SSE saat ini atau teks chunk streaming.

Nilai kembali harus berupa teks SSE baru. Jika tidak mengembalikan string, halaman dapat menerima data yang tidak normal.

Contoh: mengganti teks dalam data SSE.

return data.replace('old text', 'new text');

Skrip Intersepsi API Normal

Saat pageScript = false dan sseScript = false, skrip digunakan untuk mencegat response API normal. Sistem mencocokkan URL API, membaca body response, lalu menyerahkan body ke skrip untuk diubah.

Bentuk eksekusi:

async (data, api, url) => {
  // Konten skrip yang diisi di content
}

Paramètre	Type	Description
data	string	Body response asli.
api	object	API skrip. Lihat lampiran API Skrip.
url	string	URL API yang sedang dicegat.

Nilai kembali harus berupa string body response baru.

Contoh: mengubah response API JSON.

const obj = JSON.parse(data);
obj.debug = true;
obj.fromScript = url.includes('/api/');
return JSON.stringify(obj);

Aturan Pencocokan URL

Field url mendukung aturan berikut:

Écriture	Description	Exemple
*	Mencocokkan semua URL	*
regex:<ekspresi>	Mencocokkan URL dengan regular expression	regex:/api/chat
exact:<URL lengkap>	Mencocokkan URL lengkap secara tepat	exact:https://example.com/api/user
script:<ekspresi>	Menjalankan ekspresi dengan URL saat ini sebagai variabel url	script:url.includes('/api/')
String biasa	Memeriksa apakah URL target diawali string ini	https://example.com/api/

Untuk skrip produksi, gunakan path yang presisi atau prefix stabil untuk mengurangi risiko memengaruhi halaman dan API yang tidak terkait.

Header Request dan Response

Header request dan response dalam konfigurasi situs digunakan untuk mencatat header tertentu. Skrip halaman dapat membacanya melalui api.header(). Lihat lampiran API Skrip untuk parameter lengkap.

Langkah penggunaan:

1. Tambahkan nama header request yang perlu dicatat di "Header Request", misalnya authorization, cookie.
2. Tambahkan nama header response yang perlu dicatat di "Header Response", misalnya content-type, set-cookie.
3. Simpan konfigurasi, lalu akses situs target melalui browser jarak jauh.
4. Baca header di skrip halaman.

const authorization = await api.header('authorization', true);
const contentType = await api.header('content-type', false);

Catatan:

• Nama header dikonversi menjadi huruf kecil saat dibaca.
• Hanya header yang dikonfigurasi dan benar-benar melewati browser jarak jauh yang dapat dibaca.
• Header response mungkin berupa array string; skrip harus menangani array dan nilai kosong.

Sintaks Selector

Selector skrip dan selector kontrol halaman mendukung CSS dan XPath.

Écriture	Description
.button.primary	Selector CSS.
xpath://div[@id="app"]	Selector XPath.
.dialog:p	Mengembalikan elemen induk dari elemen yang cocok.
.dialog:p2	Mengembalikan elemen induk dua level di atas elemen yang cocok.
.header:bottom	Pada metode batas overlay, gunakan batas bawah elemen target.
.sidebar:right	Pada metode batas overlay, gunakan batas kanan elemen target.

Proses Perubahan Konfigurasi

1. Catat konfigurasi saat ini dan konten skrip.
2. Ubah pada situs uji atau akun uji.
3. Verifikasi pembukaan, login, navigasi, logout, response API, dan event SSE.
4. Periksa apakah aturan kontrol halaman menyembunyikan atau menghapus elemen yang benar.
5. Sinkronkan konfigurasi ke situs produksi.
6. Minta pengguna terkait masuk ulang ke situs dan memverifikasi.

Verifikasi

• Kartu situs di frontend pengguna tampil sesuai konfigurasi.
• Saat URL terenkripsi diaktifkan, antarmuka pengguna tidak menampilkan URL situs asal secara langsung.
• Skrip kustom berlaku sesuai aturan pencocokan saat browser jarak jauh mengakses situs target.
• Skrip halaman dapat membaca konfigurasi, menemukan elemen, dan memproses perilaku halaman dengan benar.
• Skrip SSE hanya mengubah stream event target dan tidak memengaruhi API normal.
• Skrip intersepsi API normal mengembalikan body response yang valid.
• Setelah situs target berubah, skrip dan selector tetap cocok dengan benar.

FAQ

• Uji skrip di situs uji sebelum digunakan di produksi.
• URL terenkripsi hanya memengaruhi tampilan frontend dan jalur akses; ini tidak melewati kebijakan keamanan situs target.
• Skrip halaman cocok untuk memproses DOM, formulir, dan perilaku halaman.
• Skrip SSE hanya cocok untuk stream Server-Sent Events dan tidak boleh digunakan untuk API JSON normal.
• Skrip intersepsi API normal harus mengembalikan string, jika tidak halaman target mungkin gagal mem-parse response.
• Parameter lengkap dan contoh API skrip yang tersedia ada di lampiran API Skrip.
• Konfigurasi kategori akun cocok untuk mendefinisikan perilaku berbeda untuk metode login berbeda pada situs yang sama.