El contrato de renderizado de Clione para commercetools

Para quién es esto: para los desarrolladores que construyen el front. No para el merchant. Si te han mandado aquí, alguien ha conectado un proyecto de commercetools con Clione y lo de abajo es la mitad que lo hace visible.

Esta página es pública porque quien tiene que actuar sobre ella no tiene cuenta en nuestra documentación interna, y un contrato que solo puede leer una de las partes no es un contrato.

Por qué hay algo que hacer en tu lado

En Shopify, BigCommerce y WooCommerce, Clione publica dentro del propio escaparate: un bloque del theme, un widget, un hook de wp_head. commercetools no tiene escaparate. Clione escribe cuatro atributos en tus product projections y tu front los renderiza.

Si no lo hace, tu HTML no cambia. Una escritura perfecta y un front que nunca lee los atributos producen exactamente la misma página que no tener Clione, porque aquí los consumidores son crawlers y asistentes de IA: no ejecutan JavaScript y no llaman a nuestra API.

Los cuatro atributos

Declarados en tu product type y leídos de la variante (commercetools no tiene atributos a nivel de producto). Todos son ltext —un LocalizedString— porque una product projection ya es por locale:

Atributo	Tipo	Lleva
clione_meta_title	ltext	el meta title, por locale
clione_meta_description	ltext	la meta description, por locale
clione_faq	ltext	un array JSON de { question, answer }, por locale
clione_jsonld	ltext	el @graph de schema.org, como JSON, por locale

Dalos por congelados en cuanto hayas desplegado contra ellos. Renombrar uno es un despliegue por las dos partes en la misma ventana: en el hueco, cada producto lleva o el nombre viejo que tu código ya no lee o el nuevo que tu código desplegado no conoce. Si necesitas otros nombres, dilo antes de salir a producción.

Qué tienes que renderizar

Tres cosas, en la primera respuesta HTML, sin JavaScript:

1. El title y la description de clione_meta_title y clione_meta_description.
2. Un <script type="application/ld+json"> con clione_jsonld tal cual.
3. La FAQ como marcado real — <details>/<summary> sirve y no necesita JS.

Y dos documentos en tu dominio, no en el nuestro:

• /llms.txt — un índice de tus páginas
• /.well-known/agents.json — lo mismo, para agentes

Tienen que estar en tu origen. Un documento que un crawler encuentra en otro dominio describiendo tu web se descuenta, así que los helpers de abajo lanzan error si les pasas algo que no sea tu propio origen.

Qué NO tienes que hacer

Componer schema.org. clione_jsonld ya es el grafo que Clione construyó para esa entidad —Organization, WebSite, BreadcrumbList, el Product y la FAQPage, referenciados entre sí por @id—. Emítelo. Construir el tuyo son dos fuentes de verdad para una misma página, y la nuestra es la que el merchant revisa y aprueba.

Copia esto

La implementación de referencia es una app de Next.js (App Router) en el repositorio de Clione:

packages/seo-client/examples/commercetools-next/
  lib/clione-contract.ts        <- copia este fichero; no tiene dependencias
  app/products/[key]/page.tsx   <- un server component
  app/llms.txt/route.ts
  app/.well-known/agents.json/route.ts
  mock/products.ts              <- un producto enriquecido y otro sin enriquecer

lib/clione-contract.ts no importa nada —ni de Clione ni de un framework—, así que es tuyo en el momento en que lo copias. Cambia el marcado, los nombres de clase, las reglas de fallback. Clione mantiene una copia idéntica en su lado, y un test pasa las dos por los mismos fixtures en cada build, así que el fichero no puede separarse de lo que escribe el otro lado.

Pide a tu contacto en Clione el directorio si no tienes el repositorio.

Cuatro cosas fáciles de equivocar

Un client component. Lo que hace el App Router por defecto es un server component; déjalo así. ssr: false, un fetch en useEffect o un montaje en cliente producen una cáscara vacía para los únicos lectores que importan.

Que React escape el JSON-LD. Meter el grafo en un <script> desde JSX necesita dangerouslySetInnerHTML; sin eso React escapa el contenido y ningún parser lo lee como JSON-LD. Escapa antes < a <: un </script> dentro de cualquier cadena cierra el elemento para el parser de HTML, diga lo que diga el JSON. La referencia hace las dos cosas.

Un fallback de idioma silencioso. Servir meta en inglés en una página en alemán parece correcto para todo el mundo menos para quien lee. La referencia sale sin fallback: un locale que Clione aún no ha escrito renderiza tu propio meta nativo. Puedes cambiarlo, pero hazlo a propósito.

No renderizar nada cuando falta una señal, y no decir nada. Cada lectura del contrato responde un motivo —not_enriched, locale_missing, invalid_json, wrong_shape— para que puedas registrarlo. Un renderizador que no distingue "nadie ha enriquecido este producto todavía" de "el atributo lleva algo que no se pudo parsear" es como una escritura mala sobrevive un mes.

Compruébalo como lo comprobamos nosotros

Sin navegador y sin ejecutar JS: los mismos comandos que pasamos a las demás plataformas.

UA="Mozilla/5.0 (compatible; Googlebot/2.1)"
curl -sSL -A "$UA" https://tu-tienda.example.com/products/una-key -o /tmp/p.html
grep -c '"@type":"Product"'        /tmp/p.html   # >= 1
grep -c '"@type":"FAQPage"'        /tmp/p.html   # >= 1
grep -c '"@type":"Organization"'   /tmp/p.html   # >= 1
grep -c '"@type":"WebSite"'        /tmp/p.html   # >= 1
grep -c '"@type":"BreadcrumbList"' /tmp/p.html   # >= 1
grep -c '<summary>'                /tmp/p.html   # >= 1  la FAQ visible

curl -sS https://tu-tienda.example.com/llms.txt | grep -c 'clione.ai'   # == 0

# El control que hace que lo demás signifique algo: un producto sin atributos
# de Clione no debe renderizar NADA de esto.
curl -sSL -A "$UA" https://tu-tienda.example.com/products/sin-enriquecer \
  | grep -c 'application/ld+json'                                       # == 0

Ese último comando es el que todo el mundo se salta. Sin él, cualquiera de las comprobaciones de arriba la cumple también una página que imprime un grafo fijo, y un producto que perdiera sus señales parecería correcto.

Estado

La parte de escritura —que Clione ponga estos atributos en tus productos— está en desarrollo. Leer tu catálogo y enriquecerlo funcionan hoy. Nada aparece en tu web hasta que estén vivos este contrato y la escritura.