Recomendaciones de productos en el sitio

El Web SDK puede mostrar recomendaciones de productos en su sitio web: en una página de producto, en el carrito, en una página de catálogo o en una página 404. Los productos provienen del Catálogo de productos de la aplicación. Hay dos formas de mostrarlos:

Widget: añada un elemento con el atributo data-pw-recommendations y el SDK lo llenará con una cuadrícula de productos.
API headless: llame a Pushwoosh.recommendations.fetch y renderice los productos con su propio marcado.

Un ejemplo en vivo es la tienda de demostración de Pushwoosh en pushon.pushwoosh.com. Tiene un bloque de widget en la página 404 y bloques headless en la página de producto y en el carrito.

Requisitos previos

Web SDK 3.96.0 o posterior, cargado desde la CDN de Pushwoosh como se describe en la guía de Web push SDK 3.0. El paquete npm web-push-notifications aún no incluye las recomendaciones.
Productos en el Catálogo de productos de la aplicación.
Recomendaciones en el sitio activadas para la aplicación. Consulte Activar las recomendaciones en el sitio.

Activar las recomendaciones en el sitio

Cada aplicación se activa por separado, porque el feed que sirve los bloques es público y no requiere un API token. Hasta entonces, el feed responde con un error y los bloques permanecen vacíos.

Para activar las recomendaciones en el sitio en el Panel de Control:

Vaya a Contenido → Catálogo de productos para la aplicación.
Haga clic en On-site recommendations.
Active Show recommendations on my website.
En Website domains, introduzca los dominios de los sitios web que mostrarán los bloques, uno por línea. Por ejemplo, shop.example.com.
Haga clic en Guardar.

Panel On-site recommendations con el interruptor Show recommendations on my website activado, un dominio en Website domains y el botón Save

Después de guardar:

Website domains muestra los dominios tal como Pushwoosh los almacenó: con https:// añadido, en minúsculas y sin duplicados. Revise la lista en busca de errores tipográficos.
Los bloques se cargan solo en los sitios web de la lista. Si deja Website domains vacío, los bloques se cargan en cualquier sitio web.
El cambio surte efecto en menos de un minuto.

Si no puede acceder al Panel de Control, pida al soporte de Pushwoosh o a su Customer Success Manager que active las recomendaciones en el sitio para la aplicación. Incluya el código de aplicación y los dominios de sus sitios web.

Estrategias de recomendación

Estrategia	Qué muestra	Requiere
`viewed`	Productos que este visitante vio recientemente. Para un visitante con sesión iniciada, los productos vistos con su user ID aparecen primero.	Vistas de productos enviadas con `trackProductView`.
`bestsellers_30d`	Los productos más vendidos de la aplicación en los últimos 30 días. Los productos agotados se omiten.	Eventos de pedido con los artículos del pedido.
`also_bought`	Productos que a menudo se compran o se ven junto con un producto determinado. Los productos agotados se omiten.	Vistas de productos enviadas con `trackProductView`, eventos de pedido o cualquier otro evento que contenga un ID de producto. Consulte Rastrear la actividad de productos. La solicitud necesita un ID de producto.

Cuando una estrategia no tiene nada que mostrar, el feed sirve en su lugar la estrategia de respaldo. La estrategia de respaldo es bestsellers_30d de forma predeterminada. Establézcala en none para obtener en su lugar una respuesta vacía. La respuesta siempre indica qué estrategia se sirvió realmente, para que pueda cambiar el título del bloque.

Rastrear las vistas de productos

Las estrategias viewed y also_bought usan las vistas de productos. En cada página de producto, llame a trackProductView una vez que el SDK esté listo:

Pushwoosh.push(() => {
  Pushwoosh.trackProductView({
    id: 'SKU-123',
    name: 'Linen shirt',
    price: 49.9,
    currency: 'USD',
    category: 'Shirts',
    url: 'https://shop.example.com/linen-shirt',
    imageUrl: 'https://shop.example.com/img/linen-shirt.jpg',
  });
});

Solo id es obligatorio. Use el mismo ID de producto que en su Catálogo de productos. El SDK envía un evento PW_ProductView y omite las vistas repetidas del mismo producto en un plazo de 30 segundos, por lo que recargar la página no cuenta como una segunda vista.

Enviar eventos de pedido

La estrategia bestsellers_30d cuenta solo las ventas procedentes de eventos de pedido, y es la estrategia de respaldo predeterminada de todos los bloques. Cuando un visitante realice un pedido, envíe PW_OrderCreated:

Pushwoosh.push((api) => {
  api.postEvent('PW_OrderCreated', {
    orderId: 'ORDER-10293',
    items: [
      { productId: 'SKU-123', quantity: 1 },
      { productId: 'SKU-456', quantity: 2 },
    ],
  });
});

orderId es obligatorio, porque un pedido sin él no se cuenta. En items, use los mismos ID de producto que en su Catálogo de productos. Cuando un pedido cambie, envíe PW_OrderUpdated con los mismos orderId e items. Para enviar los eventos de pedido desde su servidor, consulte Bestsellers: añada artículos a sus eventos de pedido.

Añada un elemento con el atributo data-pw-recommendations donde deba aparecer el bloque. El SDK carga el widget solo en las páginas que tienen un elemento de este tipo.

<div
  data-pw-recommendations
  data-pw-strategy="also_bought"
  data-pw-product-id="SKU-123"
  data-pw-fallback="bestsellers_30d"
  data-pw-limit="4"
  data-pw-title="Bought together"
  data-pw-fallback-title="Popular right now"
  data-pw-block="pdp-also-bought"
  data-pw-min-height="260"
></div>

Atributo	Descripción
`data-pw-recommendations`	Marca el elemento como un bloque de recomendaciones. Obligatorio.
`data-pw-strategy`	`viewed`, `bestsellers_30d` o `also_bought`. El valor predeterminado es `bestsellers_30d`.
`data-pw-fallback`	Estrategia que se sirve cuando la principal no tiene nada: `viewed`, `bestsellers_30d`, `also_bought` o `none`. El valor predeterminado es `bestsellers_30d`.
`data-pw-limit`	Número de productos, de 1 a 12. El valor predeterminado es 6.
`data-pw-product-id`	El producto en pantalla. Obligatorio para `also_bought`.
`data-pw-exclude`	ID de productos separados por comas que no se deben mostrar, por ejemplo, los productos que ya están en el carrito. Hasta 50.
`data-pw-block`	Nombre del bloque. Se añade a los enlaces de productos y a los eventos de clic, para que pueda distinguir los bloques en las analíticas.
`data-pw-title`	Título del bloque.
`data-pw-fallback-title`	Título que se muestra cuando se sirvió la estrategia de respaldo, por ejemplo, “Popular right now” en lugar de “You viewed”.
`data-pw-min-height`	Espacio que se reserva mientras se carga el bloque, para evitar un desplazamiento del diseño. Un número se interpreta como píxeles. También funciona cualquier longitud CSS.

El widget muestra la imagen, el nombre y el precio de cada producto, y enlaza a la página del producto. Los enlaces de productos llevan utm_medium=onsite. Un clic en un producto envía un evento PW_RecommendationClick con el nombre del bloque, la estrategia y la posición del producto.

Cuando cambia cualquier atributo data-pw-*, el bloque se vuelve a cargar. Por ejemplo, actualice data-pw-product-id cuando el producto en pantalla cambie sin recargar la página.

Bloques para páginas típicas

Página	Estrategia	Atributos que establecer
Página de producto	`also_bought`	`data-pw-product-id` con el producto en pantalla, `data-pw-exclude` con el mismo ID
Carrito	`also_bought`	`data-pw-product-id` con un producto del carrito, `data-pw-exclude` con todos los productos del carrito
Página de catálogo o de inicio	`bestsellers_30d`	—
Página 404	`viewed`	`data-pw-fallback="bestsellers_30d"` y `data-pw-fallback-title`, para que los visitantes nuevos vean productos populares

Estados del bloque

El widget establece el atributo data-pw-state en el elemento del bloque:

loading: los productos se están cargando.
ready: los productos se muestran.
empty: ni la estrategia ni la estrategia de respaldo tienen productos. El bloque permanece vacío.
error: los productos no se cargaron. El bloque permanece vacío.

Use el estado para ocultar su propio marco o encabezado alrededor de un bloque vacío:

.recommendations-frame:has([data-pw-state="empty"], [data-pw-state="error"]) {
  display: none;
}

El widget se renderiza dentro de un shadow DOM, por lo que el CSS de su sitio no llega a su contenido. En su lugar, establezca estas propiedades personalizadas en el elemento del bloque:

Propiedad	Descripción	Predeterminado
`--pw-reco-font`	Familia de fuentes	Heredada de la página
`--pw-reco-accent`	Color del precio	Color del texto actual
`--pw-reco-radius`	Radio de las esquinas de las imágenes de productos	`8px`
`--pw-reco-columns`	Número de columnas de la cuadrícula. En pantallas de hasta 600px de ancho, la cuadrícula siempre tiene 2 columnas.	Tantas como quepan

[data-pw-recommendations] {
  --pw-reco-columns: 4;
  --pw-reco-radius: 0;
  --pw-reco-accent: #337ab7;
}

Para un ajuste más fino de los estilos, el título, la cuadrícula y cada tarjeta de producto se exponen como las CSS parts title, grid y card, por ejemplo, [data-pw-recommendations]::part(card).

Aplicaciones de una sola página

De forma predeterminada, el SDK busca los bloques una sola vez, cuando está listo. Si su sitio renderiza los bloques más tarde, por ejemplo, al navegar en una aplicación de una sola página, establezca recommendations.spa en true en la llamada init:

Pushwoosh.push(['init', {
  applicationCode: 'XXXXX-XXXXX',
  // other initialization parameters...
  recommendations: {
    spa: true,
  },
}]);

Reemplace XXXXX-XXXXX por su código de aplicación.

A partir de entonces, el SDK sigue observando la página y carga el widget en cuanto aparece un bloque.

Para mantener el widget desactivado incluso cuando una página tiene elementos data-pw-recommendations, establezca recommendations.widget en false. La API headless sigue funcionando.

Renderizar bloques con su propio marcado

Use la API headless cuando el diseño del widget no se ajuste a su diseño. Solicite productos con Pushwoosh.recommendations.fetch e informe de los clics con Pushwoosh.recommendations.trackClick:

Pushwoosh.push(async () => {
  const request = {
    strategy: 'also_bought',
    productId: 'SKU-123',
    exclude: ['SKU-123'],
    fallback: 'bestsellers_30d',
    limit: 4,
    block: 'pdp-also-bought',
  };
  const { items, strategy } = await Pushwoosh.recommendations.fetch(request);

  const title = strategy === request.strategy ? 'Bought together' : 'Popular right now';
  renderBlock(title, items, (item, index) => {
    Pushwoosh.recommendations.trackClick({
      block: request.block,
      strategy,
      productId: item.id,
      position: index + 1,
    });
  });
});

fetch acepta los mismos parámetros que los atributos del widget: strategy, fallback, limit, productId, exclude y block. Devuelve:

items: los productos. Cada uno tiene id, title, description, image_url, url, price, price_formatted, old_price_formatted (solo para un producto en oferta), currency, category y sku.
strategy: la estrategia que se sirvió realmente. Difiere de la solicitada cuando se sirvió la estrategia de respaldo, y es none cuando la respuesta está vacía.

Si la solicitud falla, fetch lanza un error. Captúrelo y oculte el bloque.

trackClick envía el evento PW_RecommendationClick. Se entrega incluso cuando el clic abre otra página. position es el lugar del producto en el bloque, empezando por 1.

Comportamiento sin consentimiento para la comunicación

Si la comunicación con Pushwoosh está desactivada para el visitante, por ejemplo, con communicationEnabled: false en la llamada init (consulte Gestionar el consentimiento del usuario para las notificaciones push web):

trackProductView y trackClick no envían nada.
Los bloques siguen mostrando productos, pero la solicitud no identifica al visitante. La estrategia viewed no tiene historial que usar, por lo que se sirve la estrategia de respaldo.

Una vez que el visitante habilita la comunicación, las vistas de productos y los clics se vuelven a rastrear.