Configuración del sitio

Objetivo

Administra la configuración avanzada del sitio, incluidas URL cifradas, scripts, emulación del navegador, proxy, registro de encabezados de solicitud/respuesta, controles de página y comportamiento de acceso.

Requisitos previos

• El sitio de destino ya se ha creado.
• Antes de publicar scripts, prueba primero el sitio.

Pasos

1. Ve a «Gestión de sitios > Lista de sitios».
2. Busca el sitio de destino y haz clic en la configuración.
3. Activa la URL cifrada si es necesario para evitar que el frontend del usuario muestre directamente la dirección del sitio de origen.
4. Configura la emulación del navegador, el proxy, los encabezados de solicitud, los encabezados de respuesta, los controles de página y los scripts.
5. Guarda la configuración del sitio.
6. Usa una cuenta de prueba para acceder al sitio de destino y verificar apertura, inicio de sesión, navegación, datos de API y procesamiento de eventos SSE.
7. Para personalizar el comportamiento por categoría de cuenta, vuelve a la lista de sitios y abre «Configuración de categoría de cuenta».

Referencia de configuración

Élément	Utilité	Remarques
URL cifrada	Ocultar la dirección del sitio de origen mostrada en el frontend del usuario	No sustituye la autenticación propia del sitio de destino
Emulación del navegador	Ajustar marca del navegador, modelo de dispositivo móvil, zona horaria y otros datos de identificación	Vuelve a validar la compatibilidad del sitio de destino después de cambios
Configuración de proxy	Configurar acceso directo, proxy del sistema, PAC o un servidor proxy fijo para este sitio	Errores de proxy pueden impedir abrir el sitio o causar anomalías de inicio de sesión
Encabezados de solicitud	Registrar encabezados de solicitud específicos para que los scripts de página los lean con api.header(name, true)	Solo se registran encabezados configurados que pasan realmente por el navegador remoto
Encabezados de respuesta	Registrar encabezados de respuesta específicos para que los scripts de página los lean con api.header(name, false)	Los nombres de encabezado se convierten a minúsculas al leerse
Script de página	Procesar DOM, formularios, botones, navegación y mejoras de página	Limita las URL coincidentes para evitar efectos no deseados
Script SSE	Reescribir datos de flujo Server-Sent Events	Adecuado para escenarios avanzados; prueba primero
Script de interceptación de API normal	Reescribir el body de respuesta de API no SSE	El script debe devolver la nueva cadena del body de respuesta
Control de página	Ocultar o eliminar elementos de página por URL y selector	Los selectores pueden fallar después de rediseñar el sitio de destino
Configuración de categoría de cuenta	Definir lógica de inicio de sesión diferenciada para distintas categorías de cuenta	Se usa junto con cuentas de navegador del sitio

Configuración de scripts

El área «Configuración de scripts» de la página de configuración del sitio permite agregar un conjunto de reglas de script para el sitio de destino. Cada regla se ejecuta cuando el navegador remoto accede al sitio de destino, según la URL coincidente y el tipo de script.

Champ	Type	Description
name	string	Nombre del script. Se recomienda el formato "sitio-uso-versión", por ejemplo crm-login-v1.
url	string	URL coincidente. Si está vacío suele interpretarse como *; en producción conviene ser lo más preciso posible.
pageScript	boolean	Indica si es un script de página. Al activarlo, el script se ejecuta en el contexto de la página y puede usar window.api.
sseScript	boolean	Indica si es un script de interceptación SSE. Solo se muestra y surte efecto cuando pageScript = false.
selector	string	Condición de ejecución del script de página. Si se rellena, el script solo se ejecuta cuando la página coincide con este selector CSS o XPath.
content	string	Contenido JavaScript del script. Los parámetros y valores devueltos dependen del tipo de script.

Script de página

Cuando pageScript = true, el script se ejecuta como script de página. Es adecuado para DOM, formularios, clics de botones, navegación, overlays, lectura/escritura de datos de usuario y mejoras de página.

Comportamiento de ejecución:

1. El navegador remoto accede a la página de destino.
2. El sistema inicializa window.api en la página y en los iframes accesibles.
3. Si selector está configurado, el script se ejecuta solo cuando el selector coincide con un elemento.
4. El script puede usar directamente api.config, api.user, api.dom, api.utils y api.header(). Consulta el apéndice de API de scripts para ver la API completa.

Ejemplo: esperar a que aparezca un elemento, ocultar un área publicitaria y leer la configuración del producto.

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

Script SSE

Cuando pageScript = false y sseScript = true, el script intercepta datos de Server-Sent Events. El sistema envuelve EventSource y fetch en la página, y procesa flujos cuya URL coincide y cuyo tipo de contenido es text/event-stream.

Forma de ejecución:

async (data) => {
  // Contenido del script escrito en content
}

Paramètre	Type	Description
data	string	Mensaje SSE actual o texto de chunk del flujo.

El valor devuelto debe ser el nuevo texto SSE. Si no se devuelve una cadena, la página puede recibir datos anómalos.

Ejemplo: reemplazar texto en datos SSE.

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

Script de interceptación de API normal

Cuando pageScript = false y sseScript = false, el script intercepta respuestas de API normales. El sistema coincide con la URL de la API, lee el body de la respuesta y lo entrega al script para reescribirlo.

Forma de ejecución:

async (data, api, url) => {
  // Contenido del script escrito en content
}

Paramètre	Type	Description
data	string	Body de respuesta original.
api	object	API de script. Consulta el apéndice de API de scripts.
url	string	URL de la API interceptada actualmente.

El valor devuelto debe ser la nueva cadena del body de respuesta.

Ejemplo: reescribir una respuesta JSON de API.

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

Reglas de coincidencia de URL

El campo url admite las siguientes reglas:

Écriture	Description	Exemple
*	Coincide con todas las URL	*
regex:<expresión>	Usa una expresión regular para coincidir con la URL	regex:/api/chat
exact:<URL completa>	Coincide exactamente con la URL completa	exact:https://example.com/api/user
script:<expresión>	Ejecuta la expresión usando la URL actual como variable url	script:url.includes('/api/')
Cadena normal	Comprueba si la URL de destino empieza con esta cadena	https://example.com/api/

En scripts de producción, usa rutas exactas o prefijos estables para reducir el riesgo de afectar páginas y API no relacionadas.

Encabezados de solicitud y respuesta

Los encabezados de solicitud y respuesta en la configuración del sitio se usan para registrar headers específicos. Los scripts de página pueden leerlos con api.header(). Consulta el apéndice de API de scripts para ver todos los parámetros.

Pasos:

1. Agrega en «Encabezados de solicitud» los nombres que quieras registrar, por ejemplo authorization, cookie.
2. Agrega en «Encabezados de respuesta» los nombres que quieras registrar, por ejemplo content-type, set-cookie.
3. Guarda la configuración y accede al sitio de destino con el navegador remoto.
4. Léelos en el script de página.

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

Notas:

• Los nombres de header se convierten a minúsculas al leerse.
• Solo pueden leerse headers configurados que hayan pasado realmente por el navegador remoto.
• Los encabezados de respuesta pueden ser arrays de cadenas; los scripts deben manejar arrays y valores vacíos.

Sintaxis de selectores

Los selectores de script y de control de página admiten CSS y XPath.

Écriture	Description
.button.primary	Selector CSS.
xpath://div[@id="app"]	Selector XPath.
.dialog:p	Devuelve el elemento padre del elemento coincidente.
.dialog:p2	Devuelve el padre dos niveles por encima del elemento coincidente.
.header:bottom	En métodos de borde de overlay, usa el borde inferior del elemento objetivo.
.sidebar:right	En métodos de borde de overlay, usa el borde derecho del elemento objetivo.

Proceso de cambio

1. Registra la configuración actual y el contenido de los scripts.
2. Modifica en un sitio de prueba o con una cuenta de prueba.
3. Verifica apertura, inicio de sesión, navegación, cierre de sesión, respuestas de API y eventos SSE.
4. Comprueba si las reglas de control de página ocultan o eliminan los elementos correctos.
5. Sincroniza la configuración con el sitio de producción.
6. Pide a los usuarios relacionados que vuelvan a entrar al sitio y verifiquen.

Verificación

• Las tarjetas del sitio en el frontend del usuario se muestran según la configuración.
• Con URL cifrada, la interfaz del usuario no muestra directamente la URL del sitio de origen.
• Los scripts personalizados surten efecto según las reglas de coincidencia cuando el navegador remoto accede al sitio de destino.
• Los scripts de página leen correctamente la configuración, localizan elementos y procesan el comportamiento de página.
• Los scripts SSE solo reescriben el flujo de eventos de destino y no afectan API normales.
• Los scripts de interceptación de API normal devuelven un body de respuesta válido.
• Después de cambios en el sitio de destino, los scripts y selectores siguen coincidiendo correctamente.

Preguntas frecuentes

• Prueba los scripts en un sitio de prueba antes de usarlos en producción.
• La URL cifrada solo afecta la visualización frontend y la ruta de acceso; no omite las políticas de seguridad del sitio de destino.
• Los scripts de página son adecuados para DOM, formularios y comportamiento de página.
• Los scripts SSE solo son adecuados para flujos Server-Sent Events y no deben usarse para API JSON normales.
• Los scripts de interceptación de API normal deben devolver una cadena; de lo contrario, la página de destino puede no poder analizar la respuesta.
• Los parámetros completos y ejemplos de las API disponibles están en el apéndice de API de scripts.
• La configuración de categoría de cuenta sirve para definir comportamientos diferentes para distintos métodos de inicio de sesión del mismo sitio.