Saltar al contenido principal

BigCommerce headless (Catalyst, Alokai)

Lee esto primero. En un storefront headless de BigCommerce, Clione escribe los datos y el código de tu storefront tiene que pintarlos. Nada de lo que instala Clione llega por sí solo a un front de Catalyst o de Alokai. Esta página cuenta qué está verificado y qué no.

En un tema Stencil, Clione publica su JSON-LD con un widget de BigCommerce que la propia BigCommerce pinta en la página. Un storefront headless (Catalyst, Alokai o cualquier front en Next.js o Nuxt sobre las APIs de BigCommerce) nunca pinta esos widgets. Lo que sí puede leer son los metafields del producto.

Qué escribe Clione al publicar un producto​

Cada vez que publicas un producto en una tienda BigCommerce, Clione escribe el widget de Stencil y tres metafields de producto, tanto si tu storefront es headless como si no:

NamespaceKeyValorCuándo se escribe
clionejsonldEl mismo @graph JSON-LD que lleva el widget de Stencil: Organization, WebSite, BreadcrumbList, Product y FAQPage cuando el producto tiene FAQsEn cada publicación del producto
globaltitle_tagEl meta title que Clione acaba de escribirSi la publicación incluía el meta title
globaldescription_tagLa meta description que Clione acaba de escribirSi la publicación incluía la meta description

Los metafields se crean con el permiso read_and_sf_access de BigCommerce, el que BigCommerce ofrece para los metafields que un storefront lee con su Storefront GraphQL API.

Escribirlos nunca bloquea la publicación: si falla un metafield, la publicación sigue dando el widget de Stencil por escrito.

Qué tiene que hacer tu storefront​

  1. Pedir los metafields. La query de producto de tu storefront tiene que pedir el namespace clione, key jsonld, y el namespace global, keys title_tag y description_tag. Si no los pide, no recibe nada.
  2. Pintarlos en el servidor. Imprime el JSON-LD como <script type="application/ld+json"> en el HTML que devuelve tu servidor, y el título y la descripción como <title> y <meta name="description"> de la página. Los crawlers de IA no ejecutan JavaScript, así que una etiqueta añadida en el navegador no cuenta.

El SDK @clione/seo lee justo esos tres metafields: extractSignals() recibe un objeto de producto que ya los trae y devuelve el JSON-LD, el título y la descripción. Tiene un adaptador de Nuxt para storefronts Alokai y uno de React para Next.js. No toca tu query de producto: pedir los metafields sigue siendo cosa de tu código.

Verificado y sin verificar​

Verificado:

  • El código de Clione escribe los tres metafields en cada publicación de producto, con read_and_sf_access.
  • En una tienda BigCommerce real (nuestra tienda de pruebas), un producto publicado lleva los metafields de Clione.
  • Los nombres de metafield que busca el SDK son los que escribe Clione.

Sin verificar:

  • Que un storefront headless los lea. La mitad de la lectura no se ha probado contra un storefront Catalyst o Alokai real. Nuestro storefront Catalyst de pruebas devolvió un error cuando lo intentamos.
  • Que BigCommerce los exponga por la Storefront GraphQL API en una tienda real. Es lo que BigCommerce documenta para read_and_sf_access, no algo que hayamos visto.
  • Que el conector de BigCommerce de Alokai pida los metafields de producto por defecto. Da por hecho que no y añádelos a tu query.
  • Ninguna prueba de extremo a extremo. No hay ningún test automático de Clione sobre un storefront BigCommerce headless.

Lo que no hay​

  • Solo productos. Las categorías y las páginas no reciben metafields: en un storefront BigCommerce headless no tienen nada que leer.
  • No hay módulo empaquetado para Catalyst ni para Alokai. El SDK es una librería de uso general que tus desarrolladores llaman desde sus propias páginas. No hay nada que instalar que se enganche solo al storefront, como hace el widget en Stencil o el app embed en Shopify.

Compruébalo tú​

Después de publicar un producto, descarga su página con un user agent de crawler y busca el JSON-LD en el HTML crudo:

curl -sSL -A "Mozilla/5.0 (compatible; Googlebot/2.1)" "https://tu-tienda.example/url-del-producto/" -o /tmp/p.html
grep -c '"@type":"Product"' /tmp/p.html

Si sale cero, tu storefront todavía no pinta el metafield en el servidor, escriba lo que escriba Clione.

Ver también: Capacidades por plataforma · Headless — Next.js.