Skrip Kustom

Skrip bawaan sudah mencakup alur yang umum. Ketika Anda butuh sesuatu yang tidak disediakan — satu langkah dengan urutan berbeda, layar yang tidak pernah disentuh, atau aplikasi yang bukan TikTok maupun Instagram — Anda bisa menulisnya sendiri dalam bahasa apa pun dan TikMatrix akan menyerahkan ponselnya kepada Anda.

Persyaratan

Persyaratan Lisensi

Skrip kustom memerlukan paket Pro, Team, atau Business. Paket Starter tidak memiliki akses.

Jumlah perangkat pada paket Anda sekaligus menjadi batas konkurensi: paket Pro (20 perangkat) dapat menjalankan 20 ponsel sekaligus, baik lewat tugas bawaan, skrip kustom, maupun campuran keduanya.

Dua cara menjalankan skrip

Mandiri

Anda menjalankan program sendiri. TikMatrix hanya meminjamkan perangkat.

from tikmatrix import TikMatrix

client = TikMatrix()

for device in client.devices():
    if device["busy"]:
        continue
    with client.device(device["serial"], label="my crawler") as d:
        d.press("home")
        print(d.info())

Cocok untuk pekerjaan sekali jalan, pengumpulan data, dan apa pun yang ingin Anda jalankan dari penjadwal sendiri.

Terkelola

Anda mendaftarkan program di TikMatrix dan ia menjadi tugas seperti yang lain. Ia mendapat antrean tugas, konkurensi sesuai paket, percobaan ulang otomatis, log tugas, dan template jadwal. TikMatrix menyewa perangkat sebelum menjalankan program Anda dan mengoper id sewanya lewat environment.

from tikmatrix import TikMatrix

with TikMatrix.from_env() as d:   # perangkat sudah disewa
    d.click(text="Log in")
    print("done")                 # baris ini masuk ke log tugas

Cocok untuk apa pun yang ingin dijalankan berulang, terjadwal, atau di banyak perangkat.

Mana yang dipilih

	Mandiri	Terkelola
Siapa yang memulai	Anda	Antrean tugas TikMatrix
Sewa perangkat	Anda ambil sendiri	Sudah dipegang saat mulai
Percobaan ulang, jadwal, log	Anda bangun sendiri	Sudah termasuk
Jalan di banyak perangkat	Anda tulis perulangannya	Satu tugas per perangkat, paralel
Paling cocok untuk	Eksplorasi, crawler, pekerjaan sekali jalan	Apa pun yang ingin diulang

Anda bisa mulai dengan mode mandiri sambil merapikan alurnya, lalu mendaftarkan berkas yang sama sebagai skrip terkelola — satu-satunya baris yang berubah adalah TikMatrix.from_env().

Memulai

1. Pasang pustaka klien

pip install requests

Lalu salin tikmatrix.py dari direktori SDK ke sebelah skrip Anda. Pustaka ini hanya satu berkas tanpa dependensi lain.

Anda tidak wajib memakainya — API-nya JSON biasa lewat HTTP, dan endpoint mentahnya didokumentasikan di bawah.

2. Tulis skrip Anda

from tikmatrix import TikMatrix

client = TikMatrix()
with client.device("192.168.1.5:5555") as d:
    d.press("home")
    d.adb("shell", "am", "start", "-a", "android.settings.SETTINGS")
    d.wait_for(text="Settings", timeout=15)
    d.screenshot("settings.png")

Jalankan dengan TikMatrix terbuka dan ponsel terhubung. Kalau ia mencetak kamus info perangkat, semuanya sudah tersambung.

3. Daftarkan (hanya mode terkelola)

Buka Perangkat → Skrip Kustom → Tambah Skrip:

Kolom	Arti
Nama	Tampil di daftar skrip dan log tugas
Perintah	Baris program yang dijalankan, mis. `python C:/scripts/my_flow.py`
Direktori kerja	Opsional. Tempat program dimulai
Platform	Lihat mode platform di bawah
Batas waktu	Detik sebelum skrip dihentikan dan tugas ditandai gagal. Bawaan 1800
Variabel environment tambahan	Objek JSON opsional yang digabung ke environment program
Aktif	Matikan skrip tanpa menghapusnya. Skrip nonaktif tidak bisa dikirim

Lalu tekan ▶ pada baris skrip dan pilih perangkat Anda, persis seperti skrip bawaan.

Biarkan asisten yang menulisnya

Asisten AI bisa menyusun skrip kustom dari deskripsi bahasa sehari-hari dan mendaftarkannya dalam satu langkah. Ia menunjukkan seluruh berkas sebelum apa pun ditulis ke disk.

Sewa perangkat

Sebuah ponsel hanya bisa dikendalikan oleh satu hal pada satu waktu. Menyewanya memberi tahu TikMatrix bahwa perangkat sedang sibuk, sehingga:

antrean tugas tidak akan mengirim tugas ke layar yang sama, dan
panggilan JSON-RPC Anda melaporkan kesehatan agen persis seperti skrip bawaan, sehingga watchdog melihat agen yang sibuk, bukan agen yang bisu.

Sewa juga memakai satu slot perangkat dari paket Anda.

Sewa punya masa berlaku — 120 detik secara bawaan, maksimum 600. Pustaka Python memperbaruinya di thread latar dan melepaskannya saat blok with berakhir, sehingga skrip yang mati membebaskan perangkatnya dalam hitungan detik alih-alih menahannya sampai aplikasi di-restart. Kalau Anda memanggil API langsung, kirim heartbeat sendiri.

Semua sewa aktif dapat dilihat — dan dilepas paksa — di Pengaturan → Developer API → Sesi perangkat aktif.

Mode platform

Skrip terdaftar mendeklarasikan sasarannya:

Generic — perangkat diserahkan apa adanya. Tidak ada aplikasi yang dibuka, tidak ada pergantian akun, tidak ada pemeriksaan metode masukan, dan tidak ada yang ditutup sesudahnya. Gunakan untuk mengotomatiskan apa pun selain TikTok atau Instagram.

TikTok / Instagram — aplikasi dibuka dan akun diganti sebelum program Anda mulai, lalu aplikasi ditutup saat selesai, persis seperti skrip bawaan. TIKMATRIX_PACKAGE memberi tahu paket mana yang dipakai. Gunakan untuk menambahkan langkah yang tidak dicakup skrip bawaan.

Variabel environment

Skrip terkelola menerima:

Variabel	Arti
`TIKMATRIX_API_BASE`	URL server, mis. `http://127.0.0.1:50809`
`TIKMATRIX_SESSION_ID`	Sewa yang sudah dipegang untuk Anda
`TIKMATRIX_SERIAL`	Perangkat tujuan tugas ini
`TIKMATRIX_PACKAGE`	Paket aplikasi yang dipakai
`TIKMATRIX_PLATFORM`	`tiktok`, `instagram`, atau `generic`

TikMatrix.from_env() membaca semuanya untuk Anda.

Skrip mandiri tidak menerima satu pun — sewalah perangkat secara eksplisit.

Apa pun yang Anda isikan di Variabel environment tambahan digabungkan di atasnya. Itulah cara umum memberi satu skrip terdaftar pengaturan per-jalan tanpa mengubah berkasnya.

Referensi pustaka Python

`TikMatrix` — koneksi

Panggilan	Fungsinya
`TikMatrix(base_url=None, timeout=30.0)`	Menyambung. Jatuh ke `TIKMATRIX_API_BASE`, lalu `http://127.0.0.1:50809`
`client.devices()`	Perangkat daring, masing-masing dengan `serial`, `real_serial`, dan `busy`
`client.sessions()`	Semua sewa aktif, termasuk yang bukan milik proses ini
`client.device(serial, label=..., ttl_secs=120)`	Menyewa perangkat dan mengembalikan `Device`
`TikMatrix.from_env()`	Mengambil alih perangkat yang diberikan saat skrip terkelola dimulai

`Device` — ponselnya

Panggilan	Fungsinya
`d.info()`	Info perangkat dari UIAutomator2
`d.window_size()`	`(lebar, tinggi)`
`d.screenshot(path=None)`	Byte PNG, opsional ditulis ke `path`
`d.hierarchy()`	Pohon UI saat ini sebagai XML
`d.find(text=, resource_id=, description=, class_name=)`	Node yang cocok, masing-masing dengan `bounds` dan `center`
`d.exists(**criteria)`	Apakah ada yang cocok
`d.wait_for(timeout=10.0, interval=1.0, **criteria)`	Menunggu sampai muncul lalu mengembalikannya
`d.click(timeout=10.0, **criteria)`	Menunggu elemen lalu mengetuk pusatnya
`d.click_xy(x, y)`	Mengetuk koordinat
`d.swipe(sx, sy, ex, ey, steps=20)`	Menggeser
`d.press(key)`	`back`, `home`, `recent`, `enter`, …
`d.input_text(text)`	Mengetik ke kolom aktif lewat IME cepat bawaan
`d.jsonrpc(method, params=None, timeout=10)`	Metode UIAutomator2 apa pun
`d.adb(*args, timeout_ms=None)`	Menjalankan perintah ADB
`d.release()`	Melepas sewa. `with` melakukannya untuk Anda

find mencocokkan pada pohon UI yang di-dump, jadi ketika sebuah selektor meleset Anda bisa print(d.hierarchy()) dan melihat persis apa yang dicari. Element Inspector di tampilan perangkat menunjukkan pohon yang sama secara visual, dan biasanya itu cara tercepat menemukan resource-id.

input_text butuh ADB

Ia mengirim broadcast ke metode masukan bawaan lewat adb shell. Aktifkan akses ADB sebelum memakainya, kalau tidak akan gagal dengan 403.

Kesalahan

Pustaka ini melempar dua pengecualian, keduanya turunan RuntimeError:

Pengecualian	Kapan
`DeviceBusyError`	HTTP 409 — perangkat sudah disewa, atau paket Anda tak punya slot kosong
`TikMatrixError`	Selebihnya: paket terlalu rendah, sewa kedaluwarsa, ADB nonaktif, selektor tidak pernah cocok

from tikmatrix import TikMatrix, TikMatrixError, DeviceBusyError

client = TikMatrix()
try:
    with client.device("192.168.1.5:5555") as d:
        d.click(text="Log in", timeout=20)
except DeviceBusyError:
    print("ponsel itu sedang dipakai yang lain — coba yang lain")
except TikMatrixError as exc:
    print("gagal:", exc)

Pada skrip terkelola, membiarkan pengecualian lolos keluar biasanya justru tepat: keluaran bukan nol menandai tugas gagal dan traceback-nya masuk ke log tugas.

Endpoint HTTP

Operasi perangkat memerlukan header x-session-id yang menunjuk sewa aktif. Tidak ada kunci API: seperti bagian lain API lokal, endpoint ini tidak diautentikasi — bisa menjangkau mesin ini di jaringan itulah kontrol aksesnya. Endpoint ini tidak mengirim header CORS, jadi panggil dari program (curl, Python, kode sisi server apa pun), bukan dari halaman di peramban.

Metode	Jalur	Tujuan
`GET`	`/api/v1/rpc/devices`	Daftar perangkat daring dan apakah sibuk
`POST`	`/api/v1/rpc/session`	Menyewa perangkat → `session_id`
`POST`	`/api/v1/rpc/session/{id}/heartbeat`	Memperpanjang sewa
`DELETE`	`/api/v1/rpc/session/{id}`	Melepas sewa
`GET`	`/api/v1/rpc/session`	Daftar sewa aktif
`POST`	`/api/v1/rpc/jsonrpc`	Memanggil metode UIAutomator2
`POST`	`/api/v1/rpc/adb`	Menjalankan perintah ADB
`GET`	`/api/v1/rpc/hierarchy?serial=`	Pohon UI saat ini sebagai XML
`GET`	`/api/v1/rpc/screenshot?serial=`	Layar saat ini sebagai PNG

Respons JSON memakai pembungkus yang sama dengan bagian lain API lokal — {"code": 0, "message": "success", "data": ...}, dengan code bukan nol saat gagal. hierarchy dan screenshot mengembalikan body mentah.

Contoh

# Menyewa perangkat
curl -X POST http://127.0.0.1:50809/api/v1/rpc/session \
  -H "Content-Type: application/json" \
  -d '{"serial":"192.168.1.5:5555","label":"curl test","ttl_secs":120}'

# {"code":0,"message":"success","data":{"session_id":"ff3ae079-...","serial":"192.168.1.5:5555", ...}}

# Mengendalikannya
curl -X POST http://127.0.0.1:50809/api/v1/rpc/jsonrpc \
  -H "x-session-id: ff3ae079-..." \
  -H "Content-Type: application/json" \
  -d '{"serial":"192.168.1.5:5555","method":"deviceInfo","params":[]}'

# Menjaga sewa tetap hidup selama bekerja
curl -X POST http://127.0.0.1:50809/api/v1/rpc/session/ff3ae079-.../heartbeat \
  -H "Content-Type: application/json" \
  -d '{"ttl_secs":120}'

# Mengembalikannya
curl -X DELETE http://127.0.0.1:50809/api/v1/rpc/session/ff3ae079-...

Kesalahan

Status	Arti
403	Paket di bawah Pro, tanpa sewa, sewa kedaluwarsa, atau akses ADB nonaktif
409	Perangkat sudah disewa, atau paket tak punya slot kosong

Menulis dalam bahasa lain

Tidak ada yang khusus Python di sini. Runtime apa pun yang bisa membuat permintaan HTTP bisa dipakai — kontrak mode terkelola hanyalah "baca tiga variabel environment, keluar dengan 0 saat berhasil".

// my_flow.js — daftarkan dengan:  node C:/scripts/my_flow.js
const base = process.env.TIKMATRIX_API_BASE || "http://127.0.0.1:50809";
const serial = process.env.TIKMATRIX_SERIAL;
const session = process.env.TIKMATRIX_SESSION_ID;

async function jsonrpc(method, params = []) {
  const res = await fetch(`${base}/api/v1/rpc/jsonrpc`, {
    method: "POST",
    headers: { "content-type": "application/json", "x-session-id": session },
    body: JSON.stringify({ serial, method, params }),
  });
  const body = await res.json();
  if (!res.ok || body.code !== 0) throw new Error(body.message || res.statusText);
  return body.data;
}

console.log(await jsonrpc("deviceInfo"));

Kalau interpreter tidak ada di PATH, tulis jalur lengkapnya di Perintah, mis. C:/Program Files/nodejs/node.exe C:/scripts/my_flow.js.

Memicu skrip kustom dari API

Skrip terdaftar juga bisa dijalankan lewat API Manajemen Tugas, sehingga satu skrip bisa mengantrekan pekerjaan lanjutan:

curl -X POST http://127.0.0.1:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["192.168.1.5:5555"],
    "script_name": "custom_script",
    "script_config": {
      "custom_script_id": 1,
      "custom_script_platform": "generic"
    }
  }'

custom_script_id adalah id skrip yang Anda daftarkan.

Akses ADB

/api/v1/rpc/adb memberi skrip Anda shell perangkat — Anda memerlukannya untuk mengirim media, memasang APK, dan mengubah pengaturan sistem. Karena ini shell penuh pada endpoint tanpa kunci API, fiturnya dikirim dalam keadaan mati. Aktifkan di Pengaturan → Developer API → Izinkan perintah ADB ketika Anda punya skrip yang membutuhkannya; otomatisasi UI lewat /rpc/jsonrpc tetap jalan tanpanya.

Selama mati, /api/v1/rpc/adb menjawab 403 dan sisa API tetap bekerja. Setiap perintah ADB yang dijalankan skrip ditulis ke berkas log Anda.

Menulis skrip yang tetap berfungsi

Tunggu layarnya, jangan tidur untuknya. d.wait_for(...) kembali begitu elemennya ada; sleep tetap itu entah lebih lambat dari perlunya, atau terlalu pendek di hari yang buruk.
Periksa sebelum mengetuk. d.exists(...) pada dialog persetujuan atau ajakan "nanti saja" hanya berbiaya satu dump pohon, dan menyelamatkan satu jalannya skrip yang jika tidak akan mengetuk ke ruang kosong.
Cetak apa yang Anda lakukan. Di mode terkelola, stdout adalah log tugas, dan itu satu-satunya jejak dari jalannya skrip yang tak seorang pun tonton.
Buat pengulangan aman. Percobaan ulang menjalankan seluruh program dari awal, jadi skrip yang mem-posting sebaiknya memeriksa apakah ia sudah mem-posting, bukan menganggap dirinya mulai dari nol.
Satu skrip satu pekerjaan. Konkurensi dihitung per perangkat, jadi sepuluh tugas kecil di sepuluh ponsel selesai jauh lebih cepat daripada satu skrip yang mengulang sepuluh ponsel.

Catatan dan batasan

Perintah dieksekusi langsung, bukan lewat shell, jadi && dan | dianggap argumen, bukan operator. Daftarkan cmd /c "..." (Windows) atau sh -c "..." (macOS) kalau Anda ingin perilaku shell.
Beri tanda kutip pada jalur yang mengandung spasi: "C:/Program Files/Python/python.exe" my_script.py.
Skrip yang melewati batas waktunya dihentikan dan tugasnya ditandai gagal.
Kode keluar bukan nol menandai tugas gagal; semua yang ditulis skrip ke stdout dan stderr masuk ke log tugas.
Skrip berjalan dengan izin yang sama seperti TikMatrix sendiri. Hanya daftarkan program yang Anda tulis atau percayai.

Pemecahan masalah

API access requires Pro or higher plan (403) Lisensi di mesin ini Starter atau tidak aktif. Periksa Pengaturan → Lisensi.

Koneksi ditolak di 127.0.0.1:50809 TikMatrix tidak berjalan, atau berjalan sebagai pengguna lain. Server hanya ada selama aplikasi terbuka.

409 pada setiap upaya sewa Entah ponselnya memang sibuk — periksa Pengaturan → Developer API → Sesi perangkat aktif — atau semua slot perangkat di paket Anda sudah dipakai tugas yang sedang berjalan.

Sewa kedaluwarsa di tengah langkah panjang TTL bawaan 120 detik dan pustaka memperbaruinya di latar, jadi ini biasanya berarti skrip memblokir thread utamanya lebih lama dari TTL. Naikkan ttl_secs (sampai 600), atau pindahkan pekerjaan panjang keluar dari thread itu.

d.adb(...) gagal dengan 403 Akses ADB mati. Nyalakan di Pengaturan → Developer API → Izinkan perintah ADB.

Selektor tidak pernah cocok print(d.hierarchy()) menunjukkan pohon persis yang dicari find. Teks dicocokkan persis, jadi spasi berlebih atau label yang diterjemahkan adalah penyebab biasa; mencocokkan lewat resource_id lebih stabil daripada lewat text.

Tugas ditandai gagal tapi ponselnya tampak baik-baik saja Baca log tugas. Keluar dengan kode bukan nol — termasuk pengecualian yang tak tertangani di akhir jalannya skrip yang sebenarnya berhasil — tetap menggagalkan tugas.

Langkah berikutnya

Ikhtisar API Lokal — autentikasi dan format respons
API Manajemen Tugas — membuat, melihat, mengulang, dan menghentikan tugas
Asisten AI — biarkan model menyusun dan mendaftarkan skrip untuk Anda
SDK dan contoh di GitHub

Persyaratan​

Dua cara menjalankan skrip​

Mandiri​

Terkelola​

Mana yang dipilih​

Memulai​

1. Pasang pustaka klien​

2. Tulis skrip Anda​

3. Daftarkan (hanya mode terkelola)​

Sewa perangkat​

Mode platform​

Variabel environment​

Referensi pustaka Python​

TikMatrix — koneksi​

Device — ponselnya​

Kesalahan​

Endpoint HTTP​

Contoh​

Kesalahan​

Menulis dalam bahasa lain​

Memicu skrip kustom dari API​

Akses ADB​

Menulis skrip yang tetap berfungsi​

Catatan dan batasan​

Pemecahan masalah​

Langkah berikutnya​

Persyaratan

Dua cara menjalankan skrip

Mandiri

Terkelola

Mana yang dipilih

Memulai

1. Pasang pustaka klien

2. Tulis skrip Anda

3. Daftarkan (hanya mode terkelola)

Sewa perangkat

Mode platform

Variabel environment

Referensi pustaka Python

`TikMatrix` — koneksi

`Device` — ponselnya

Kesalahan

Endpoint HTTP

Contoh

Kesalahan

Menulis dalam bahasa lain

Memicu skrip kustom dari API

Akses ADB

Menulis skrip yang tetap berfungsi

Catatan dan batasan

Pemecahan masalah

Langkah berikutnya