Intégrer un SDK Croct
Connectez un SDK Croct à une application pour qu'elle rende le contenu des emplacements, évalue CQL et identifie les utilisateurs. Le contenu et les audiences vivent dans le tableau de bord Croct ; le code ne fait que référencer les emplacements par leur ID et version, et fournit un contenu de secours.
Workflow
- [ ] 1. Détecter la stack et choisir le SDK (tableau ci-dessous)
- [ ] 2. Installer avec la CLI (`croct init`, exécutée par l'utilisateur), manuellement uniquement si demandé ou si la CLI ne peut pas s'exécuter
- [ ] 3. Ajouter l'emplacement avec la CLI (`npx croct@latest add slot home-hero@1 --example`) pour les types + fallback
- [ ] 4. Rendre le contenu : côté serveur lorsque le framework le permet, côté client sinon
- [ ] 5. Identifier/anonymiser les utilisateurs à la connexion/déconnexion (ou passer l'ID utilisateur à l'initialisation)
- [ ] 6. Vérifier : la page d'intégration affiche "Trafic reçu dans les dernières 24 heures" ; sinon, activer le mode débogage
1. Choisir le SDK
Lisez d'abord package.json / composer.json. Choisissez le SDK le plus spécifique pour le framework ; n'utilisez jamais le SDK JavaScript simple à l'intérieur de React, Next.js, Vue, Nuxt ou Hydrogen.
| Stack | Package | Initialisation | Rendu serveur | Référence |
|---|---|---|---|---|
JS simple, tout bundler, ou balise <script> | @croct/plug (ou https://cdn.croct.io/js/v1/lib/plug.js) | croct.plug({appId}) une fois au démarrage | fetchContent/evaluate seul depuis @croct/plug/api avec apiKey | javascript.md |
| React (SPA, Vite, tout SSR non-Next) | @croct/plug-react | <CroctProvider appId="..."> à la racine | Les hooks client nécessitent initial ; bas niveau avec @croct/plug-react/api | react.md |
| Next.js (App ou Pages Router) | @croct/plug-next | middleware (≤15) / proxy (≥16) + <CroctProvider> depuis @croct/plug-next/CroctProvider | Oui : @croct/plug-next/server | nextjs.md |
| Vue | @croct/plug-vue | app.use(createCroct({appId})) | Composables/composants ; SSR nécessite des valeurs initiales | vue.md |
| Nuxt | @croct/plug-nuxt | modules: ['@croct/plug-nuxt'] dans nuxt.config | Oui | nuxt.md |
| Shopify Hydrogen (React Router 7 ou Remix) | @croct/plug-hydrogen | Plugin Vite + createCroctMiddleware / createCroctContext depuis @croct/plug-hydrogen/server | Oui | hydrogen.md |
| PHP simple | croct/plug-php (+ un client PSR-18, ex. guzzlehttp/guzzle nyholm/psr7) | Croct::fromDotenv() puis Croct::emitCookies() avant la sortie | Oui (serveur d'abord) | php.md |
| Laravel | croct/plug-laravel | Informations d'identification .env | Oui | laravel.md |
| Symfony | croct/plug-symfony symfony/twig-bundle | Enregistrer le bundle dans config/bundles.php + informations d'identification .env | Oui (Twig) | symfony.md |
| Drupal | croct/plug-drupal | Activer le module ; informations d'identification dans settings.php ; reconstruire le cache | Oui | drupal.md |
| Storyblok (JS ou PHP) | — | Utiliser le skill croct-integrate-platforms | — | — |
| Langage non pris en charge ou HTTP brut | — | Utiliser le skill croct-use-api | — | — |
2. Installer
La page d'intégration de chaque SDK, y compris PHP, Laravel, Symfony, Drupal et Hydrogen, recommande la CLI. init est interactif et nécessite une session connectée, donc demandez à l'utilisateur de l'exécuter depuis la racine du projet dans son propre terminal :
npx croct@latest init
croct init détecte le framework, connecte l'utilisateur, sélectionne l'organisation/espace de travail/application, installe le SDK correspondant et configure l'environnement (provider, middleware, variables d'environnement). Lorsque l'utilisateur a déjà une session et connaît les IDs, vous pouvez exécuter vous-même la forme non interactive :
npx croct@latest --no-interaction init --sdk next --org <org> --wor <workspace> --dev-app <dev-app> --prod-app <prod-app>
(--sdk n'accepte que javascript, react, vue, next, nuxt ; omettre pour la détection automatique). Les drapeaux, l'utilisation CI et croct.json sont dans le skill croct-use-cli. Revenez aux étapes manuelles du fichier de référence du framework uniquement si l'utilisateur le demande ou si la CLI ne peut pas s'exécuter.
3. Ajouter l'emplacement
Passez toujours l'ID et la version de l'emplacement. Sans eux, la CLI demande un emplacement, auquel vous ne pouvez pas répondre :
npx croct@latest add slot home-hero@1 --example
Ceci génère des types TypeScript (afin que useContent('home-hero@1') / fetchContent('home-hero@1') soient typés), télécharge le contenu par défaut de l'emplacement comme fallback automatique et écrit un exemple fonctionnel. Réexécutez croct install / croct update pour resynchroniser après les modifications du tableau de bord (voir croct-use-cli).
Concepts centraux (tous les SDK)
IDs et versions d'emplacements
- Référencez un emplacement comme
<id>@<version>, par ex.home-hero@1. Pas de version (home-hero) signifiehome-hero@latest. - Épinglez toujours une version. Les emplacements non épinglés répercutent immédiatement les changements de schéma cassants. Lorsque le tableau de bord crée une nouvelle version majeure, l'application continue de recevoir l'ancienne version jusqu'à ce que le code soit mis à jour.
- Tapez le contenu avec
SlotContent<'home-hero@1'>etComponentContent<'card@1'>(exporté par@croct/plug,@croct/plug-react,@croct/plug-next). Les emplacements d'union se résolvent en une union discriminée sur_type.
Contenu de secours, par défaut et initial
| Terme | Ce que c'est | D'où ça vient |
|---|---|---|
| Contenu par défaut | Contenu de l'emplacement affiché lorsqu'aucune expérience ne correspond, que la locale n'en a pas, que le contenu statique est demandé ou que la récupération échoue | Tableau de bord |
| Fallback | Valeur rendue lorsque la requête échoue | Option fallback dans le code, sinon contenu par défaut téléchargé par la CLI (@croct/content) |
| Initial (hooks client React/Next) | Valeur rendue pendant le SSR/pré-rendu et pendant le chargement côté client | Option initial ; la CLI l'ajoute automatiquement |
Ordre de résolution dans le SDK : contenu dynamique → fallback explicite → contenu par défaut de la CLI → erreur. Sans fallback et sans contenu CLI, une récupération échouée lance une erreur (JS croct.fetch rejette). Lisez le contenu CLI directement avec getSlotContent(slotId, locale?) / loadSlotContent(slotId, locale?) depuis @croct/content (préférez la version asynchrone avec du code splitting).
Rendu client vs serveur
| Besoin | Faire |
|---|---|
| Contenu final dans le premier HTML, pas de scintillement, crawlable | Récupérer côté serveur (Next fetchContent depuis @croct/plug-next/server, Nuxt, Hydrogen, famille PHP) |
La page doit rester un fichier statique / CDN / output: 'export' | Hooks/composants client avec une valeur initial ou une limite <Suspense> |
| Section hors écran où un squelette est acceptable | Côté client est suffisant |
| Rendu serveur en React simple / SSR personnalisé | fetchContent / evaluate depuis @croct/plug-react/api (ou @croct/plug/api) avec apiKey, puis passer le contenu comme props |
Les requêtes côté serveur s'authentifient avec une clé API (ne l'envoyez jamais au navigateur) ; les requêtes côté client utilisent l'ID d'application. Passer à la fois appId et apiKey à une fonction autonome est une erreur.
Évaluation de requêtes
Évaluez CQL à l'exécution avec croct.evaluate(query, {attributes}) (JS), useEvaluation / <Personalization> (React/Next client), ou evaluate / cql`...` (serveur Next). Les requêtes sont limitées à 500 caractères ; les résultats peuvent être n'importe quel JSON ('location' retourne un objet). Fournissez toujours un fallback (.catch(() => false) ou fallback: false). Syntaxe CQL : skill croct-cql.
Évaluation ou emplacement ? La documentation présente les emplacements comme le moyen de mettre à jour le contenu sans modifications de code ; une requête évaluée vit dans le code et ne change qu'avec un déploiement.
| Besoin | Utiliser |
|---|---|
| Contenu, audience ou déploiement que les marketeurs modifient, planifient ou testent A/B | Un emplacement plus une expérience (voir croct-personalize-and-test) |
| Logique fixée par l'ingénierie (afficher/masquer un widget, bifurquer sur une condition), pas de contenu à éditer | evaluate / useEvaluation avec un fallback |
Attributs de contexte
Passez des données spécifiques à l'application (plan, état du panier) comme attributes (JS/React) ou context.attributes (serveur Next, fonctions autonomes) ; lisez-les dans CQL comme context's plan is "premium". Limites : jusqu'à 30 entrées, 5 niveaux de profondeur, clés ≤ 50 caractères, valeurs chaîne ≤ 50 caractères.
Informations d'identification et variables d'environnement
| Stack | ID d'application | Clé API |
|---|---|---|
| Next.js | NEXT_PUBLIC_CROCT_APP_ID | CROCT_API_KEY |
| Nuxt | NUXT_PUBLIC_CROCT_APP_ID | NUXT_CROCT_API_KEY |
| Hydrogen | PUBLIC_CROCT_APP_ID | CROCT_API_KEY |
| PHP, Laravel, Symfony | CROCT_APP_ID | CROCT_API_KEY |
| Drupal | $settings['croct.app_id'] | $settings['croct.api_key'] |
| JavaScript, React, Vue | Option appId / prop | Uniquement fonctions autonomes côté serveur |
- Trouvez l'ID d'application sur la page Intégration de l'application ; créez des clés sur sa page Clés API.
- Pour les SDK serveur qui émettent des jetons utilisateur (Next.js), la clé API a besoin de la permission Émettre des jetons utilisateur.
- Chaque environnement a sa propre application. Un ID d'application de production utilisé sur localhost (ou vice versa) échoue avec des informations d'identification invalides.
Identifier et anonymiser
- Appelez
identify(userId)à la connexion/inscription etanonymize()à la déconnexion. Les changements d'identité terminent la session en cours et en démarrent une nouvelle. - Si l'utilisateur est déjà connecté lorsque la page se charge, passez l'ID à l'initialisation (
userIddanscroct.plug/<CroctProvider>) afin que le SDK ne crée pas de session anonyme supplémentaire. userIddoit être une chaîne ; convertissez les IDs numériques (de préférence côté serveur). Préférez les IDs aléatoires (UUID v4) aux emails ou aux numéros séquentiels.- Lorsque Exiger un jeton signé est activé dans les paramètres de l'application,
userId/identify(jetons non signés) échouent ; passez plutôt untokensigné. Next.js signe les jetons pour vous avecCROCT_API_KEY. - Next.js : préférez
withCroct({userIdResolver})dans le middleware/proxy pour maintenir le jeton synchronisé avec la session d'authentification à chaque requête.
Options Plug à connaître
appId, debug, test, track (suivi automatique, défaut true), userId / token (mutuellement exclusifs), tokenScope (global | isolated | contextual), defaultFetchTimeout (JS/React 5000 ms ; Next 2000 ms), defaultPreferredLocale, baseEndpointUrl (serveurs mock), cookie (stocker l'ID client / jeton utilisateur / jeton de prévisualisation dans des cookies propriétaires), eventMetadata, urlSanitizer, logger. Liste complète : javascript.md.
Suivi et collecte de données
Suivez les objectifs avec croct.track('goalCompleted', {goalId}) ; éditez le profil/session avec croct.user.edit().set(...).save() / croct.session.edit(). Catalogue d'événements, événements recommandés et règles d'attributs : skill croct-track-events.
Pièges
À faire :
- Épinglez les versions d'emplacements (
home-hero@1) et conservez les fallbacks (contenu par défaut CLI ou explicite). - Fournissez
initial(ou<Suspense>) pour chaqueuseContent/useEvaluationclient qui peut être rendu sur le serveur. - Appelez les méthodes
Plugcôté client (useCroct().track,identify,user.edit) à l'intérieur deuseEffectou de gestionnaires d'événements, jamais pendant le rendu. - Ajoutez chaque domaine qui charge le SDK aux Origines de confiance de l'application.
- Activez d'abord le mode débogage quand quelque chose ne va pas (
debug: true,NEXT_PUBLIC_CROCT_DEBUG=true), puis vérifiez l'onglet Réseau.
À ne pas faire :
- N'appelez pas
croct.plugdeux fois (appelez d'abordunplug()) ni aucune méthode avantplug("Croct is not plugged in"). - Ne mettez pas la clé API dans le code client ou dans des variables
NEXT_PUBLIC_*. - Ne spécifiez pas l'ID d'application à la fois dans la balise script
?appId=et dansplug(erreur d'ID d'application conflictuelle). - N'appelez pas Next
fetchContentsur une route que vous voulez garder statique ; cela opte la route dans le rendu dynamique. Utilisez plutôt les hooks client. - N'utilisez pas la balise
cqlen dehors du App Router Next.js ; utilisezevaluateavecroute.
Erreurs courantes
| Erreur | Correctif |
|---|---|
Croct is not plugged in. | Appelez croct.plug au démarrage avant d'autres appels |
The app ID must be specified when it cannot be auto-detected. | Passez appId (ou ?appId= sur la balise script) |
The request was not authorized, most likely due to invalid credentials. | Mauvais ID d'application, mauvais environnement, jeton expiré/altéré (effacez les cookies + stockage local), ou jeton non signé avec Exiger un jeton signé activé |
Erreur CORS / The origin of the request is not allowed in your application settings. | Ajoutez le domaine sous Origines de confiance |
The user ID must be a string. | Convertissez l'ID en chaîne |
The request timed out. | Augmentez timeout / le délai d'attente par défaut ; vérifiez X-Croct-Timing / X-Croct-Region dans les logs de débogage |
The query is too complex. | Requête de plus de 500 caractères ; simplifiez, divisez ou passez les données via des attributs |
The service is temporarily suspended. | Pas un bug de code : espace de travail suspendu ou trafic de bot (X-Suspension-Reason) ; conservez les fallbacks |
The application has exceeded the monthly active users (MAU) quota. | Mettez à niveau le forfait ou attendez le prochain cycle |
useCroct() can only be used in the context of a <CroctProvider> component. | Enveloppez l'arborescence dans <CroctProvider> |
The initial content/value is required for server-side rendering (SSR). | Ajoutez initial, ou récupérez côté serveur |
Did you forget to configure Croct's middleware? | Ajoutez le middleware/proxy Next |
someFunction() requires specifying the route parameter outside app routes. | Passez route: context (Pages Router/routes API) |
Did you forget to set the SOME_ENV_VAR environment variable? | Définissez NEXT_PUBLIC_CROCT_APP_ID / CROCT_API_KEY |
| Contenu non mis à jour après publication (pas d'erreur) | Les hooks client mettent en cache les résultats pour expiration (60 s, étendu à chaque rendu) ; changez cacheKey pour forcer une nouvelle récupération. Vérifiez que le changement est publié, pas un brouillon. Une version épinglée (home-hero@1) ne reçoit jamais une nouvelle version majeure : exécutez croct upgrade. Fallback obsolète après une requête échouée : croct update rafraîchit le contenu par défaut de la CLI |
Index des références
Chargez uniquement le fichier pour la stack utilisée.
- references/javascript.md —
@croct/plug: options plug,fetch,evaluate,test, identité, correctifs,@croct/plug/apiautonome, tests, erreurs. - references/react.md —
@croct/plug-react: provider,useContent,<Slot>,useEvaluation,<Personalization>,useCroct, valeurs initiales SSR, tests.
[truncated for translation]