SDK des règles automatiques et des scripts
Une référence de ce qui est disponible à l'intérieur du code d'une règle de mise en pause automatique et d'un script utilisateur : les champs de l'objet ad, les fonctions de mise en pause et de reprise, et les sélecteurs pour choisir les annonces. Les libellés de tous les champs accompagnés de leurs descriptions sont également disponibles directement dans l'éditeur de règles — dans le panneau latéral Référence des clés ad.* (recherche par nom et description).
Il s'agit du Server SDK — des commandes qui s'exécutent sur le serveur Qubix, par opposition au Browser SDK qui s'exécute dans le navigateur du visiteur. Le Server SDK est synchrone : sql, ctx.fetch et l'état retournent une valeur directement — sans await ni Promises.
L'objet ad
Dans une règle de mise en pause automatique, vous recevez un seul objet ad — il s'agit de l'annonce pour laquelle la vérification est exécutée. À travers lui, vous lisez toutes les métriques et tous les attributs. Tous les champs disponibles sont regroupés par portée.
| Groupe | Préfixe de champ | Ce qu'il contient |
|---|---|---|
| Annonce | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Métriques et attributs de l'annonce elle-même |
| Créa | ad.creo_* | Métriques par créa (toutes les annonces utilisant cette créa) |
| Geo | ad.geo_* | Métriques par pays |
| Offre | ad.offer_* | Métriques et paramètres de l'offre (payout, cap) |
| Réseau | ad.network_* | Métriques par réseau |
| Période précédente | ad.prev_* | Les mêmes métriques pour la période précédente (pour comparaison) |
La liste complète des métriques, des fenêtres temporelles (_1h…_total) et la signification de chaque préfixe — dans la section Métriques et colonnes.
Accéder à un champ inexistant (ad.something_wrong) interrompt immédiatement la règle avec une erreur. Vérifiez les noms par rapport à la référence dans l'éditeur.
Mise en pause
Trois fonctions — par portée. L'annonce, l'ensemble de publicités et la campagne.
| Fonction | Action |
|---|---|
pauseAd(duration, reason?) | Mettre en pause l'annonce courante |
pauseAdset({ adsetId, duration, reason? }) | Mettre en pause l'ensemble de publicités |
pauseCampaign({ campaignId, duration, reason? }) | Mettre en pause la campagne |
Pour pauseAd, il suffit de passer la durée sous forme de chaîne ; pour l'ensemble de publicités et la campagne, la forme objet avec un adsetId / campaignId explicite est requise.
Durées (duration) :
| Valeur | Signification |
|---|---|
6h / 12h / 24h | Mettre en pause pendant N heures |
next_day_target_geo | Jusqu'au début du jour suivant dans l'heure du pays cible |
next_day_ad_account | Jusqu'au début du jour suivant dans l'heure du compte publicitaire |
permanent | Une mise en pause permanente |
while_matches | Tant que la condition de la règle est vérifiée |
reason est un commentaire facultatif qui figure dans le journal. S'il est omis, le nom de la règle est utilisé à la place.
Reprise
| Fonction | Action |
|---|---|
activateAd(reason?) | Reprendre l'annonce courante |
activateAdset({ adsetId, reason? }) | Reprendre l'ensemble de publicités |
activateCampaign({ campaignId, reason? }) | Reprendre la campagne |
Annonces voisines
À l'intérieur d'une règle, vous pouvez consulter d'autres annonces du même ensemble de publicités ou de la même campagne — par exemple, pour arrêter tout l'ensemble de publicités si une seule annonce a chuté.
| Fonction | Renvoie |
|---|---|
getAd(id) | Une annonce par son ad_id |
getAdset() | Toutes les annonces de l'ensemble de publicités de l'annonce courante |
getCampaign() | Toutes les annonces de la campagne de l'annonce courante |
Sont également disponibles console.log / console.warn / console.error pour la sortie de débogage et skipNextRules() — ignorer les règles restantes pour cette annonce.
Sélecteurs QubixApp (pour les scripts)
Dans les scripts utilisateur, l'objet QubixApp est disponible — il sélectionne les annonces, les ensembles de publicités et les campagnes selon des conditions. Chaque élément sélectionné possède ses propres statistiques et méthodes de mise en pause.
| Méthode | Renvoie une sélection de |
|---|---|
QubixApp.ads() | Annonces |
QubixApp.adsets() | Ensembles de publicités |
QubixApp.campaigns() | Campagnes |
Méthodes de sélection (chaînables) :
| Méthode | Ce qu'elle fait |
|---|---|
.withCondition(sql) | Filtrer par une condition |
.filter(fn) | Filtrer avec une fonction |
.orderBy(field, dir) | Trier ('asc' / 'desc') |
.withLimit(n) | Limiter le nombre d'éléments |
.get() | Obtenir un tableau d'éléments |
.first() | Obtenir le premier élément |
Méthodes d'élément :
| Méthode | Action |
|---|---|
.pause({ duration, reason? }) | Mettre en pause |
.activate({ reason? }) | Reprendre |
.getStatsFor(period) | Métriques pour une fenêtre ('1h'…'total') |
.getAds() | Annonces à l'intérieur d'un ensemble de publicités / d'une campagne |
.getAdsets() | Ensembles de publicités à l'intérieur d'une campagne |
getStatsFor renvoie un ensemble de métriques pour la fenêtre sélectionnée : spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Contexte du script
Dans les scripts, l'objet ctx est en plus disponible.
| Champ / méthode | Rôle |
|---|---|
ctx.state.get/set/delete/keys | Persistance de l'état entre les exécutions |
ctx.fetch(url, opts?) | Une requête HTTP (l'hôte doit figurer dans la liste d'autorisation, voir JavaScript dans les paramètres) |
ctx.now() | L'heure actuelle |
ctx.script | Informations sur le script courant |
L'objet ctx (y compris ctx.fetch) n'existe que dans les scripts — il n'est pas disponible à l'intérieur des règles de mise en pause automatique. Et même dans les scripts, ctx.fetch ne fonctionne que lors d'une exécution réelle sur le serveur : lors d'une exécution de test dans le navigateur, les appels réseau sont désactivés, vérifiez donc via une exécution réelle.
État partagé
En plus de son ctx.state privé, il existe un store partagé ctx.state.global, visible par chaque script, règle et gestionnaire de site simultanément.
| Méthode | Action |
|---|---|
ctx.state.global.get(key) | Lire une valeur |
ctx.state.global.keys() | Lister les clés |
ctx.state.global.set(key, value) | Écrire une valeur |
ctx.state.global.delete(key) | Supprimer une valeur |
Tout script ou règle peut lire le store partagé. L'écriture (set / delete) n'est autorisée que depuis un script ou une règle appartenant à un administrateur — dans le cas contraire, l'écriture génère une erreur. Pratique pour les données de référence partagées : l'administrateur écrit une valeur une fois, tous les autres la lisent.
ctx.fetch: un délai d'expiration de 10 secondes par défaut (30 au maximum), une réponse jusqu'à 1 Mo, pas plus de 20 requêtes par exécution.sql: une seule requête renvoie au maximum quelques milliers de lignes — l'administrateur définit le plafond exact dans les paramètres. Pour les sélections volumineuses, agrégez directement dans la requête.
Les valeurs exactes des limites sont configurées dans Système → l'onglet JavaScript.
sql en lecture seule
Le template balisé sql\SELECT …`exécute une requête de données en lecture seule dans les limites des permissions du propriétaire. Il est disponible **à la fois dans les règles de mise en pause automatique (Britva) et dans les scripts utilisateur** — à condition que le paramètre système correspondant soit activé. Lors d'une exécution de test dans le navigateur, il est désactivé (commectx.fetch), vérifiez donc une règle ou un script utilisant sql` via une exécution réelle sur le serveur.
La liste complète des tables et colonnes accessibles par une requête est disponible dans Tables pour les requêtes sql.