Escrevendo um script
O editor de scripts é o espaço de trabalho onde você escreve código, o testa com dados reais e configura o agendamento. A tela é dividida em três partes: à esquerda — o assistente de IA, ao centro — o editor de código e o console, à direita — o painel de configurações (metadados, agendamento, estado, histórico de execuções).
Como criar um script
- Abra a seção Scripts e clique em + Criar script. O editor abre com um modelo de código.
- No painel à direita, na seção Metadados, preencha o Nome e a Descrição do script.
- No editor central, escreva o corpo da função
main()— exatamente o que o script deve fazer (veja a seção SDK QubixApp abaixo). - Na seção Agendamento, defina com que frequência o script será executado automaticamente (veja Agendamento). Você pode deixar em branco se for executá-lo apenas manualmente.
- Clique no botão Executar abaixo do editor para testar o script com dados reais — o resultado aparece no console (veja Testando o script).
- Ative o botão Ativo no canto superior direito e clique em Salvar.
Você pode salvar com o atalho de teclado Ctrl + S (no macOS — Cmd + S) direto do editor, sem mover o cursor até o botão.
Assistente de IA
A coluna à esquerda é um chat com o assistente de IA. Descreva a tarefa em palavras simples ("pausar ads com ROAS abaixo de 0.5 e spend acima de $20") e o assistente vai gerar código pronto sobre o SDK Qubix. O botão Inserir em Code abaixo da resposta coloca esse código diretamente no editor.
Abaixo do campo de entrada há prompts de exemplo prontos — clique em qualquer um deles para começar rapidamente.
O assistente também pode sugerir um Nome e uma Descrição para o script a partir do seu código — clique no ícone de IA ao lado desses campos na seção Metadados.
🎬 GIF: uma requisição ao assistente de IA e a inserção do código no editor
SDK QubixApp
Um script é uma função main(), dentro da qual você trabalha com os dados de anúncios através do conjunto de comandos QubixApp. Três níveis estão disponíveis:
QubixApp.ads()— anúncios,QubixApp.adsets()— conjuntos de anúncios,QubixApp.campaigns()— campanhas.
Cada um deles retorna uma seleção que pode ser filtrada e percorrida. A seleção tem métodos:
.withCondition('...')— selecionar por uma condição sobre métricas (por exemplo,'spend_24h > 10 AND roas_24h < 0.5');.orderBy('field', 'desc')— ordenar;.withLimit(n)— limitar a quantidade;.get()— obter um array de itens;.first()— obter o primeiro item.
Todo anúncio, conjunto de anúncios ou campanha tem ações:
.pause({ duration: '24h', reason: '...' })— pausar pelo período especificado;.activate({ reason: '...' })— reativar;.getStatsFor('24h')— obter métricas de um período.
Exemplo básico: pausar anúncios com spend acima de $10 e ROAS abaixo de 0.5 no último dia.
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' })
}
}
Mais trechos de código prontos estão na seção Exemplos de scripts.
O autocompletar funciona no editor: comece a digitar ad. ou QubixApp. — o Qubix vai sugerir os campos e métodos disponíveis com descrições. Assim você não precisa manter a lista de métricas na cabeça.
Consultas ao banco de dados
Além dos anúncios atuais disponíveis através do QubixApp, um script pode ler dados diretamente do banco de dados do Qubix com o comando sql. É uma consulta somente leitura escrita como um tagged template:
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)
Uma consulta retorna um array de linhas; cada linha é um objeto cujas chaves são os nomes das colunas. Os valores que você passa por ${…} são enviados como parâmetros seguros — você não precisa escapar nada à mão, e injeção de SQL não é possível. As consultas são somente leitura: um script pode ler dados, mas não pode alterar nada. O que uma consulta consegue alcançar é limitado aos dados que o seu papel tem permissão para ver.
Estado entre execuções
Um script pode lembrar valores entre execuções através de ctx.state — esta é a sua memória pessoal:
ctx.state.set('key', value)— salvar;ctx.state.get('key')— ler;ctx.state.delete('key')— excluir.
Por exemplo, isso permite lembrar quais anúncios já foram processados e não tocar neles de novo. O conteúdo atual da memória fica visível no painel à direita na seção Estado — de lá também é possível excluir manualmente uma entrada individual.
Requisições a serviços externos
O comando ctx.fetch(url, opts) faz uma requisição HTTP para fora — por exemplo, para enviar uma notificação a um messenger ou para chamar a API de outra pessoa.
As requisições de saída só são permitidas para endereços da allowlist. O administrador a configura em Sistema → a aba JavaScript. Se a lista estiver vazia, as requisições de saída ficam desativadas. Ao tentar alcançar um endereço que não está na lista, o script vai exibir uma dica clara no console.
Agendamento
No painel à direita, a seção Agendamento define quando o script é executado automaticamente. Pode haver vários agendamentos — por exemplo, uma vez por hora e adicionalmente em um horário específico.
- Insira o agendamento no formato cron (por exemplo,
*/5 * * * *— a cada 5 minutos) e clique em +. - Abaixo da linha, o Qubix mostra imediatamente uma explicação em palavras simples — verifique se vocês se entenderam corretamente.
- Para não precisar lembrar a sintaxe do cron, clique no ícone de IA na linha e descreva o agendamento em palavras ("todo dia às 9h") — o Qubix vai preencher a expressão pronta.
Se nenhum agendamento for definido, o script não será executado por conta própria — apenas pelo botão Executar. Para que a execução automática funcione, o botão Ativo deve estar ligado.
Testando o script com o botão "Executar"
Abaixo do editor de código há um console e um botão ▶ Executar. Ele executa o código que está atualmente no editor com dados reais — esta é uma forma segura de testar a lógica sem esperar pelo agendamento. Tudo o que o script produz via console.log aparece no console junto com o horário, o status e a duração da execução.
O botão Executar realiza ações reais. Se o código contiver pause() ou activate(), os anúncios serão de fato pausados ou ativados. Para testar a lógica sem consequências, primeiro comente as linhas com ações e deixe apenas console.log.
O botão Executar fica disponível depois que o script é salvo pela primeira vez.
Histórico de execuções
A seção Execuções no painel à direita mantém o histórico de todas as execuções: horário, status (sucesso, erro, timeout), duração e o número de ações realizadas. Clicar em uma linha expande a saída completa do console daquela execução — útil para descobrir por que o script se comportou de forma inesperada.