Saltar al contenido principal

Escribir un script

El editor de scripts es el espacio de trabajo donde escribes el código, lo pruebas con datos reales y configuras la programación. La pantalla se divide en tres partes: a la izquierda — el asistente IA, en el centro — el editor de código y la consola, a la derecha — el panel de configuración (metadatos, programación, estado, historial de ejecuciones).

vista general del editor de scripts — tres columnas

Cómo crear un script​

  1. Abre la sección Scripts y pulsa + Crear script. El editor se abre con una plantilla de código. un script nuevo con la plantilla de código
  2. En el panel derecho, en la sección Metadatos, rellena el Nombre y la Descripción del script.
  3. En el editor central, escribe el cuerpo de la función main() — exactamente lo que el script debe hacer (ver la sección SDK de QubixApp más abajo).
  4. En la sección Programación, fija con qué frecuencia se ejecutará el script automáticamente (ver Programación). Puedes dejarla vacía si solo lo vas a ejecutar manualmente.
  5. Pulsa el botón Ejecutar debajo del editor para probar el script con datos reales — el resultado aparece en la consola (ver Probar el script).
  6. Activa el conmutador Activo en la esquina superior derecha y pulsa Guardar.
Consejo

Puedes guardar con el atajo de teclado Ctrl + S (en macOS — Cmd + S) directamente desde el editor, sin mover el cursor al botón.

Asistente IA​

La columna izquierda es un chat con el asistente IA. Describe la tarea con palabras sencillas ("detener anuncios con un ROAS por debajo de 0,5 y un gasto superior a 20 $"), y el asistente generará código listo contra el SDK de Qubix. El botón Insertar en Code debajo de la respuesta lo coloca directamente en el editor.

Debajo del campo de entrada hay prompts de ejemplo listos — pulsa cualquiera de ellos para empezar rápido.

El asistente también puede inventar un Nombre y una Descripción para el script a partir de su código — pulsa el icono de IA junto a estos campos en la sección Metadatos.

🎬 GIF: una petición al asistente IA e inserción del código en el editor

SDK de QubixApp​

Un script es una función main(), dentro de la cual trabajas con los datos de los anuncios a través del conjunto de comandos QubixApp. Hay tres niveles disponibles:

  • QubixApp.ads() — anuncios,
  • QubixApp.adsets() — conjuntos de anuncios,
  • QubixApp.campaigns() — campañas.

Cada uno de ellos devuelve una selección que se puede filtrar e iterar. La selección tiene métodos:

  • .withCondition('...') — seleccionar por una condición sobre las métricas (por ejemplo, 'spend_24h > 10 AND roas_24h < 0.5');
  • .orderBy('field', 'desc') — ordenar;
  • .withLimit(n) — limitar la cantidad;
  • .get() — obtener un array de elementos;
  • .first() — obtener el primer elemento.

Cada anuncio, conjunto de anuncios o campaña tiene acciones:

  • .pause({ duration: '24h', reason: '...' }) — pausar durante el periodo especificado;
  • .activate({ reason: '...' }) — volver a activar;
  • .getStatsFor('24h') — obtener métricas de un periodo.

Ejemplo básico: pausar anuncios con un gasto superior a 10 $ y un ROAS por debajo de 0,5 en el último día.

pause-low-roas.jsJavaScript
function main() {
  const ads = QubixApp.ads()
    .withCondition('spend_24h > 10 AND roas_24h < 0.5')
    .get()

  for (const ad of ads) {
    console.log('pausing', ad.name, 'roas24h=', ad.roas_24h)
    ad.pause({ duration: '24h', reason: 'low roas' })
  }
}

Hay más fragmentos listos en la sección Ejemplos de scripts.

Consejo

El autocompletado funciona en el editor: empieza a escribir ad. o QubixApp. — Qubix sugerirá los campos y métodos disponibles con descripciones. Así no tendrás que mantener la lista de métricas en la cabeza.

Consultas a la base de datos​

Además de los anuncios actuales disponibles a través de QubixApp, un script puede leer datos directamente de la base de datos de Qubix con el comando sql. Es una consulta de solo lectura escrita como una plantilla etiquetada:

JavaScript
const rows = sql`
  SELECT country, sum(spend) AS spend
    FROM hourly_insights
   WHERE date >= ${'2026-06-01'}
   GROUP BY country`
for (const row of rows) console.log(row.country, row.spend)

Una consulta devuelve un array de filas; cada fila es un objeto cuyas claves son los nombres de las columnas. Los valores que pasas a través de ${…} se envían como parámetros seguros — no escapas nada a mano, y la inyección SQL no es posible. Las consultas son de solo lectura: un script puede leer datos pero no puede cambiar nada. Lo que una consulta puede alcanzar está limitado a los datos que tu rol tiene permitido ver.

Estado entre ejecuciones​

Un script puede recordar valores entre ejecuciones a través de ctx.state — esta es su memoria personal:

  • ctx.state.set('key', value) — guardar;
  • ctx.state.get('key') — leer;
  • ctx.state.delete('key') — eliminar.

Por ejemplo, esto permite recordar qué anuncios ya se han procesado y no volver a tocarlos. El contenido actual de la memoria es visible en el panel derecho en la sección Estado — desde ahí también se puede eliminar manualmente una entrada concreta.

Peticiones a servicios externos​

El comando ctx.fetch(url, opts) realiza una petición HTTP al exterior — por ejemplo, para enviar una notificación a un mensajero o para llamar a la API de otra persona.

Atención

Las peticiones salientes solo se permiten a direcciones de la lista blanca. El administrador la configura en Sistema → la pestaña JavaScript. Si la lista está vacía, las peticiones salientes están desactivadas. Al intentar alcanzar una dirección que no está en la lista, el script mostrará una pista clara en la consola.

Programación​

En el panel derecho, la sección Programación fija cuándo se ejecuta el script automáticamente. Puede haber varias programaciones — por ejemplo, una vez por hora y adicionalmente a una hora concreta.

  1. Introduce la programación en formato cron (por ejemplo, */5 * * * * — cada 5 minutos) y pulsa +.
  2. Debajo de la línea, Qubix muestra de inmediato una explicación en palabras sencillas — comprueba que os habéis entendido correctamente.
  3. Para no recordar la sintaxis de cron, pulsa el icono de IA en la línea y describe la programación con palabras ("cada día a las 9 de la mañana") — Qubix rellenará la expresión lista.

la sección Programación con la explicación del cron

nota

Si no se establece ninguna programación, el script no se ejecutará por sí solo — solo a través del botón Ejecutar. Para que funcione la ejecución automática, el conmutador Activo debe estar encendido.

Probar el script con el botón "Ejecutar"​

Debajo del editor de código hay una consola y un botón ▶ Ejecutar. Ejecuta el código que hay actualmente en el editor con datos reales — es una forma segura de probar la lógica sin esperar a la programación. Todo lo que el script muestra a través de console.log aparece en la consola junto con la hora de ejecución, el estado y la duración.

la consola con el resultado de la ejecución

Atención

El botón Ejecutar realiza acciones reales. Si el código contiene pause() o activate(), los anuncios se pausarán o activarán de verdad. Para probar la lógica sin consecuencias, comenta primero las líneas con acciones y deja solo console.log.

El botón Ejecutar queda disponible después de guardar el script por primera vez.

Historial de ejecuciones​

La sección Ejecuciones en el panel derecho conserva el historial de todas las ejecuciones: hora, estado (éxito, error, timeout), duración y el número de acciones realizadas. Al pulsar una fila se despliega la salida completa de la consola de esa ejecución — útil para averiguar por qué el script se comportó de forma inesperada.

Qué sigue​

Ejemplos de scripts

Escenarios listos para tareas comunes.

Reglas automatizadas de Britva

Cuando basta con pausar/devolver por anuncio según una condición.

On this page