Integrar um SDK Croct
Conecte um SDK Croct a um aplicativo para renderizar conteúdo de slot, avaliar CQL e identificar usuários. O conteúdo e os públicos residem no dashboard da Croct; o código apenas referencia slots por ID e versão e fornece um fallback.
Fluxo de Trabalho
- [ ] 1. Detecte a pilha e escolha o SDK (tabela abaixo)
- [ ] 2. Instale com o CLI (`croct init`, executado pelo usuário), apenas manual se solicitado ou o CLI não puder ser executado
- [ ] 3. Adicione o slot com o CLI (`npx croct@latest add slot home-hero@1 --example`) para tipos + fallback
- [ ] 4. Renderize-o: no servidor quando o framework permitir, caso contrário no cliente
- [ ] 5. Identifique/anonimize usuários no login/logout (ou passe o ID do usuário na inicialização)
- [ ] 6. Verifique: a página de Integração mostra "Tráfego recebido nas últimas 24 horas"; caso contrário, ative o modo de depuração
1. Escolha o SDK
Leia package.json / composer.json primeiro. Escolha o SDK mais específico para o framework; nunca use o SDK JavaScript simples dentro de React, Next.js, Vue, Nuxt ou Hydrogen.
| Pilha | Pacote | Inicialize com | Renderização no servidor | Referência |
|---|---|---|---|---|
JS simples, qualquer bundler ou tag <script> | @croct/plug (ou https://cdn.croct.io/js/v1/lib/plug.js) | croct.plug({appId}) uma vez na inicialização | fetchContent/evaluate standalone de @croct/plug/api com apiKey | javascript.md |
| React (SPA, Vite, qualquer SSR que não seja Next) | @croct/plug-react | <CroctProvider appId="..."> na raiz | Hooks do cliente precisam de initial; @croct/plug-react/api de baixo nível | react.md |
| Next.js (App ou Pages Router) | @croct/plug-next | middleware (≤15) / proxy (≥16) + <CroctProvider> de @croct/plug-next/CroctProvider | Sim: @croct/plug-next/server | nextjs.md |
| Vue | @croct/plug-vue | app.use(createCroct({appId})) | Composables/componentes; SSR precisa de valores iniciais | vue.md |
| Nuxt | @croct/plug-nuxt | modules: ['@croct/plug-nuxt'] no nuxt.config | Sim | nuxt.md |
| Shopify Hydrogen (React Router 7 ou Remix) | @croct/plug-hydrogen | Plugin Vite + createCroctMiddleware / createCroctContext de @croct/plug-hydrogen/server | Sim | hydrogen.md |
| PHP simples | croct/plug-php (+ um cliente PSR-18, ex. guzzlehttp/guzzle nyholm/psr7) | Croct::fromDotenv() depois Croct::emitCookies() antes da saída | Sim (servidor primeiro) | php.md |
| Laravel | croct/plug-laravel | Credenciais no .env | Sim | laravel.md |
| Symfony | croct/plug-symfony symfony/twig-bundle | Registre o bundle em config/bundles.php + credenciais no .env | Sim (Twig) | symfony.md |
| Drupal | croct/plug-drupal | Habilite o módulo; credenciais em settings.php; reconstrua o cache | Sim | drupal.md |
| Storyblok (JS ou PHP) | — | Use a habilidade croct-integrate-platforms | — | — |
| Linguagem não suportada ou HTTP bruto | — | Use a habilidade croct-use-api | — | — |
2. Instalar
Todas as páginas de integração dos SDKs, incluindo PHP, Laravel, Symfony, Drupal e Hydrogen, recomendam o CLI. O init é interativo e precisa de uma sessão autenticada, então peça ao usuário para executá-lo na raiz do projeto em seu próprio terminal:
npx croct@latest init
croct init detecta o framework, faz login, seleciona a organização/workspace/aplicação, instala o SDK correspondente e configura a estrutura (provider, middleware, variáveis de ambiente). Quando o usuário já tem uma sessão e conhece os IDs, você pode executar a forma não interativa você mesmo:
npx croct@latest --no-interaction init --sdk next --org <org> --wor <workspace> --dev-app <dev-app> --prod-app <prod-app>
(--sdk aceita apenas javascript, react, vue, next, nuxt; omita para detecção automática). Flags, uso em CI e croct.json estão na habilidade croct-use-cli. Recorra às etapas manuais no arquivo de referência do framework apenas quando o usuário solicitar ou o CLI não puder ser executado.
3. Adicionar o slot
Sempre passe o ID e a versão do slot. Sem eles, o CLI pede um slot, o que você não pode responder:
npx croct@latest add slot home-hero@1 --example
Isso gera tipos TypeScript (então useContent('home-hero@1') / fetchContent('home-hero@1') são tipados), baixa o conteúdo padrão do slot como fallback automático e escreve um exemplo funcional. Execute croct install / croct update novamente para ressincronizar após alterações no dashboard (veja croct-use-cli).
Conceitos principais (todos os SDKs)
IDs e versões de slot
- Referencie um slot como
<id>@<versão>, ex.home-hero@1. Sem versão (home-hero) significahome-hero@latest. - Sempre fixe uma versão. Slots não fixados captam alterações de esquema de quebra imediatamente. Quando o dashboard cria uma nova versão principal, o aplicativo continua recebendo a versão antiga até que o código seja atualizado.
- Digite o conteúdo com
SlotContent<'home-hero@1'>eComponentContent<'card@1'>(exportado por@croct/plug,@croct/plug-react,@croct/plug-next). Slots de união resolvem para uma união discriminada em_type.
Conteúdo fallback, padrão e inicial
| Termo | O que é | De onde vem |
|---|---|---|
| Conteúdo padrão | Conteúdo do slot mostrado quando nenhuma experiência corresponde, o locale não tem nenhum, o conteúdo estático é solicitado ou a recuperação falha | Dashboard |
| Fallback | Valor renderizado quando a requisição falha | Opção fallback no código, senão conteúdo padrão baixado pelo CLI (@croct/content) |
| Inicial (hooks do cliente React/Next) | Valor renderizado durante SSR/pré-renderização e enquanto carrega no cliente | Opção initial; o CLI adiciona automaticamente |
Ordem de resolução no SDK: conteúdo dinâmico → fallback explícito → conteúdo padrão do CLI → erro. Sem fallback e sem conteúdo do CLI, uma busca falha gera uma exceção (JS croct.fetch rejeita). Leia o conteúdo do CLI diretamente com getSlotContent(slotId, locale?) / loadSlotContent(slotId, locale?) de @croct/content (prefira o assíncrono com divisão de código).
Renderização cliente vs servidor
| Necessidade | Faça |
|---|---|
| Conteúdo final no primeiro HTML, sem flicker, rastreável | Busque no servidor (Next fetchContent de @croct/plug-next/server, Nuxt, Hydrogen, família PHP) |
A página deve permanecer um arquivo estático / CDN / output: 'export' | Hooks/componentes do cliente com um valor initial ou um limite <Suspense> |
| Seção abaixo da dobra onde um esqueleto é aceitável | Lado do cliente é suficiente |
| Renderização no servidor em React simples / SSR personalizado | fetchContent / evaluate de @croct/plug-react/api (ou @croct/plug/api) com apiKey, depois passe o conteúdo como props |
Requisições no servidor autenticam com uma chave de API (nunca a envie para o navegador); requisições no cliente usam o ID do aplicativo. Passar appId e apiKey para uma função standalone é um erro.
Avaliação de consultas
Avalie CQL em tempo de execução com croct.evaluate(query, {attributes}) (JS), useEvaluation / <Personalization> (React/Next cliente), ou evaluate / cql`...` (Next servidor). Consultas são limitadas a 500 caracteres; resultados podem ser qualquer JSON ('location' retorna um objeto). Sempre forneça um fallback (.catch(() => false) ou fallback: false). Sintaxe CQL: habilidade croct-cql.
Avaliação ou slot? A documentação apresenta slots como a forma de atualizar conteúdo sem alterações de código; uma consulta avaliada vive no código e muda apenas com um deploy.
| Necessidade | Use |
|---|---|
| Conteúdo, público ou rollout que profissionais de marketing alteram, agendam ou testam A/B | Um slot mais uma experiência (veja croct-personalize-and-test) |
| Lógica fixada pela engenharia (mostrar/esconder um widget, ramificar em uma condição), sem conteúdo para editar | evaluate / useEvaluation com um fallback |
Atributos de contexto
Passe dados específicos do aplicativo (plano, estado do carrinho) como attributes (JS/React) ou context.attributes (Next servidor, funções standalone); leia em CQL como context's plan is "premium". Limites: até 30 entradas, 5 níveis de profundidade, chaves ≤ 50 caracteres, valores string ≤ 50 caracteres.
Credenciais e variáveis de ambiente
| Pilha | ID do aplicativo | Chave de 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 | Opção appId / prop | apenas funções standalone no servidor |
- Encontre o ID do aplicativo na página de Integração do aplicativo; crie chaves na página de chaves de API.
- Para SDKs de servidor que emitem tokens de usuário (Next.js), a chave de API precisa da permissão Emitir tokens de usuário.
- Cada ambiente tem seu próprio aplicativo. Um ID de aplicativo de produção usado em localhost (ou vice-versa) falha com credenciais inválidas.
Identificar e anonimizar
- Chame
identify(userId)no login/cadastro eanonymize()no logout. Mudanças de identidade encerram a sessão atual e iniciam uma nova. - Se o usuário já estiver logado quando a página carregar, passe o ID na inicialização (
userIdemcroct.plug/<CroctProvider>) para que o SDK não crie uma sessão anônima extra. userIddeve ser uma string; converta IDs numéricos (preferencialmente no servidor). Prefira IDs aleatórios (UUID v4) em vez de e-mails ou números sequenciais.- Quando Exigir token assinado estiver ativado nas configurações do aplicativo,
userId/identify(tokens não assinados) falham; passe umtokenassinado em vez disso. O Next.js assina tokens para você comCROCT_API_KEY. - Next.js: prefira
withCroct({userIdResolver})no middleware/proxy para manter o token sincronizado com a sessão de autenticação em cada requisição.
Opções de plug que vale a pena conhecer
appId, debug, test, track (rastreamento automático, padrão true), userId / token (mutuamente exclusivos), tokenScope (global | isolated | contextual), defaultFetchTimeout (JS/React 5000 ms; Next 2000 ms), defaultPreferredLocale, baseEndpointUrl (servidores mock), cookie (armazenar ID do cliente / token do usuário / token de pré-visualização em cookies primários), eventMetadata, urlSanitizer, logger. Lista completa: javascript.md.
Rastreamento e coleta de dados
Rastreie metas com croct.track('goalCompleted', {goalId}); edite perfil/sessão com croct.user.edit().set(...).save() / croct.session.edit(). Catálogo de eventos, eventos recomendados e regras de atributos: habilidade croct-track-events.
Armadilhas
Faça:
- Fixe versões de slot (
home-hero@1) e mantenha fallbacks (conteúdo padrão do CLI ou explícito). - Forneça
initial(ou<Suspense>) para cadauseContent/useEvaluationdo cliente que possa renderizar no servidor. - Chame métodos do
Plugsomente do lado do cliente (useCroct().track,identify,user.edit) dentro deuseEffectou manipuladores de evento, nunca durante a renderização. - Adicione todo domínio que carrega o SDK às Origens confiáveis do aplicativo.
- Ative o modo de depuração primeiro quando algo estiver errado (
debug: true,NEXT_PUBLIC_CROCT_DEBUG=true), depois verifique a aba Network.
Não faça:
- Chame
croct.plugduas vezes (chameunplug()primeiro) ou chame qualquer método antes deplug("Croct is not plugged in"). - Coloque a chave de API no código do cliente ou em variáveis
NEXT_PUBLIC_*. - Especifique o ID do aplicativo tanto na tag script
?appId=quanto noplug(erro de ID do aplicativo conflitante). - Chame o Next
fetchContentem uma rota que você deseja que permaneça estática; isso faz a rota optar pela renderização dinâmica. Use hooks do cliente lá. - Use a tag
cqlfora do Next.js App Router; useevaluatecomroute.
Erros comuns
| Erro | Correção |
|---|---|
Croct is not plugged in. | Chame croct.plug na inicialização antes de outras chamadas |
The app ID must be specified when it cannot be auto-detected. | Passe appId (ou ?appId= na tag script) |
The request was not authorized, most likely due to invalid credentials. | ID do aplicativo errado, ambiente errado, token expirado/adulterado (limpe cookies + armazenamento local), ou token não assinado com Exigir token assinado ativado |
Erro CORS / The origin of the request is not allowed in your application settings. | Adicione o domínio em Origens confiáveis |
The user ID must be a string. | Converta o ID para string |
The request timed out. | Aumente timeout / tempo limite padrão; verifique X-Croct-Timing / X-Croct-Region nos logs de depuração |
The query is too complex. | Consulta com mais de 500 caracteres; simplifique, divida ou passe dados via atributos |
The service is temporarily suspended. | Não é um bug de código: workspace suspenso ou tráfego de bot (X-Suspension-Reason); mantenha fallbacks |
The application has exceeded the monthly active users (MAU) quota. | Faça upgrade do plano ou aguarde o próximo ciclo |
useCroct() can only be used in the context of a <CroctProvider> component. | Envolva a árvore em <CroctProvider> |
The initial content/value is required for server-side rendering (SSR). | Adicione initial, ou busque no servidor |
Did you forget to configure Croct's middleware? | Adicione middleware/proxy do Next |
someFunction() requires specifying the route parameter outside app routes. | Passe route: context (Pages Router/rotas de API) |
Did you forget to set the SOME_ENV_VAR environment variable? | Defina NEXT_PUBLIC_CROCT_APP_ID / CROCT_API_KEY |
| Conteúdo não atualizado após publicação (sem erro) | Hooks do cliente armazenam resultados em cache por expiration (60 s, estendido a cada renderização); mude cacheKey para forçar uma nova busca. Verifique se a alteração foi publicada, não é um rascunho. Uma versão fixada (home-hero@1) nunca recebe uma nova versão principal: execute croct upgrade. Fallback desatualizado após uma requisição com falha: croct update atualiza o conteúdo padrão do CLI |
Índice de referência
Carregue apenas o arquivo para a pilha em uso.
- references/javascript.md —
@croct/plug: opções de plug,fetch,evaluate,test, identidade, patches,@croct/plug/apistandalone, teste, erros. - references/react.md —
@croct/plug-react: provider,useContent,<Slot>,useEvaluation,<Personalization>,useCroct, valores iniciais SSR, teste. - references/nextjs.md —
@croct/plug-next: inicialização, middleware/proxy,
...