SDK de reglas automatizadas y scripts
Una referencia de lo que está disponible dentro del código de una regla de pausa automática y de un script de usuario: los campos del objeto ad, las funciones para pausar y reanudar, y los selectores para elegir anuncios. Las descripciones de todos los campos también están disponibles directamente en el editor de reglas — en el panel lateral Referencia de claves ad.* (búsqueda por nombre y descripción).
Este es el Server SDK — comandos que se ejecutan en el servidor de Qubix, a diferencia del Browser SDK que se ejecuta en el navegador del visitante. El Server SDK es síncrono: sql, ctx.fetch y el estado devuelven un valor directamente — sin await ni Promises.
El objeto ad
En una regla de pausa automática, usted recibe un único objeto ad — este es el anuncio para el que se ejecuta la comprobación. A través de él lee todas las métricas y atributos. Todos los campos disponibles están agrupados por ámbito.
| Grupo | Prefijo del campo | Qué contiene |
|---|---|---|
| Anuncio | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Métricas y atributos del propio anuncio |
| Creativo | ad.creo_* | Métricas por creativo (todos los anuncios con este creativo) |
| Geo | ad.geo_* | Métricas por país |
| Oferta | ad.offer_* | Métricas y parámetros de la oferta (payout, cap) |
| Red | ad.network_* | Métricas por red |
| Periodo anterior | ad.prev_* | Las mismas métricas para el periodo anterior (para comparar) |
La lista completa de métricas, las ventanas temporales (_1h…_total) y el significado de cada prefijo — en la sección Métricas y columnas.
Acceder a un campo inexistente (ad.something_wrong) aborta de inmediato la regla con un error. Compruebe los nombres contra la referencia en el editor.
Pausa
Tres funciones — por ámbito. El anuncio, el conjunto de anuncios y la campaña.
| Función | Acción |
|---|---|
pauseAd(duration, reason?) | Pausar el anuncio actual |
pauseAdset({ adsetId, duration, reason? }) | Pausar el conjunto de anuncios |
pauseCampaign({ campaignId, duration, reason? }) | Pausar la campaña |
Para pauseAd basta con pasar la duración como una cadena; para el conjunto de anuncios y la campaña se requiere la forma de objeto con un adsetId / campaignId explícito.
Duraciones (duration):
| Valor | Significado |
|---|---|
6h / 12h / 24h | Pausa durante N horas |
next_day_target_geo | Hasta el inicio del día siguiente en la hora del país de destino |
next_day_ad_account | Hasta el inicio del día siguiente en la hora de la cuenta publicitaria |
permanent | Una pausa permanente |
while_matches | Mientras la condición de la regla se cumpla |
reason es un comentario opcional que va al log. Si se omite, se sustituye por el nombre de la regla.
Reanudar
| Función | Acción |
|---|---|
activateAd(reason?) | Reanudar el anuncio actual |
activateAdset({ adsetId, reason? }) | Reanudar el conjunto de anuncios |
activateCampaign({ campaignId, reason? }) | Reanudar la campaña |
Anuncios vecinos
Dentro de una regla, usted puede mirar otros anuncios del mismo conjunto de anuncios o campaña — por ejemplo, para detener todo el conjunto de anuncios si solo uno cayó.
| Función | Devuelve |
|---|---|
getAd(id) | Un anuncio por su ad_id |
getAdset() | Todos los anuncios del conjunto de anuncios del anuncio actual |
getCampaign() | Todos los anuncios de la campaña del anuncio actual |
También están disponibles console.log / console.warn / console.error para la salida de depuración y skipNextRules() — omitir las reglas restantes para este anuncio.
Selectores de QubixApp (para scripts)
En los scripts de usuario, está disponible el objeto QubixApp — selecciona anuncios, conjuntos de anuncios y campañas por condiciones. Cada elemento seleccionado tiene sus propias estadísticas y métodos de pausa.
| Método | Devuelve una selección de |
|---|---|
QubixApp.ads() | Anuncios |
QubixApp.adsets() | Conjuntos de anuncios |
QubixApp.campaigns() | Campañas |
Métodos de selección (encadenados):
| Método | Qué hace |
|---|---|
.withCondition(sql) | Filtrar por una condición |
.filter(fn) | Filtrar con una función |
.orderBy(field, dir) | Ordenar ('asc' / 'desc') |
.withLimit(n) | Limitar el número de elementos |
.get() | Obtener un array de elementos |
.first() | Obtener el primer elemento |
Métodos de elemento:
| Método | Acción |
|---|---|
.pause({ duration, reason? }) | Pausar |
.activate({ reason? }) | Reanudar |
.getStatsFor(period) | Métricas de una ventana ('1h'…'total') |
.getAds() | Anuncios dentro de un conjunto de anuncios / campaña |
.getAdsets() | Conjuntos de anuncios dentro de una campaña |
getStatsFor devuelve un conjunto de métricas para la ventana seleccionada: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Contexto del script
En los scripts, está disponible adicionalmente el objeto ctx.
| Campo / método | Propósito |
|---|---|
ctx.state.get/set/delete/keys | Persistir el estado entre ejecuciones |
ctx.fetch(url, opts?) | Una petición HTTP (el host debe estar en la lista blanca, ver JavaScript en la configuración) |
ctx.now() | La hora actual |
ctx.script | Información sobre el script actual |
El objeto ctx (incluido ctx.fetch) existe solo en los scripts — no está disponible dentro de las reglas de pausa automática. E incluso en los scripts, ctx.fetch solo funciona en una ejecución real en el servidor: en una ejecución de prueba en el navegador las llamadas de red están desactivadas, así que verifíquelo mediante una ejecución real.
Estado compartido
Además de su ctx.state privado, existe un almacén compartido ctx.state.global, visible para todos los scripts, reglas y handlers de sitios a la vez.
| Método | Acción |
|---|---|
ctx.state.global.get(key) | Leer un valor |
ctx.state.global.keys() | Listar las claves |
ctx.state.global.set(key, value) | Escribir un valor |
ctx.state.global.delete(key) | Eliminar un valor |
Cualquier script o regla puede leer el almacén compartido. Escribir (set / delete) solo está permitido desde un script o regla cuyo propietario sea un administrador — de lo contrario, la escritura genera un error. Resulta útil para búsquedas compartidas: el administrador escribe un valor una vez, todos los demás lo leen.
ctx.fetch: un tiempo de espera de 10 segundos por defecto (30 como máximo), una respuesta de hasta 1 MB, no más de 20 peticiones por ejecución.sql: una sola consulta devuelve como máximo unos pocos miles de filas — el administrador establece el límite exacto en la configuración. Para selecciones grandes, agregue directamente en la consulta.
Los valores exactos de los límites se configuran en Sistema → la pestaña JavaScript.
sql de solo lectura
La plantilla etiquetada sql\SELECT …`ejecuta una consulta de datos de solo lectura dentro de los permisos del propietario. Está disponible **tanto en las reglas de pausa automática (Britva) como en los scripts de usuario** — siempre que la configuración del sistema correspondiente esté activada. En una ejecución de prueba en el navegador está desactivada (comoctx.fetch), así que verifique una regla o script que use sql` mediante una ejecución real en el servidor.
La lista completa de tablas y columnas a las que puede llegar una consulta está en Tablas para consultas sql.