Recommandations de produits sur le site

Le Web SDK peut afficher des recommandations de produits sur votre site web : sur une page produit, dans le panier, sur une page de catalogue ou sur une page 404. Les produits proviennent du Catalogue de produits de l’application. Il existe deux façons de les afficher :

Widget : ajoutez un élément avec l’attribut data-pw-recommendations, et le SDK le remplit avec une grille de produits.
API headless : appelez Pushwoosh.recommendations.fetch et affichez les produits avec votre propre balisage.

Un exemple concret est la boutique de démonstration Pushwoosh sur pushon.pushwoosh.com. Elle comporte un bloc widget sur la page 404 et des blocs headless sur la page produit et dans le panier.

Prérequis

Web SDK 3.96.0 ou version ultérieure, chargé depuis le CDN Pushwoosh comme décrit dans le guide SDK Web Push 3.0. Le package npm web-push-notifications n’inclut pas encore les recommandations.
Des produits dans le Catalogue de produits de l’application.
Les recommandations sur le site activées pour l’application. Consultez Activer les recommandations sur le site.

Activer les recommandations sur le site

Chaque application doit être activée séparément, car le flux qui fournit les blocs est public et ne nécessite pas d’API token. En attendant, le flux répond par une erreur et les blocs restent vides.

Pour activer les recommandations sur le site dans le Panneau de Contrôle :

Allez dans Contenu → Catalogue de produits pour l’application.
Cliquez sur On-site recommendations.
Activez Show recommendations on my website.
Dans Website domains, saisissez les domaines des sites web qui afficheront les blocs, un par ligne. Par exemple, shop.example.com.
Cliquez sur Enregistrer.

Panneau On-site recommendations avec l'interrupteur Show recommendations on my website activé, un domaine dans Website domains et le bouton Save

Après l’enregistrement :

Website domains affiche les domaines tels que Pushwoosh les a enregistrés : avec https:// ajouté, en minuscules et sans doublons. Vérifiez que la liste ne contient pas de fautes de frappe.
Les blocs se chargent uniquement sur les sites web de la liste. Si vous laissez Website domains vide, les blocs se chargent sur n’importe quel site web.
La modification prend effet en moins d’une minute.

Si vous n’avez pas accès au Panneau de Contrôle, demandez au support Pushwoosh ou à votre Customer Success Manager d’activer les recommandations sur le site pour l’application. Indiquez le code d’application et les domaines de vos sites web.

Stratégies de recommandation

Stratégie	Ce qu’elle affiche	Prérequis
`viewed`	Les produits que ce visiteur a consultés récemment. Pour un visiteur connecté, les produits consultés sous son user ID apparaissent en premier.	Consultations de produits envoyées avec `trackProductView`.
`bestsellers_30d`	Les produits les plus vendus de l’application au cours des 30 derniers jours. Les produits épuisés sont ignorés.	Événements de commande avec les articles de la commande.
`also_bought`	Les produits souvent achetés ou consultés avec un produit donné. Les produits épuisés sont ignorés.	Consultations de produits envoyées avec `trackProductView`, événements de commande ou tout autre événement contenant un ID de produit. Consultez Suivre l’activité liée aux produits. La requête nécessite un ID de produit.

Lorsqu’une stratégie n’a rien à afficher, le flux fournit à la place la stratégie de repli. La stratégie de repli est bestsellers_30d par défaut. Définissez-la sur none pour obtenir une réponse vide à la place. La réponse indique toujours quelle stratégie a réellement été fournie, afin que vous puissiez modifier le titre du bloc.

Suivre les consultations de produits

Les stratégies viewed et also_bought utilisent les consultations de produits. Sur chaque page produit, appelez trackProductView une fois le SDK prêt :

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',
  });
});

Seul id est obligatoire. Utilisez le même ID de produit que dans votre Catalogue de produits. Le SDK envoie un événement PW_ProductView et ignore les consultations répétées du même produit dans un délai de 30 secondes, de sorte qu’un rechargement de page ne compte pas comme une deuxième consultation.

Envoyer des événements de commande

La stratégie bestsellers_30d ne compte que les ventes issues des événements de commande, et c’est la stratégie de repli par défaut de chaque bloc. Lorsqu’un visiteur passe une commande, envoyez PW_OrderCreated :

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

orderId est obligatoire, car une commande sans cet identifiant n’est pas comptée. Dans items, utilisez les mêmes ID de produit que dans votre Catalogue de produits. Lorsqu’une commande change, envoyez PW_OrderUpdated avec les mêmes orderId et items. Pour envoyer plutôt les événements de commande depuis votre serveur, consultez Bestsellers : ajoutez des articles à vos événements de commande.

Ajoutez un élément avec l’attribut data-pw-recommendations à l’endroit où le bloc doit apparaître. Le SDK charge le widget uniquement sur les pages qui contiennent un tel élément.

<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>

Attribut	Description
`data-pw-recommendations`	Marque l’élément comme un bloc de recommandations. Obligatoire.
`data-pw-strategy`	`viewed`, `bestsellers_30d` ou `also_bought`. Par défaut, `bestsellers_30d`.
`data-pw-fallback`	Stratégie à fournir lorsque la stratégie principale n’a rien : `viewed`, `bestsellers_30d`, `also_bought` ou `none`. Par défaut, `bestsellers_30d`.
`data-pw-limit`	Nombre de produits, de 1 à 12. Par défaut, 6.
`data-pw-product-id`	Le produit affiché à l’écran. Obligatoire pour `also_bought`.
`data-pw-exclude`	ID de produits séparés par des virgules à ne pas afficher, par exemple les produits déjà dans le panier. Jusqu’à 50.
`data-pw-block`	Nom du bloc. Il est ajouté aux liens des produits et aux événements de clic, afin que vous puissiez distinguer les blocs dans les analyses.
`data-pw-title`	Titre du bloc.
`data-pw-fallback-title`	Titre à afficher lorsque la stratégie de repli a été fournie, par exemple « Popular right now » au lieu de « You viewed ».
`data-pw-min-height`	Espace à réserver pendant le chargement du bloc, afin d’éviter un décalage de mise en page. Un nombre est interprété en pixels. Toute longueur CSS fonctionne également.

Le widget affiche l’image, le nom et le prix de chaque produit, et renvoie vers la page du produit. Les liens des produits contiennent utm_medium=onsite. Un clic sur un produit envoie un événement PW_RecommendationClick avec le nom du bloc, la stratégie et la position du produit.

Lorsque vous modifiez un attribut data-pw-*, le bloc se recharge. Par exemple, mettez à jour data-pw-product-id lorsque le produit affiché à l’écran change sans rechargement de la page.

Blocs pour les pages types

Page	Stratégie	Attributs à définir
Page produit	`also_bought`	`data-pw-product-id` avec le produit affiché, `data-pw-exclude` avec le même ID
Panier	`also_bought`	`data-pw-product-id` avec un produit du panier, `data-pw-exclude` avec tous les produits du panier
Page de catalogue ou page d’accueil	`bestsellers_30d`	—
Page 404	`viewed`	`data-pw-fallback="bestsellers_30d"` et `data-pw-fallback-title`, afin que les nouveaux visiteurs voient des produits populaires

États du bloc

Le widget définit l’attribut data-pw-state sur l’élément du bloc :

loading : les produits sont en cours de chargement.
ready : les produits sont affichés.
empty : ni la stratégie ni la stratégie de repli n’ont de produits. Le bloc reste vide.
error : les produits ne se sont pas chargés. Le bloc reste vide.

Utilisez l’état pour masquer votre propre cadre ou titre autour d’un bloc vide :

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

Le widget s’affiche dans un shadow DOM, de sorte que le CSS de votre site n’atteint pas son contenu. Définissez plutôt ces propriétés personnalisées sur l’élément du bloc :

Propriété	Description	Par défaut
`--pw-reco-font`	Famille de polices	Héritée de la page
`--pw-reco-accent`	Couleur du prix	Couleur du texte actuelle
`--pw-reco-radius`	Rayon des coins des images de produits	`8px`
`--pw-reco-columns`	Nombre de colonnes de la grille. Sur les écrans d’une largeur maximale de 600px, la grille comporte toujours 2 colonnes.	Autant que possible

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

Pour un style plus précis, le titre, la grille et chaque carte produit sont exposés en tant que CSS parts title, grid et card, par exemple [data-pw-recommendations]::part(card).

Applications monopages

Par défaut, le SDK recherche les blocs une seule fois, lorsqu’il est prêt. Si votre site affiche les blocs plus tard, par exemple lors de la navigation dans une application monopage, définissez recommendations.spa sur true dans l’appel init :

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

Remplacez XXXXX-XXXXX par votre code d’application.

Le SDK continue alors de surveiller la page et charge le widget dès qu’un bloc apparaît.

Pour désactiver le widget même lorsqu’une page contient des éléments data-pw-recommendations, définissez recommendations.widget sur false. L’API headless continue de fonctionner.

Afficher des blocs avec votre propre balisage

Utilisez l’API headless lorsque la mise en page du widget ne convient pas à votre design. Demandez les produits avec Pushwoosh.recommendations.fetch et signalez les clics avec 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 accepte les mêmes paramètres que les attributs du widget : strategy, fallback, limit, productId, exclude et block. Elle renvoie :

items : les produits. Chacun possède id, title, description, image_url, url, price, price_formatted, old_price_formatted (uniquement pour un produit en promotion), currency, category et sku.
strategy : la stratégie réellement fournie. Elle diffère de la stratégie demandée lorsque la stratégie de repli a été fournie, et vaut none lorsque la réponse est vide.

Si la requête échoue, fetch lève une erreur. Interceptez-la et masquez le bloc.

trackClick envoie l’événement PW_RecommendationClick. Il est transmis même lorsque le clic ouvre une autre page. position est la place du produit dans le bloc, à partir de 1.

Comportement sans consentement à la communication

Si la communication avec Pushwoosh est désactivée pour le visiteur, par exemple avec communicationEnabled: false dans l’appel init (consultez Gestion du consentement utilisateur pour les notifications push web) :

trackProductView et trackClick n’envoient rien.
Les blocs affichent toujours des produits, mais la requête n’identifie pas le visiteur. La stratégie viewed n’a aucun historique à utiliser, c’est donc la stratégie de repli qui est fournie.

Dès que le visiteur active la communication, les consultations de produits et les clics sont de nouveau suivis.