Écrire et déboguer CQL
CQL est le langage de requête pseudo-naturel de Croct. La même syntaxe d'expression alimente les audiences, l'évaluation en temps réel depuis les SDK et l'API HTTP, ainsi que les valeurs de contenu dynamiques. Tout ce qui se trouve ici provient de docs.croct.com ; lorsqu'un point n'est pas couvert, consultez la documentation en direct (en bas de ce fichier) au lieu de deviner.
Flux de travail
- Identifiez où la requête s'exécute : audience (doit être booléenne),
evaluate/API (toute valeur JSON, 500 caractères maximum), ou valeur dynamique (le résultat doit correspondre au type d'attribut, sinondefault). - Choisissez la source de données : contexte actuel (
page,panier,emplacement,campagne,appareil), profil stocké (de l'utilisateur ...,statistiques de l'utilisateur), session (de la session ...), ou historique (l'utilisateur a ...expressions d'événement, plan Scale). - Vérifiez que les données sont collectées : tout ce qui est marqué intégration requise (attributs de profil, panier, centres d'intérêt, objectifs, état de connexion) ne correspond jamais à moins que l'application ne l'envoie.
- Écrivez avec l'anti-sèche ci-dessous ; recherchez les propriétés exactes dans context-and-data-types.md.
- Passez en revue la liste des pièges, puis testez avec
croct.evaluate()ou l'estimateur du tableau de bord.
Anti-sèche
// Les styles naturel, technique et mixte sont interchangeables
le score de l'utilisateur est supérieur à 90
user.score > 90
le score de l'utilisateur > 90
| Besoin | Syntaxe |
|---|---|
| Propriété | de l'utilisateur l'adresse de la ville, de l'utilisateur les statistiques des commandes, la propriété ville de l'adresse de l'utilisateur, user.address.city |
| Clé étrange / indice | page.query['code-coupon'], liste[0], (centres d'intérêt de l'utilisateur)[0] |
| Sélecteurs | panier.articles[1er], [:premier], [:dernier(2)], articles[*].prix, données[...].prix |
| Littéraux | null, true, 42, 3.14 (décimal), 3.14f, 51%, "str", 'raw', ~/re/i, [1, 2], ["k": "v"] |
| Dates | Pas de littéral : "2026-01-01" as date, "2026-01-01T12:00" as datetime ; today + 1 day |
| Logique | et ou non (&& || !) ; et se lie plus fortement que ou |
| Comparaison | == != > >= < <= ; 1 < x < 3 ; est égal à X en ignorant la casse |
| Raccourci littéral | X est "valeur", X n'est pas 0 (le côté droit doit être un littéral) |
| Chaînes | commence par, finit par, correspond à "sous" / correspond à ~/re/i (sensible à la casse), est comme "sous" (insensible à la casse) |
| Collections | contient X, X est dans [..], contient tous les [..], contient soit [..], ne contient ni [..] |
| Présence | est défini / est connu, est vide |
| Utilisateur/session | l'utilisateur revient, l'utilisateur est anonyme, l'utilisateur est identifié, la session commence |
| Dates | est avant, est après, est à "12:00", est entre A et B [exclusif], le jour de la semaine d'aujourd'hui est "lundi" |
| Quantifieurs | certains x dans C satisfont P, chaque, aucun, pas tous, au moins 2 de tous [distincts] x dans C satisfont P |
| Macros | compte de, somme de, moyenne de, min de, max de, premier de, dernier de, clés de, longueur de, nombre de jours entre A et B, ce mois-ci |
| Modificateurs | en nombre, arrondi [vers le bas], en titre, trié par ordre décroissant, sans doublons, en remplaçant "a" par "b", aujourd'hui à "12:00" |
| Valeur de repli | le nom de l'utilisateur ou alors "Anonyme" (??) |
| Conditionnel | "A" si condition sinon "B", condition ? "A" : "B" |
| Variables | soit commandes = les statistiques de l'utilisateur des commandes ; commandes >= 5 |
| Événements (Scale) | l'utilisateur a <événement> [avec valeur de propriété] [au moins N fois] [au cours des 7 derniers jours] |
| Commentaires | // ligne, # ligne, /* bloc */ |
Les mots-clés et identifiants sont insensibles à la casse ; les littéraux de chaîne sont sensibles à la casse.
Contexte en un coup d'œil
| Variable | Propriétés courantes |
|---|---|
user | id, firstName, email, age, company, jobTitle, interests, activities, stats' sessions, stats' orders, tout attribut personnalisé |
session | start, duration, landingPage, referrer, stats' pageviews, stats' orders, audiences, experiences, experiments, attributs personnalisés |
page (web) | title, url, path, query, anchor, referrer |
location | continentCode, countryCode, countryName, stateCode/regionCode (alias de state's code), stateName, cityName, timeZone, tags |
device / browser | category (desktop, tablet, mobile, bot, ...), vendor, name, os ; browser's name, type |
campaign | name, source, medium, content, term (UTM) |
cart | stage (browsing, shopping, checkout), items, total, subtotal, coupon, discount |
context | timeZone, attributs passés lors de l'évaluation |
now, today, yesterday, tomorrow | weekday, day, month, year, hour... |
Patrons les plus utiles
l'utilisateur revient
l'utilisateur ne revient pas
la session commence
la catégorie de l'appareil est "mobile"
la catégorie de l'appareil n'est pas "bot"
le code pays de l'emplacement est "US"
le code de l'état de l'emplacement est dans ["NY", "CA"]
le nom de la ville de l'emplacement est "New York" et le jour de la semaine d'aujourd'hui est "lundi"
la source de la campagne est "google" et le support de la campagne est "cpc"
le nom de la campagne correspond à "sale"
le chemin de la page est dans ["/pricing", "/plans"]
la newsletter de la requête de la page est "daily-news"
page.query['code-coupon'] est défini
le référent de la session correspond à "google"
la page d'atterrissage de la session commence par "https://example.com/promo"
la durée de la session > 5 minutes et les commandes des statistiques de la session est 0
les centres d'intérêt de l'utilisateur contiennent soit ["marketing", "sales"]
l'âge de l'utilisateur est entre 18 et 30
les commandes des statistiques de l'utilisateur est 0
le plan de l'utilisateur est "premium"
l'étape du panier est "checkout" et le total du panier est supérieur à 100
certain article dans les articles du panier satisfait la marque de l'article est "Apple"
(aucun article dans les articles du panier ne satisfait le nom de l'article est comme "smartphone") et l'utilisateur revient
l'utilisateur a abandonné un panier au moins 2 fois
l'utilisateur a consulté un produit avec la catégorie "Chaussures" au cours des 7 derniers jours
l'utilisateur a atteint l'objectif "demo-requested" la dernière session
le prénom de l'utilisateur ou alors "là"
Plus par cas d'utilisation (campagne, emplacement, technologie, session, profil, panier, commandes, requêtes de valeur) : references/recipes.md.
Évaluer depuis le code
import croct from '@croct/plug';
const revient = await croct.evaluate<boolean>("l'utilisateur revient").catch(() => false);
const dansListe = await croct.evaluate<boolean>(
"les pays du contexte incluent le nom du pays de l'emplacement",
{attributes: {countries: ['États-Unis', 'Canada']}}, // lu comme `pays du contexte`
);
Serveur Next.js : await evaluate(requête) ou await cql`le persona de l'utilisateur est dans ${roles}` depuis @croct/plug-next/server. React : useEvaluation(requête). HTTP : POST https://api.croct.io/client/web/evaluate avec {"query": "..."}. Détails, limites d'attributs, valeurs dynamiques et estimation : references/evaluation.md.
Pièges et débogage
| Symptôme | Cause probable | Correctif |
|---|---|---|
Erreur de syntaxe sur x est y | Le raccourci est nécessite un littéral à droite | x est égal à y ou x == y |
Erreur de syntaxe sur emplacement ville est "Berlin" | Accesseur manquant : mots nus entre une variable et sa propriété | le nom de la ville de l'emplacement, la propriété nom de la ville de l'emplacement, ou location.cityName |
Erreur en comparant "1" > 0 ou début de session > "2026-01-01" | Les opérateurs relationnels ne convertissent jamais les types | Convertir : "1" en nombre > 0, ... > "2026-01-01" en datetime, ou utiliser est après |
| L'emplacement/le code ne correspond jamais | Mauvaise casse : les codes sont en majuscules ("US", "NA", "CA") et les chaînes sont sensibles à la casse | Utiliser des majuscules, est comme, est égal à ... en ignorant la casse, ou ~/.../i |
correspond à "Solde" ne trouve pas "solde" | correspond à, commence par, finit par sont sensibles à la casse | est comme "solde" ou correspond à ~/solde/i |
| Un quantifieur absorbe la condition suivante | Le prédicat du quantifieur s'étend jusqu'à la fin | Mettre tout le quantifieur entre parenthèses |
a ou b et c se comporte bizarrement | et se lie plus fortement que ou | Ajouter des parenthèses |
| Le résultat conditionnel est multiplié de manière incorrecte | Les conditionnels sont gourmands | (A si condition sinon B) * prix |
| La condition de profil/panier/intérêt n'est jamais vraie | Données nécessitant une intégration non envoyées | Suivre l'événement ou définir l'attribut (voir la compétence croct-track-events) |
À la fois X est supérieur à 30 et X n'est pas supérieur à 30 sont faux | Valeur non définie : la tolérance d'erreur booléenne donne faux | Utiliser X est défini et ..., ou X ou alors 0 |
l'utilisateur est identifié toujours faux | Événements de connexion/déconnexion non suivis | Les suivre ; sinon les utilisateurs sont toujours anonymes |
Erreurs sur panier.articles[2e], premier de, moyenne de, min de | Élément manquant ou collection vide | Ajouter ou alors null / ou alors 0 |
ne contient aucun de [] vs ne contient ni [] | Côté droit vide : aucun faux, ni vrai | Utiliser ne contient ni pour "aucun chevauchement" |
Erreur en mélangeant 's avec des crochets | La possession/le possessif plus les crochets nécessitent des parenthèses | (les articles du panier)[1er] ou notation par point panier.articles[*] |
| Expressions d'événement indisponibles | C'est une fonctionnalité du plan Scale | Utiliser les statistiques de profil/session lorsque possible (les commandes des statistiques de l'utilisateur) |
| "Estimation indisponible" | Utilise page, contexte actuel, ou maintenant/aujourd'hui/hier | Attendu ; l'audience fonctionne toujours à l'exécution |
| Erreur de plage | Les plages .. ont un maximum de 30 éléments | Réduire la plage |
| Erreur de nom de variable/paramètre | Les variables ne peuvent pas être redéfinies ; les noms doivent être des identifiants | Renommer ; éviter les mots réservés (utilisateur, page) et les mots génériques |
À faire :
- Privilégier
est égal à,est supérieur àexplicites dans les audiences partagées avec des non-développeurs ; utiliser le style technique lorsqu'il se lit mieux. - Protéger les données optionnelles avec
est définiouou alors. - Placer les conditions peu coûteuses en premier dans les chaînes
et(le court-circuit ignore le reste). - Utiliser
contient soit/ne contient niplutôt que de niercontient tous/ne contient aucun.
À ne pas faire :
- N'inventez pas de tests, de variables ou de formulations d'événements. Des exemples comme
l'utilisateur est nouveauoul'utilisateur a effectué un achatapparaissent dans la prose de la documentation mais ne sont pas des constructions documentées ; utilisezl'utilisateur ne revient pasetles commandes des statistiques de l'utilisateur n'est pas 0(oul'utilisateur a passé une commande). - Ne comparez pas
le nom du pays de l'emplacementavec un code ; utilisezcountryCodepour"US". - Ne vous fiez pas à la conversion implicite de date dans l'arithmétique :
"2021-01-01" en date + 1 jour.
Références
| Fichier | Lire quand |
|---|---|
| references/syntax.md | Règles lexicales, let, fonctions, littéraux, accesseurs et sélecteurs, table de précédence, conditionnels, durées |
| references/context-and-data-types.md | Chaque variable et propriété, indicateurs de disponibilité, énumérations (catégorie d'appareil, étape de panier, continent, balises d'emplacement), conversions |
| references/expressions.md | Tous les tests, opérateurs, tolérance d'erreur, quantifieurs, macros, modificateurs |
| references/events.md | Expressions d'événement, opérateurs de critères, quantifieurs de comptage, fenêtres de temps, exigences de suivi |
| references/evaluation.md | SDK evaluate / cql / hooks, API Evaluation, attributs de contexte, valeurs dynamiques, estimation d'audience |
| references/recipes.md | Audiences prêtes à l'emploi et requêtes de valeur par cas d'utilisation |
Compétences connexes : croct-integrate-sdk (configuration SDK), croct-track-events (envoi des événements et attributs lus par les requêtes), croct-use-api (API HTTP), croct-model-content (valeurs dynamiques dans les définitions de contenu), croct-personalize-and-test (expériences et expérimentations qui utilisent les audiences), croct-use-croct (concepts et orientation).
Documentation en direct
- Index : https://docs.croct.com/llms.txt
- Référence CQL : https://docs.croct.com/reference/cql/introduction.md (ajoutez
.mdà n'importe quelle page) - Recherche : https://docs.croct.com/api/search.md?term=