Écrire un script
L'éditeur de scripts est l'espace de travail où vous écrivez du code, le testez sur des données réelles et configurez la planification. L'écran est divisé en trois parties : à gauche — l'assistant IA, au centre — l'éditeur de code et la console, à droite — le panneau de réglages (métadonnées, planification, état, historique des exécutions).
Comment créer un script
- Ouvrez la section Scripts et cliquez sur + Créer un script. L'éditeur s'ouvre avec un modèle de code.
- Dans le panneau de droite, dans la section Métadonnées, renseignez le Nom et la Description du script.
- Dans l'éditeur central, écrivez le corps de la fonction
main()— exactement ce que le script doit faire (voir la section SDK QubixApp ci-dessous). - Dans la section Planification, définissez la fréquence d'exécution automatique du script (voir Planification). Vous pouvez la laisser vide si vous comptez l'exécuter uniquement manuellement.
- Cliquez sur le bouton Exécuter sous l'éditeur pour tester le script sur des données réelles — le résultat apparaît dans la console (voir Tester le script).
- Activez le commutateur Actif dans le coin supérieur droit et cliquez sur Enregistrer.
Vous pouvez enregistrer avec le raccourci clavier Ctrl + S (sur macOS — Cmd + S) directement depuis l'éditeur, sans déplacer le curseur vers le bouton.
Assistant IA
La colonne de gauche est un chat avec l'assistant IA. Décrivez la tâche en langage courant (« mettre en pause les ads avec un ROAS inférieur à 0,5 et un spend supérieur à 20 $ »), et l'assistant génère du code prêt à l'emploi pour le SDK Qubix. Le bouton Insérer dans Code sous la réponse place ce code directement dans l'éditeur.
Sous le champ de saisie se trouvent des exemples de prompts prêts à l'emploi — cliquez sur l'un d'eux pour démarrer rapidement.
L'assistant peut aussi proposer un Nom et une Description pour le script à partir de son code — cliquez sur l'icône IA à côté de ces champs dans la section Métadonnées.
🎬 GIF : une requête à l'assistant IA et l'insertion du code dans l'éditeur
SDK QubixApp
Un script est une fonction main(), à l'intérieur de laquelle vous travaillez avec les données publicitaires via l'ensemble de commandes QubixApp. Trois niveaux sont disponibles :
QubixApp.ads()— les ads,QubixApp.adsets()— les ensembles d'ads,QubixApp.campaigns()— les campagnes.
Chacun d'eux renvoie une sélection que l'on peut filtrer et parcourir. La sélection dispose des méthodes :
.withCondition('...')— sélectionner selon une condition sur les métriques (par exemple,'spend_24h > 10 AND roas_24h < 0.5') ;.orderBy('field', 'desc')— trier ;.withLimit(n)— limiter le nombre ;.get()— obtenir un tableau d'éléments ;.first()— obtenir le premier élément.
Chaque ad, ensemble d'ads ou campagne dispose d'actions :
.pause({ duration: '24h', reason: '...' })— mettre en pause pour la période indiquée ;.activate({ reason: '...' })— réactiver ;.getStatsFor('24h')— obtenir les métriques sur une période.
Exemple de base : mettre en pause les ads avec un spend supérieur à 10 $ et un ROAS inférieur à 0,5 sur la dernière journée.
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' })
}
}
D'autres extraits prêts à l'emploi se trouvent dans la section Exemples de scripts.
L'autocomplétion fonctionne dans l'éditeur : commencez à taper ad. ou QubixApp. — Qubix suggère les champs et méthodes disponibles avec leurs descriptions. Ainsi, vous n'avez pas à garder la liste des métriques en tête.
Requêtes à la base de données
Outre les ads actuelles accessibles via QubixApp, un script peut lire des données directement depuis la base de données Qubix avec la commande sql. Il s'agit d'une requête en lecture seule écrite sous forme de template balisé :
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)
Une requête renvoie un tableau de lignes ; chaque ligne est un objet dont les clés sont les noms des colonnes. Les valeurs que vous passez via ${…} sont envoyées en tant que paramètres sécurisés — vous n'échappez rien à la main, et l'injection SQL est impossible. Les requêtes sont en lecture seule : un script peut lire des données mais ne peut rien modifier. Ce qu'une requête peut atteindre est limité aux données que votre rôle est autorisé à voir.
État entre les exécutions
Un script peut mémoriser des valeurs entre les exécutions via ctx.state — c'est sa mémoire personnelle :
ctx.state.set('key', value)— enregistrer ;ctx.state.get('key')— lire ;ctx.state.delete('key')— supprimer.
Par exemple, cela permet de retenir quelles ads ont déjà été traitées et de ne pas y toucher de nouveau. Le contenu actuel de la mémoire est visible dans le panneau de droite, dans la section État — à partir de là, une entrée individuelle peut aussi être supprimée manuellement.
Requêtes vers des services externes
La commande ctx.fetch(url, opts) effectue une requête HTTP vers l'extérieur — par exemple, pour envoyer une notification à une messagerie ou appeler l'API de quelqu'un d'autre.
Les requêtes sortantes ne sont autorisées que vers des adresses figurant dans la liste blanche. L'administrateur la configure dans Système → l'onglet JavaScript. Si la liste est vide, les requêtes sortantes sont désactivées. Lorsqu'on tente d'atteindre une adresse qui n'y figure pas, le script affiche une indication claire dans la console.
Planification
Dans le panneau de droite, la section Planification définit quand le script s'exécute automatiquement. Il peut y avoir plusieurs planifications — par exemple, une fois par heure et, en complément, à un moment précis.
- Saisissez la planification au format cron (par exemple,
*/5 * * * *— toutes les 5 minutes) et cliquez sur +. - Sous la ligne, Qubix affiche aussitôt une explication en langage courant — vérifiez que vous vous êtes bien compris.
- Pour ne pas avoir à mémoriser la syntaxe cron, cliquez sur l'icône IA dans la ligne et décrivez la planification avec des mots (« chaque jour à 9 h ») — Qubix remplit l'expression toute prête.
Si aucune planification n'est définie, le script ne s'exécute pas de lui-même — uniquement via le bouton Exécuter. Pour que l'exécution automatique fonctionne, le commutateur Actif doit être activé.
Tester le script avec le bouton « Exécuter »
Sous l'éditeur de code se trouvent une console et un bouton ▶ Exécuter. Il exécute le code actuellement présent dans l'éditeur sur des données réelles — c'est un moyen sûr de tester la logique sans attendre la planification. Tout ce que le script affiche via console.log apparaît dans la console, avec l'heure d'exécution, le statut et la durée.
Le bouton Exécuter effectue des actions réelles. Si le code contient pause() ou activate(), les ads seront réellement mises en pause ou réactivées. Pour tester la logique sans conséquences, commentez d'abord les lignes comportant des actions et ne laissez que console.log.
Le bouton Exécuter devient disponible une fois le script enregistré pour la première fois.
Historique des exécutions
La section Exécutions du panneau de droite conserve l'historique de toutes les exécutions : heure, statut (succès, erreur, timeout), durée et nombre d'actions effectuées. Cliquer sur une ligne déploie l'intégralité de la sortie console de cette exécution — pratique pour comprendre pourquoi le script s'est comporté de façon inattendue.