Пользовательские скрипты

Встроенные скрипты покрывают типовые сценарии. Когда нужно то, чего в них нет — другой порядок шагов, экран, которого они не касаются, или приложение помимо TikTok и Instagram — вы можете написать это сами на любом языке, а TikMatrix передаст вам телефон.

Требования

Требование к лицензии

Пользовательские скрипты доступны на тарифах Pro, Team и Business. На тарифе Starter эта возможность отсутствует.

Количество устройств в тарифе одновременно является и лимитом параллельного выполнения: тариф Pro (20 устройств) позволяет управлять 20 телефонами одновременно — встроенными задачами, пользовательскими скриптами или и тем, и другим.

Два способа запуска

Автономный запуск

Вы запускаете программу сами, TikMatrix лишь одалживает вам устройства.

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())

Подходит для разовых задач, сбора данных и всего, что вы хотите запускать из собственного планировщика.

Управляемый запуск

Вы регистрируете программу в TikMatrix, и она становится обычной задачей: очередь задач, лимит параллельности по тарифу, автоматические повторы, журнал задачи и шаблоны расписания. TikMatrix занимает устройство до запуска вашей программы и передаёт идентификатор аренды через переменные окружения.

from tikmatrix import TikMatrix

with TikMatrix.from_env() as d:   # устройство уже занято для вас
    d.click(text="Log in")
    print("done")                 # эта строка попадёт в журнал задачи

Подходит для всего, что нужно выполнять регулярно, по расписанию или на множестве устройств.

Быстрый старт

1. Установите клиентскую библиотеку

pip install requests

Затем скопируйте tikmatrix.py из каталога SDK рядом со своим скриптом. Библиотека состоит из одного файла и не требует других зависимостей.

Использовать её необязательно — это обычный JSON поверх HTTP, список эндпоинтов приведён ниже.

2. Напишите скрипт

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")

3. Зарегистрируйте его (только для управляемого режима)

Откройте Устройства → Пользовательские скрипты → Добавить скрипт:

Поле	Значение
Название	Отображается в списке скриптов и в журнале задачи
Команда	Командная строка запуска, например python C:/scripts/my_flow.py
Рабочий каталог	Необязательно. Каталог запуска программы
Платформа	См. режимы платформы ниже
Таймаут (с)	Через сколько секунд скрипт будет прерван, а задача помечена неудачной. По умолчанию 1800
Дополнительные переменные окружения	Необязательный JSON-объект, добавляемый в окружение программы

Затем нажмите ▶ в строке скрипта и выберите устройства — так же, как для встроенного скрипта.

Аренда устройств

Телефоном одновременно может управлять только что-то одно. Аренда сообщает TikMatrix, что устройство занято, поэтому:

• очередь задач не отправит задачу на тот же экран, и
• ваши вызовы JSON-RPC сообщают о состоянии агента так же, как встроенный скрипт, поэтому сторожевой таймер видит занятый агент, а не молчащий.

Аренда также занимает один слот устройства из вашего тарифа.

Аренда истекает — по умолчанию через 120 секунд, максимум 600. Python-библиотека продлевает её в фоновом потоке и освобождает при выходе из блока with, поэтому аварийно завершившийся скрипт возвращает устройство за секунды, а не удерживает его до перезапуска приложения. При прямых вызовах API отправлять heartbeat нужно самостоятельно.

Все активные аренды можно посмотреть и принудительно освободить в разделе Настройки → API для разработчиков → Активные сессии устройств.

Режимы платформы

Зарегистрированный скрипт объявляет, на что он рассчитан:

Универсальный (generic) — устройство передаётся как есть. Никакое приложение не запускается, аккаунт не переключается, метод ввода не проверяется, и по завершении ничего не закрывается. Используйте для автоматизации всего, что не является TikTok или Instagram.

TikTok / Instagram — приложение открывается и аккаунт переключается до запуска вашей программы, а по завершении приложение закрывается — в точности как для встроенного скрипта. TIKMATRIX_PACKAGE сообщит, какой пакет был определён. Используйте, чтобы добавить шаг, которого нет во встроенных скриптах.

Переменные окружения

Управляемый скрипт получает:

Переменная	Значение
TIKMATRIX_API_BASE	Адрес сервера, например http://127.0.0.1:50809
TIKMATRIX_SESSION_ID	Уже оформленная за вас аренда
TIKMATRIX_SERIAL	Устройство, на которое отправлена задача
TIKMATRIX_PACKAGE	Определённый пакет приложения
TIKMATRIX_PLATFORM	tiktok, instagram или generic

TikMatrix.from_env() читает всё это за вас.

Автономные скрипты не получают этих переменных — арендуйте устройство явно.

Частые операции

d.info()                                  # информация об устройстве
d.window_size()                           # (ширина, высота)
d.screenshot("shot.png")                  # байты PNG, при желании с сохранением

d.find(text="Following")                  # найденные узлы с bounds и center
d.exists(resource_id="com.app:id/login")
d.wait_for(text="Home", timeout=15)       # ждать появления элемента
d.click(text="Log in")                    # дождаться и нажать в центр

d.click_xy(540, 1200)
d.swipe(540, 1600, 540, 600)
d.press("back")                           # back / home / recent / enter
d.input_text("hello")                     # ввод через встроенный метод ввода

d.jsonrpc("deviceInfo")                   # любой метод UIAutomator2
d.adb("shell", "pm", "list", "packages")  # ADB, после включения в настройках

find ищет по выгруженному дереву интерфейса, поэтому при промахе селектора можно вызвать print(d.hierarchy()) и посмотреть, в чём именно шёл поиск. Инспектор элементов в разделе устройства показывает то же дерево наглядно — обычно это самый быстрый способ найти resource-id.

HTTP-эндпоинты

Операциям с устройством нужен заголовок x-session-id с идентификатором действующей аренды. API-ключа нет: как и остальная часть локального API, эти эндпоинты не требуют аутентификации — доступ к машине по сети и есть контроль доступа. Они не отправляют CORS-заголовки, поэтому вызывайте их из программы (curl, Python и т. п.), а не со страницы в браузере.

Метод	Путь	Назначение
GET	/api/v1/rpc/devices	Список устройств онлайн и признак занятости
POST	/api/v1/rpc/session	Арендовать устройство → session_id
POST	/api/v1/rpc/session/{id}/heartbeat	Продлить аренду
DELETE	/api/v1/rpc/session/{id}	Освободить аренду
GET	/api/v1/rpc/session	Список активных аренд
POST	/api/v1/rpc/jsonrpc	Вызвать метод UIAutomator2
POST	/api/v1/rpc/adb	Выполнить команду ADB
GET	/api/v1/rpc/hierarchy?serial=	Текущее дерево интерфейса (XML)
GET	/api/v1/rpc/screenshot?serial=	Текущий экран (PNG)

Пример

# Арендовать устройство
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", ...}}

# Управлять им
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":[]}'

# Вернуть устройство
curl -X DELETE http://127.0.0.1:50809/api/v1/rpc/session/ff3ae079-...

Ошибки

Код	Значение
403	Тариф ниже Pro, нет аренды, аренда истекла или доступ к ADB отключён
409	Устройство уже арендовано либо в тарифе не осталось свободных слотов

Запуск пользовательского скрипта через API

Зарегистрированные скрипты можно запускать и через API управления задачами, чтобы скрипт мог поставить в очередь дальнейшую работу:

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 — идентификатор зарегистрированного вами скрипта.

Доступ к ADB

/api/v1/rpc/adb даёт скриптам shell устройства — он нужен для загрузки медиафайлов, установки APK и изменения системных настроек. Поскольку это полноценный shell на эндпоинте без API-ключа, по умолчанию он выключен. Включите его в разделе Настройки → API для разработчиков → Разрешить команды ADB, когда появится скрипт, которому он нужен; автоматизация интерфейса через /rpc/jsonrpc работает и без него.

Пока он выключен, /api/v1/rpc/adb отвечает 403, а остальная часть API продолжает работать. Каждая выполненная скриптом команда ADB записывается в ваш журнал.

Замечания и ограничения

• Команда выполняется напрямую, а не через shell, поэтому && и | считаются аргументами, а не операторами. Если нужно поведение shell, зарегистрируйте cmd /c "..." (Windows) или sh -c "..." (macOS).
• Пути с пробелами берите в кавычки: "C:/Program Files/Python/python.exe" my_script.py.
• Скрипт, превысивший таймаут, прерывается, а задача помечается неудачной.
• Ненулевой код выхода означает провал задачи; всё, что скрипт пишет в stdout и stderr, попадает в журнал задачи.
• Скрипты выполняются с теми же правами, что и сам TikMatrix. Регистрируйте только те программы, которые написали сами или которым доверяете.

Что дальше

• Обзор локального API — формат ответов и общие соглашения
• API управления задачами — создание, запрос, повтор и остановка задач
• SDK и примеры на GitHub