SDK de regras automáticas e scripts
Uma referência do que está disponível dentro do código de uma regra de pausa automática e de um script de usuário: os campos do objeto ad, as funções para pausar e retornar ao trabalho, e os seletores para escolher anúncios. As legendas de todos os campos com descrições também estão disponíveis diretamente no editor de regras — no painel lateral Referência de chaves ad.* (busca por nome e descrição).
Este é o Server SDK — comandos executados no servidor do Qubix, ao contrário do Browser SDK que é executado no navegador do visitante. O Server SDK é síncrono: sql, ctx.fetch e state retornam um valor diretamente — sem await ou Promises.
O objeto ad
Em uma regra de pausa automática, você recebe um único objeto ad — este é o anúncio para o qual a verificação está sendo executada. Por meio dele, você lê todas as métricas e atributos. Todos os campos disponíveis são agrupados por escopo.
| Grupo | Prefixo do campo | O que contém |
|---|---|---|
| Ad | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Métricas e atributos do próprio anúncio |
| Creative | ad.creo_* | Métricas por criativo (todos os anúncios com este criativo) |
| Geo | ad.geo_* | Métricas por país |
| Offer | ad.offer_* | Métricas e parâmetros da oferta (payout, cap) |
| Network | ad.network_* | Métricas por rede |
| Período anterior | ad.prev_* | As mesmas métricas para o período anterior (para comparação) |
A lista completa de métricas, janelas de tempo (_1h…_total) e o significado de cada prefixo — na seção Métricas e colunas.
Acessar um campo inexistente (ad.something_wrong) aborta imediatamente a regra com um erro. Confira os nomes na referência dentro do editor.
Pausa
Três funções — por escopo. O anúncio, o adset e a campanha.
| Função | Ação |
|---|---|
pauseAd(duration, reason?) | Pausar o anúncio atual |
pauseAdset({ adsetId, duration, reason? }) | Pausar o adset |
pauseCampaign({ campaignId, duration, reason? }) | Pausar a campanha |
Para pauseAd basta passar a duração como uma string; para o adset e a campanha é obrigatória a forma de objeto com um adsetId / campaignId explícito.
Durações (duration):
| Valor | Significado |
|---|---|
6h / 12h / 24h | Pausar por N horas |
next_day_target_geo | Até o início do dia seguinte no fuso horário do país-alvo |
next_day_ad_account | Até o início do dia seguinte no fuso horário da conta de anúncios |
permanent | Uma pausa permanente |
while_matches | Enquanto a condição da regra se mantiver |
reason é um comentário opcional que vai para o log. Se omitido, o nome da regra é substituído.
Retorno ao trabalho
| Função | Ação |
|---|---|
activateAd(reason?) | Retornar ao trabalho o anúncio atual |
activateAdset({ adsetId, reason? }) | Retornar ao trabalho o adset |
activateCampaign({ campaignId, reason? }) | Retornar ao trabalho a campanha |
Anúncios vizinhos
Dentro de uma regra, você pode olhar outros anúncios do mesmo adset ou campanha — por exemplo, para parar o adset inteiro se apenas um anúncio cair.
| Função | Retorna |
|---|---|
getAd(id) | Um anúncio pelo seu ad_id |
getAdset() | Todos os anúncios do adset do anúncio atual |
getCampaign() | Todos os anúncios da campanha do anúncio atual |
Também estão disponíveis console.log / console.warn / console.error para saída de depuração e skipNextRules() — pular as regras restantes para este anúncio.
Seletores QubixApp (para scripts)
Em scripts de usuário, o objeto QubixApp está disponível — ele seleciona anúncios, adsets e campanhas por condições. Cada elemento selecionado tem as suas próprias estatísticas e métodos de pausa.
| Método | Retorna uma seleção de |
|---|---|
QubixApp.ads() | Anúncios |
QubixApp.adsets() | Adsets |
QubixApp.campaigns() | Campanhas |
Métodos de seleção (encadeados):
| Método | O que faz |
|---|---|
.withCondition(sql) | Filtrar por uma condição |
.filter(fn) | Filtrar com uma função |
.orderBy(field, dir) | Ordenar ('asc' / 'desc') |
.withLimit(n) | Limitar o número de elementos |
.get() | Obter um array de elementos |
.first() | Obter o primeiro elemento |
Métodos de elemento:
| Método | Ação |
|---|---|
.pause({ duration, reason? }) | Pausar |
.activate({ reason? }) | Retornar ao trabalho |
.getStatsFor(period) | Métricas para uma janela ('1h'…'total') |
.getAds() | Anúncios dentro de um adset / campanha |
.getAdsets() | Adsets dentro de uma campanha |
getStatsFor retorna um conjunto de métricas para a janela selecionada: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Contexto do script
Em scripts, o objeto ctx está adicionalmente disponível.
| Campo / método | Finalidade |
|---|---|
ctx.state.get/set/delete/keys | Persistir o estado entre execuções |
ctx.fetch(url, opts?) | Uma requisição HTTP (o host deve estar na allowlist, veja JavaScript nas configurações) |
ctx.now() | A hora atual |
ctx.script | Informações sobre o script atual |
O objeto ctx (incluindo ctx.fetch) existe apenas em scripts — ele não está disponível dentro de regras de pausa automática. E mesmo em scripts, ctx.fetch funciona apenas em uma execução real no servidor: em um teste no navegador as chamadas de rede estão desativadas, então verifique por meio de uma execução real.
Estado compartilhado
Além do seu ctx.state privado, existe um armazenamento compartilhado ctx.state.global, visível para todos os scripts, regras e handlers de sites ao mesmo tempo.
| Método | Ação |
|---|---|
ctx.state.global.get(key) | Ler um valor |
ctx.state.global.keys() | Listar as chaves |
ctx.state.global.set(key, value) | Gravar um valor |
ctx.state.global.delete(key) | Excluir um valor |
Qualquer script ou regra pode ler o armazenamento compartilhado. A escrita (set / delete) é permitida apenas a partir de um script ou regra pertencente a um administrador — caso contrário, a escrita lança um erro. Útil para consultas compartilhadas: o administrador grava um valor uma vez, todos os demais o leem.
ctx.fetch: tempo limite de 10 segundos por padrão (30 no máximo), resposta de até 1 MB, no máximo 20 requisições por execução.sql: uma única consulta retorna no máximo alguns milhares de linhas — o administrador define o limite exato nas configurações. Para seleções grandes, agregue diretamente na consulta.
Os valores exatos dos limites são configurados em Sistema → na aba JavaScript.
sql somente leitura
O template marcado sql\SELECT …`executa uma consulta de dados somente leitura dentro das permissões do proprietário. Ele está disponível **tanto em regras de pausa automática (Britva) quanto em scripts de usuário** — desde que a configuração de sistema correspondente esteja ativada. Em um teste no navegador ele está desativado (comoctx.fetch), então verifique uma regra ou script que use sql` por meio de uma execução real no servidor.
A lista completa de tabelas e colunas que uma consulta pode acessar está em Tabelas para consultas sql.