Trackily Docs

Créer et gérer des règles Automizer

Tout sur la création de règles : UI, MCP, schéma JSON, validation, et 3 exemples worked complets (auto-pause, auto-scale, anti-fraude).

Créer une règle

À quoi ça sert

Une règle Automizer = une condition + une action. Le moteur (automizer.js:16) tourne en boucle toutes les 60 secondes, charge les règles actives qui sont dues d'être re-évaluées, et trigger les actions si toutes les conditions sont vraies.

Cette page t'explique :

  1. Le schéma JSON complet (champs, validation, valeurs acceptées)
  2. Comment créer une règle via l'UI
  3. Comment créer une règle via MCP (create_automizer_rule)
  4. Trois exemples worked en détail
  5. Update / pause / delete

Le schéma

La table automation_rules (voir database.js:244) :

CREATE TABLE automation_rules (
  id                      SERIAL PRIMARY KEY,
  name                    TEXT NOT NULL,
  campaign_id             INTEGER REFERENCES campaigns(id) ON DELETE CASCADE,
  product_id              INTEGER REFERENCES products(id) ON DELETE CASCADE,
  conditions              JSONB NOT NULL DEFAULT '[]',
  actions                 JSONB NOT NULL DEFAULT '[]',
  is_active               BOOLEAN DEFAULT true,
  check_interval_minutes  INTEGER DEFAULT 5,
  last_checked            TIMESTAMPTZ,
  last_triggered          TIMESTAMPTZ,
  trigger_count           INTEGER DEFAULT 0,
  created_at              TIMESTAMPTZ DEFAULT NOW()
);

Champs

Field Type Required Notes
name string ✅ Pour identifier la règle dans l'UI et les logs
campaign_id int / null ❌ Scope à une campagne. Mutex avec product_id. Sans → règle globale.
product_id int / null ❌ Scope à un produit (commerce natif). Mutex avec campaign_id.
conditions array ✅ ≥1 condition. AND entre elles.
actions array ✅ ≥1 action. Exécutées dans l'ordre.
check_interval_minutes int ❌ Défaut 5. Min 1. Throttle d'évaluation.
is_active bool ❌ Défaut true. Si false → la règle n'est jamais évaluée.

Schéma d'une condition

{
  "metric": "cost",          // string — voir [Conditions](/docs/automizer/conditions) pour la liste
  "operator": ">",           // string — symboles (> < >= <= = !=) ou aliases (gt lt gte lte eq neq)
  "value": 20,               // number (entier ou float)
  "window": "24h"            // string — "1h", "2h", "6h", "12h", "24h", "3d", "7d"
}

Schéma d'une action

{
  "type": "pause_campaign",         // ou "meta_pause_campaign", "send_notification", etc.
  // ...champs spécifiques au type
}

Voir la liste exhaustive des actions dans l'index, ou automizer.js:139.

Créer une règle via l'UI

  1. Sidebar → Automizer → bouton + New Rule
  2. Name — un nom descriptif (sera affiché dans les notifs et logs)
  3. Scope — choisis "Global", "Campaign", ou "Product". Si Campaign/Product, sélectionne dans le dropdown
  4. Check interval — fréquence (1, 5, 10, 30 min)
  5. Conditions — clique "Add condition" pour chaque. Pour chacune, sélectionne metric / operator / value / window
  6. Actions — clique "Add action" pour chaque. Le formulaire s'adapte au type d'action
  7. Active on save — coché par défaut. Décoche pour créer en pause
  8. Save

Liste règles

L'UI valide en temps réel — si tu mets un metric inconnu, tu auras un warning (mais ça créera quand même la règle, parce que le moteur peut être étendu plus tard).

Tu peux aussi partir d'un preset : Trackily ship des règles toutes faites (auto-pause low ROI, scale winners, fraud guard…). Voir l'onglet "Presets" dans le modal de création.

Presets

Créer une règle via MCP

Le tool s'appelle create_automizer_rule (voir autopilot-actions.js:1045). Il est two-step : tu appelles d'abord sans confirm_token, l'agent te retourne un preview + un token, tu rappelles avec le token pour confirmer.

Schéma input

{
  "name": "string (≥1 char)",
  "conditions": [
    {
      "metric": "clicks | conversions | revenue | cost | profit | roi | cr | epc | bot_rate",
      "operator": "> | < | >= | <= | = | != | gt | lt | gte | lte | eq | neq",
      "value": "number",
      "window": "1h | 6h | 24h | 7d"
    }
  ],
  "actions": [{ "type": "pause_campaign" }],
  "check_interval_minutes": "integer ≥ 1, default 5",
  "is_active": "boolean, default true",
  "campaign_id": "integer (optional)",
  "product_id": "integer (optional)",
  "confirm_token": "string (returned by first call)"
}

Étape 1 — preview

{
  "name": "create_automizer_rule",
  "arguments": {
    "name": "Auto-pause low ROI 6h",
    "campaign_id": 42,
    "conditions": [
      { "metric": "roi", "operator": "<", "value": -40, "window": "6h" },
      { "metric": "clicks", "operator": ">=", "value": 100, "window": "6h" }
    ],
    "actions": [{ "type": "pause_campaign" }],
    "check_interval_minutes": 5
  }
}

Réponse :

{
  "summary": "Create Automizer rule \"Auto-pause low ROI 6h\" — checked every 5 min, active on save, scoped to campaign #42.",
  "preview": { "name": "...", "conditions": [...], "actions": [...] },
  "token": "tk_a1b2c3d4..."
}

Étape 2 — confirm

{
  "name": "create_automizer_rule",
  "arguments": {
    "name": "Auto-pause low ROI 6h",
    "campaign_id": 42,
    "conditions": [
      { "metric": "roi", "operator": "<", "value": -40, "window": "6h" },
      { "metric": "clicks", "operator": ">=", "value": 100, "window": "6h" }
    ],
    "actions": [{ "type": "pause_campaign" }],
    "check_interval_minutes": 5,
    "confirm_token": "tk_a1b2c3d4..."
  }
}

Réponse :

{
  "tool": "create_automizer_rule",
  "message": "Rule created.",
  "details": {
    "id": 17,
    "name": "Auto-pause low ROI 6h",
    "is_active": true,
    "check_interval_minutes": 5,
    "campaign_id": 42
  }
}

Validation

Le tool fait plusieurs vérifs avant de toucher la DB (voir autopilot-actions.js:697) :

  • conditions doit être un array non vide (le tool accepte aussi {$and: [...]}, {and: [...]}, {conditions: [...]} ou un dict keyed par metric, et les normalise automatiquement)
  • Chaque condition doit avoir metric, operator, value
  • operator doit être dans OPERATOR_ALIASES (symboles ou word aliases)
  • value doit être un nombre fini
  • metric doit être dans KNOWN_METRICS — sinon warning (la règle est créée mais avec un avertissement)
  • actions doit être un array non vide (un seul objet est auto-wrapé en array)
  • check_interval_minutes ≥ 1
  • Si campaign_id fourni → la campagne doit exister

Si une vérif rate, tu reçois une erreur explicite genre :

conditions[0].value must be a finite number (got "20$")

Exemple 1 — Auto-pause low ROI

Cas réel : tu lances une nouvelle campagne et tu veux qu'elle se pause toute seule si elle leak la nuit pendant que tu dors.

Règle : pause la campagne 42 si elle a dépensé > $20 ET fait < 3 conversions sur les dernières 24h.

Via MCP

{
  "name": "create_automizer_rule",
  "arguments": {
    "name": "Safety net — pause if cost>20 & conv<3",
    "campaign_id": 42,
    "conditions": [
      { "metric": "cost", "operator": ">", "value": 20, "window": "24h" },
      { "metric": "conversions", "operator": "<", "value": 3, "window": "24h" }
    ],
    "actions": [
      { "type": "pause_campaign" },
      {
        "type": "send_notification",
        "title": "Campaign auto-paused",
        "message": "Campaign #42 leaked: $20 spent, <3 conversions"
      }
    ],
    "check_interval_minutes": 10
  }
}

Trace d'exécution

  1. La boucle 60s charge la règle (is_active=true, last_checked > 10 min ago)
  2. getStatsForTimeWindow(42, "24h") retourne { cost: 23.45, conversions: 1, ... }
  3. Cond 1 : 23.45 > 20 ✅
  4. Cond 2 : 1 < 3 ✅
  5. Toutes met → exécute actions :
    • pause_campaign → UPDATE campaigns SET is_active=false WHERE id=42
    • send_notification → push notif via canal configuré
  6. INSERT INTO automation_log avec snapshot
  7. UPDATE last_triggered = NOW(), trigger_count++
  8. Au prochain tick (60s plus tard), la règle est skip parce que last_checked est trop récent (10 min throttle)

Pourquoi le check_interval_minutes: 10

Plus haut que le défaut de 5 min, parce que :

  • Tu veux laisser la régie ingérer les conversions postback (latence Meta : 30-60 min)
  • Tu veux éviter de pauser sur un creux temporaire de 10 min

Exemple 2 — Auto-scale +20% les top performers

Cas réel : campagne Meta qui fait ROAS > 2.5 sur les dernières 24h → augmente le daily budget de +20% pour profiter de la machine.

Règle : scope campagne 42, ROI > 150% ET ≥ 10 conversions → augmenter daily budget Meta de 20%.

Via MCP

{
  "name": "Scale winners +20%",
  "arguments": {
    "name": "Scale Meta winners +20%",
    "campaign_id": 42,
    "conditions": [
      { "metric": "roi", "operator": ">", "value": 150, "window": "24h" },
      { "metric": "conversions", "operator": ">=", "value": 10, "window": "24h" }
    ],
    "actions": [
      {
        "type": "meta_change_daily_budget",
        "value": 60
      }
    ],
    "check_interval_minutes": 60
  }
}

Note : meta_change_daily_budget attend la nouvelle valeur en USD (sera convertie en cents par Trackily). Si tu veux +20% du budget actuel, tu dois soit pre-calculer (lire le budget actuel via list_source_campaigns, calculer, push), soit utiliser une action en pourcentage relatif (roadmap — ouvre une issue si tu en as besoin).

Trace d'exécution

  1. Boucle 60s, règle due (intervalle 60 min)
  2. Stats 24h : roi=187.5, conversions=14
  3. Toutes met
  4. meta_change_daily_budget :
    • Résout les external_campaign_ids de la campagne 42
    • Pour chaque ID Meta, appelle POST /<meta_id> avec { daily_budget: 6000 } (60 USD = 6000 cents)
    • Log success/error par campaign
  5. automation_log avec actions_taken: [{ type: "meta_change_daily_budget", meta_updates: [{ meta_id: "23847...", status: "ok" }] }]
  6. Notif rule_triggered envoyée

Précaution

Une règle de scale qui trigger 24x par jour (1x/h) peut faire 6.2x ton budget en un jour si elle re-trigger non-stop ((1.2)^24 ≈ 79). Mets check_interval_minutes ≥ 360 (6h) pour les règles de scale, et une condition de garde-fou genre cost < $X pour limiter le scale max.

Exemple 3 — Auto-pause sources noyées de bots

Cas réel : tu pushes du trafic push d'une source qui se met à envoyer 50% de bots du jour au lendemain (typique : reseller qui re-vend du fraudulent inventory).

Règle : globale (toutes les campagnes), si bot_rate > 30% ET ≥ 500 clicks sur 6h → pause campagne + notif urgente.

Via MCP

{
  "name": "create_automizer_rule",
  "arguments": {
    "name": "Bot rate > 30% — emergency pause",
    "conditions": [
      { "metric": "bot_rate", "operator": ">", "value": 30, "window": "6h" },
      { "metric": "clicks", "operator": ">=", "value": 500, "window": "6h" }
    ],
    "actions": [
      { "type": "pause_campaign" },
      {
        "type": "send_notification",
        "title": "🚨 Bot attack detected",
        "message": "Campaign auto-paused: bot rate exceeded 30% over 6h"
      }
    ],
    "check_interval_minutes": 5
  }
}

Note : sans campaign_id, la règle est "globale" — mais l'action pause_campaign a besoin d'un campaign_id. Pour vraiment faire ça pour TOUTES les campagnes, il faut créer N règles (une par campagne). Sur la roadmap : règles vraiment globales qui itèrent sur toutes les campagnes actives.

Pourquoi clicks >= 500

Sans ce garde-fou, une campagne qui a fait 3 clicks dont 1 bot a un bot_rate = 33% → trigger immédiat sur du bruit statistique. 500 clicks min = signal solide.

Combo avec le cloaking

Cette règle gère le cas où les bots passent à travers le cloaking. Couplée à un workflow de cloaking qui filtre déjà 80%+ des bots, c'est ta double sécurité.

Update une règle existante

Via UI

Click sur la règle dans la liste → modifie les conditions / actions / interval → Save.

Via MCP

{
  "name": "update_automizer_rule",
  "arguments": {
    "id": 17,
    "conditions": [
      { "metric": "roi", "operator": "<", "value": -50, "window": "6h" }
    ]
  }
}

C'est un partial update — seuls les champs fournis sont changés. Two-step avec confirm_token aussi.

Pause / Resume

Via UI

Toggle "Active" sur la ligne.

Via MCP

{ "name": "pause_automizer_rule", "arguments": { "id": 17 } }
{ "name": "resume_automizer_rule", "arguments": { "id": 17 } }

Tier 1 — pas de confirm_token requis (pause/resume sont réversibles).

Delete

Via UI

Click sur la règle → bouton "Delete". Confirme.

Via MCP

{
  "name": "delete_automizer_rule",
  "arguments": { "id": 17 }
}

Two-step avec confirm_token. Les rows automation_log associées sont préservées (le rule_name est dénormalisé).

Voir les logs d'une règle

UI : click sur la règle → onglet "Logs". Liste paginée des déclenchements avec le snapshot des conditions et le résultat des actions.

DB direct :

SELECT created_at, conditions_met, actions_taken
FROM automation_log
WHERE rule_id = 17
ORDER BY created_at DESC
LIMIT 50;

Erreurs courantes

  • "conditions must be a non-empty array" → tu as envoyé null, un object, ou un array vide. Le tool accepte aussi {$and:[...]} qu'il convertit, mais tu dois bien envoyer 1+ condition.
  • "Unsupported operator 'gt='" → typo. Liste valide : > < >= <= = != gt lt gte lte eq neq + variantes.
  • "conditions[0].value must be a finite number" → tu as envoyé "20$" (string avec $). Envoie 20 (number).
  • "Source X is not a Meta source" → ton action meta_* cible une campagne dont la source linkée n'est pas Meta. Vérifie campaigns.source_id → traffic_sources.name doit contenir "meta" ou "facebook".
  • "No external campaign IDs linked" → la campagne n'a pas de mapping vers les campagnes externes (Meta ID). Va dans la campagne → section "External Campaign IDs" → ajoute-les.
  • Règle qui ne trigger jamais → vérifie is_active = true, vérifie que la métrique existe pour la window (ex : roi sur 1h alors que tu n'as eu aucun click sur 1h → roi=0, donc roi < -40 est faux).
  • Règle qui trigger en boucle → l'action ne change pas l'état observé. Ex : tu pauses la campagne mais la window est 7d, donc les clicks/cost restent dans le calcul pendant 7 jours → re-trigger non-stop. Solution : window plus courte ou ajouter une cond is_active = true (en roadmap).

Voir aussi