Guía de integración Clione + Next.js

Pinta las señales SEO de Clione (JSON-LD, meta title, meta description) en un storefront headless de Next.js.

Instalar

npm install @clione/seo

API key

El modo API llama a Clione desde tu servidor, así que necesita una API key de tipo server con el scope products:read, creada en Ajustes de la tienda → Claves API. Guárdala en una variable de entorno solo de servidor, nunca en una NEXT_PUBLIC_*. Si la key tiene dominios permitidos, pon uno de ellos en storefrontHost; el SDK lo envía como X-Clione-Storefront-Host. Mira Autenticación.

Pasa siempre platform: por defecto vale 'bigcommerce', así que una tienda Shopify consultada sin ella se busca en la plataforma equivocada.

CLIONE_API_URL=https://api.clione.ai
CLIONE_API_KEY=sk_live_...

App Router (Next.js 13+)

// app/products/[id]/page.tsx
import { getClioneSeoMetadata, fetchClioneSeo, getJsonLdScriptProps } from '@clione/seo/react'

const clioneConfig = {
  apiUrl: process.env.CLIONE_API_URL!,
  apiKey: process.env.CLIONE_API_KEY!,
  platform: 'bigcommerce' as const, // or 'shopify'
  storefrontHost: 'shop.example.com',
}

export async function generateMetadata({ params }: { params: { id: string } }) {
  // Returns { title, description } when Clione has them.
  return getClioneSeoMetadata(params.id, clioneConfig, 'product')
}

export default async function ProductPage({ params }: { params: { id: string } }) {
  const signals = await fetchClioneSeo('product', params.id, clioneConfig)
  const jsonLdProps = getJsonLdScriptProps(signals)

  return (
    <>
      {jsonLdProps && <script {...jsonLdProps} />}
      {/* product page content */}
    </>
  )
}

fetchClioneSeo y getClioneSeoMetadata nunca lanzan una excepción ante un error de red o HTTP: devuelven señales vacías y la página se pinta sin ellas.

Pages Router

// pages/products/[id].tsx
import Head from 'next/head'
import { createClioneSeo } from '@clione/seo'
import { getJsonLdScriptProps } from '@clione/seo/react'

export async function getServerSideProps({ params }) {
  const clione = createClioneSeo({
    source: 'api',
    apiUrl: process.env.CLIONE_API_URL,
    apiKey: process.env.CLIONE_API_KEY,
    platform: 'bigcommerce',
    storefrontHost: 'shop.example.com',
  })
  const signals = await clione.getSignals('product', params.id)
  return { props: { signals /* , ...other product data */ } }
}

export default function ProductPage({ signals }) {
  const jsonLdProps = getJsonLdScriptProps(signals)
  return (
    <>
      <Head>
        {signals.metaTitle && <title>{signals.metaTitle}</title>}
        {signals.metaDescription && <meta name="description" content={signals.metaDescription} />}
        {jsonLdProps && <script {...jsonLdProps} />}
      </Head>
      {/* product page content */}
    </>
  )
}

Modo metafield (Storefront API de Shopify)

Si tu tienda Next.js ya consulta la Storefront API de Shopify, selecciona seo { title description } y el metafield clione.jsonld en la entidad, y lee de ahí las señales:

import { createClioneSeo } from '@clione/seo'

const clione = createClioneSeo({ source: 'metafield' })

// In getServerSideProps or a server component:
const signals = clione.extractSignals(shopifyProduct)
const headHtml = clione.renderHead(signals)

Sin llamada a la API y sin API key de Clione. Mira el modo metafield para ver qué campos lee.

Caché

La API de Clione devuelve Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400. Usa revalidate de Next.js para cachear:

// App Router
export const revalidate = 3600 // revalidate every hour

// Pages Router
export async function getStaticProps({ params }) {
  // ... fetch Clione signals
  return { props: { signals }, revalidate: 3600 }
}

Tipos de entidad soportados

• 'product' — páginas de producto
• 'category' — páginas de categoría (BigCommerce)
• 'collection' — páginas de colección (Shopify)
• 'page' — páginas CMS