Настройка сайта

Цель

Управляйте расширенными настройками сайта: зашифрованными URL, скриптами, эмуляцией браузера, прокси, записью заголовков запросов/ответов, управлением страницей и поведением доступа.

Предварительные условия

• Целевой сайт уже создан.
• Перед публикацией скриптов сначала протестируйте сайт.

Шаги

1. Откройте «Управление сайтами > Список сайтов».
2. Найдите целевой сайт и нажмите настройки.
3. При необходимости включите зашифрованный URL, чтобы пользовательский интерфейс не показывал адрес исходного сайта напрямую.
4. Настройте эмуляцию браузера, прокси, заголовки запросов, заголовки ответов, управление страницей и скрипты.
5. Сохраните настройки сайта.
6. Используйте тестовую учетную запись для доступа к целевому сайту и проверьте открытие, вход, переходы, данные API и обработку событий SSE.
7. Чтобы настроить поведение по типу учетной записи, вернитесь к списку сайтов и откройте «Настройка типа учетной записи».

Справочник настроек

Élément	Utilité	Remarques
Зашифрованный URL	Скрыть адрес исходного сайта в пользовательском интерфейсе	Не заменяет собственную аутентификацию целевого сайта
Эмуляция браузера	Настроить бренд браузера, модель мобильного устройства, часовой пояс и другие идентификационные данные	После изменений повторно проверьте совместимость целевого сайта
Настройки прокси	Настроить прямой доступ, системный прокси, PAC или фиксированный прокси-сервер для сайта	Ошибки прокси могут помешать открыть сайт или вызвать проблемы входа
Заголовки запросов	Записывать указанные заголовки запросов для чтения скриптами страницы через api.header(name, true)	Записываются только настроенные заголовки, фактически прошедшие через удаленный браузер
Заголовки ответов	Записывать указанные заголовки ответов для чтения скриптами страницы через api.header(name, false)	Имена заголовков при чтении переводятся в нижний регистр
Скрипт страницы	Обрабатывать DOM, формы, кнопки, переходы и улучшения страницы	Ограничивайте совпадающие URL, чтобы избежать нежелательных эффектов
SSE-скрипт	Переписывать данные потока Server-Sent Events	Подходит для продвинутых сценариев; сначала тестируйте
Скрипт перехвата обычного API	Переписывать body ответа API не SSE	Скрипт должен вернуть новую строку body ответа
Управление страницей	Скрывать или удалять элементы страницы по URL и селектору	Селекторы могут перестать работать после изменения целевого сайта
Настройка типа учетной записи	Задать различную логику входа для разных типов учетных записей	Используется вместе с браузерными учетными записями сайта

Настройка скриптов

Раздел «Настройка скриптов» на странице настроек сайта добавляет набор правил скриптов для целевого сайта. Каждое правило выполняется при доступе удаленного браузера к целевому сайту согласно совпадающему URL и типу скрипта.

Champ	Type	Description
name	string	Имя скрипта. Рекомендуемый формат: «сайт-назначение-версия», например crm-login-v1.
url	string	URL для сопоставления. Если пусто, обычно считается *; в production задавайте как можно точнее.
pageScript	boolean	Является ли это скриптом страницы. При включении скрипт выполняется в контексте страницы и может использовать window.api.
sseScript	boolean	Является ли это скриптом перехвата SSE. Показывается и действует только при pageScript = false.
selector	string	Условие выполнения скрипта страницы. Если задано, скрипт выполняется только когда страница соответствует CSS или XPath селектору.
content	string	JavaScript-содержимое скрипта. Аргументы и возвращаемые значения различаются по типу скрипта.

Скрипт страницы

Когда pageScript = true, скрипт выполняется как скрипт страницы. Он подходит для DOM, форм, нажатий кнопок, переходов, оверлеев, чтения/записи пользовательских данных и улучшений страницы.

Поведение выполнения:

1. Удаленный браузер открывает целевую страницу.
2. Система инициализирует window.api на странице и в доступных iframe.
3. Если настроен selector, скрипт выполняется только когда селектор находит элемент.
4. Скрипт может напрямую использовать api.config, api.user, api.dom, api.utils и api.header(). Полный API см. в приложении API скриптов.

Пример: дождаться появления элемента, скрыть рекламный блок и прочитать конфигурацию продукта.

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';
}

SSE-скрипт

Когда pageScript = false и sseScript = true, скрипт перехватывает данные Server-Sent Events. Система оборачивает EventSource и fetch на странице и обрабатывает потоки, URL которых совпадает, а тип содержимого равен text/event-stream.

Форма выполнения:

async (data) => {
  // Содержимое скрипта, введенное в content
}

Paramètre	Type	Description
data	string	Текущее сообщение SSE или текст потокового chunk.

Возвращаемое значение должно быть новым текстом SSE. Если строка не возвращена, страница может получить некорректные данные.

Пример: заменить текст в данных SSE.

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

Скрипт перехвата обычного API

Когда pageScript = false и sseScript = false, скрипт перехватывает обычные ответы API. Система сопоставляет URL API, читает body ответа и передает его скрипту для перезаписи.

Форма выполнения:

async (data, api, url) => {
  // Содержимое скрипта, введенное в content
}

Paramètre	Type	Description
data	string	Исходное body ответа.
api	object	API скриптов. См. приложение API скриптов.
url	string	Текущий URL перехваченного API.

Возвращаемое значение должно быть новой строкой body ответа.

Пример: переписать JSON-ответ API.

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

Правила совпадения URL

Поле url поддерживает следующие правила:

Écriture	Description	Exemple
*	Соответствует всем URL	*
regex:<выражение>	Сопоставляет URL регулярным выражением	regex:/api/chat
exact:<полный URL>	Точно сопоставляет полный URL	exact:https://example.com/api/user
script:<выражение>	Выполняет выражение, где текущий URL доступен как url	script:url.includes('/api/')
Обычная строка	Проверяет, начинается ли целевой URL с этой строки	https://example.com/api/

Для производственных скриптов используйте точные пути или стабильные префиксы, чтобы снизить риск влияния на не связанные страницы и API.

Заголовки запросов и ответов

Заголовки запросов и ответов в настройках сайта используются для записи указанных headers. Скрипты страницы могут читать их через api.header(). Полные параметры см. в приложении API скриптов.

Шаги:

1. В «Заголовки запросов» добавьте имена заголовков для записи, например authorization, cookie.
2. В «Заголовки ответов» добавьте имена заголовков для записи, например content-type, set-cookie.
3. Сохраните настройки и откройте целевой сайт через удаленный браузер.
4. Прочитайте их в скрипте страницы.

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

Примечания:

• Имена header при чтении преобразуются в нижний регистр.
• Можно читать только настроенные headers, которые действительно прошли через удаленный браузер.
• Заголовки ответов могут быть массивами строк; скрипты должны обрабатывать массивы и пустые значения.

Синтаксис селекторов

Селекторы скриптов и управления страницей поддерживают CSS и XPath.

Écriture	Description
.button.primary	CSS-селектор.
xpath://div[@id="app"]	XPath-селектор.
.dialog:p	Возвращает родительский элемент найденного элемента.
.dialog:p2	Возвращает родителя на два уровня выше найденного элемента.
.header:bottom	В методах границ оверлея использует нижнюю границу целевого элемента.
.sidebar:right	В методах границ оверлея использует правую границу целевого элемента.

Процесс изменения

1. Запишите текущие настройки и содержимое скриптов.
2. Изменяйте их на тестовом сайте или с тестовой учетной записью.
3. Проверьте открытие, вход, переходы, выход, ответы API и события SSE.
4. Убедитесь, что правила управления страницей скрывают или удаляют правильные элементы.
5. Синхронизируйте настройки с производственным сайтом.
6. Попросите связанных пользователей заново открыть сайт и проверить.

Проверка результата

• Карточки сайтов в пользовательском интерфейсе отображаются согласно настройкам.
• При включенном зашифрованном URL интерфейс не показывает URL исходного сайта напрямую.
• Пользовательские скрипты срабатывают по правилам совпадения при доступе удаленного браузера к целевому сайту.
• Скрипты страницы корректно читают конфигурацию, находят элементы и обрабатывают поведение страницы.
• SSE-скрипты переписывают только целевой поток событий и не влияют на обычные API.
• Скрипты перехвата обычных API возвращают допустимое body ответа.
• После изменений целевого сайта скрипты и селекторы продолжают совпадать корректно.

Частые вопросы

• Проверяйте скрипты на тестовом сайте перед использованием в производстве.
• Зашифрованный URL влияет только на отображение frontend и путь доступа; он не обходит политики безопасности целевого сайта.
• Скрипты страницы подходят для DOM, форм и поведения страницы.
• SSE-скрипты подходят только для потоков Server-Sent Events и не должны использоваться для обычных JSON API.
• Скрипты перехвата обычного API должны возвращать строку, иначе целевая страница может не разобрать ответ.
• Полные параметры и примеры доступных API см. в приложении API скриптов.
• Настройка типа учетной записи подходит для разных режимов входа на одном сайте.