Des recommandations de produits livrées en JSON brut au lieu d’un widget prêt à afficher, pour que vous les mettiez en page vous-même. Utilisez-les pour un widget au design sur mesure, une application monopage, une application native, un modèle d’e-mail ou tout support dont vous maîtrisez la présentation et pour lequel vous voulez seulement la sélection. Vous la récupérez avec une seule requête GET.
Dans le panneau : Nouvelle campagne › App / API › API JSON — Recos produits.
Les étapes
Sept étapes : Catalogue, Interactions, Recommandation, Données de la réponse, Code, Automatisation et Performance. Il n’y a pas d’étape Cibler : la sélection est destinée à la personne que nomme votre requête.
1. Catalogue
Votre catalogue doit être en place et à jour. Rien ne peut être recommandé que Personyze ne connaisse pas. Chaque élément a besoin au minimum d’un ID interne, d’un titre et d’une URL, plus une image si votre mise en page en affiche une. Le catalogue se trouve dans Paramètres → Configuration des recommandations → Catalogue produits. Voir Configurer le flux de produits / de contenu.
2. Interactions
Le moteur apprend de ce que les gens font avec les produits : consultés, ajoutés au panier, achetés. Les consultations, les ajouts au panier et les achats sur votre propre site web sont suivis comme d’habitude, depuis Paramètres → Configuration des recommandations → Suivi des produits. Votre propre mise en page est un cas différent : ce n’est pas Personyze qui l’a dessinée, il ne peut donc pas voir ce qui s’y passe.
- Clics : faites passer les gens par le
click_urlrenvoyé avec chaque élément. Il ouvre le produit et enregistre le clic. - Tout ce qui se passe en dehors de votre site web, comme une consultation ou un achat dans votre application, doit être remonté par vous. Utilisez l’API REST des interactions produit.
C’est la raison la plus fréquente pour laquelle une recommandation JSON renvoie des résultats faibles ou génériques : la sélection est bien affichée, mais rien n’est remonté en retour.
3. Recommandation
Choisissez l’algorithme. Le sélecteur est le même que celui des widgets sur le site, regroupé en Personnalisés et comportementaux ; Ventes croisées, co-vues et montées en gamme ; Historique du visiteur ; Événements du catalogue ; et Personnalisé. Une requête ne provient pas d’une page de votre site : la ligne Page propose donc plutôt ce que la personne a fait :
- Général : aucun élément en particulier.
- Items they viewed : ancré à ce qu’elle a consulté.
- Items in their cart : ancré à son panier.
- Items they purchased : ancré à ce qu’elle a acheté.
De nombreux algorithmes ont leurs propres réglages, affichés sur la carte :
- Période : Récemment, Aujourd’hui, Ces 2 derniers jours, Ces 4 derniers jours, Cette dernière semaine ou Depuis toujours. Les fenêtres courtes suivent les tendances, tandis que les plus longues sont plus stables.
- Source : la partie du catalogue concernée. Par exemple, n’importe quelle catégorie, les catégories qu’elle a consultées, la catégorie de son dernier panier, ou ses centres d’intérêt déclarés.
- Trier par : Vu, Ajoutés récemment au catalogue, Achetés, Ajouté au panier, Ajouté à la liste d’envies, Bon marché, Bien notés ou Forte marge.
La carte Sortie règle le nombre d’éléments renvoyés (jusqu’à 12), les Algorithmes de repli à exécuter quand l’algorithme principal en renvoie trop peu, et Remplir les cellules vides pour compléter un résultat incomplet avec des éléments populaires. En dessous, des filtres restreignent le vivier. Vous pouvez ignorer les éléments avec lesquels la personne a déjà interagi, vous limiter à des catégories choisies ou à des éléments avec image ou prix, ou écrire des règles personnalisées sur n’importe quel champ du catalogue. Les éléments en rupture de stock sont exclus automatiquement.
Pour les algorithmes eux-mêmes, voir Algorithmes de recommandation. Voir aussi Filtres et Solutions de repli.
4. Données de la réponse
Personyze répond par un tableau JSON d’objets, un par produit, contenant les champs que vous choisissez ici. Chaque ligne associe un Field on Personyze à son Name in JSON result : vous définissez ainsi votre propre contrat de réponse. Choisissez exactement ce dont votre moteur d’affichage a besoin, et rien de plus.
Chaque produit revient aussi avec un click_url, que vous l’ayez listé ou non. Envoyez l’utilisateur vers cette URL : elle ouvre le produit et enregistre le clic, et c’est à partir d’elle que sont calculées les statistiques de consultations et de clics.
Sélection type pour un widget de produits :
[
{
"internal_id": "nw-p001",
"title": "Alpine Shell",
"price": 249,
"image_1": "https://example.test/img/alpine-shell.jpg",
"url": "https://example.test/shop/alpine-shell",
"click_url": "https://pic.personyze.com/href/k=…"
},
...
]N’importe quel champ personnalisé du catalogue peut être inclus. Si votre mise en page affiche un badge, une note ou un message de stock, associez ce champ ici plutôt que de le chercher séparément.
5. Code
L’étape Code, intitulée Request URL, vous fournit des URL prêtes à l’emploi. Elles apparaissent une fois la campagne enregistrée. Faites une requête GET sur l’une d’elles et les recommandations reviennent en JSON. Ce que vous placez à la fin indique pour qui, ou pour quoi, elles sont destinées :
| L’URL se termine par | Recommande pour |
|---|---|
/email={INSERT EMAIL HERE} |
La personne qui a cette adresse e-mail. Une adresse que Personyze n’a jamais vue crée un profil : la première requête l’enregistre donc. |
/internal_id={INSERT INTERNAL ID HERE} |
La personne désignée par votre propre ID, conservé sur son profil comme ID interne. Un ID inconnu crée lui aussi un profil. |
/u={INSERT PERSONYZE USER ID HERE} |
L’ID utilisateur numérique propre à Personyze, celui que le tracker expose sur votre site. Tout ce qui n’est pas un nombre est refusé avec Invalid parameter. |
/item_internal_id={INSERT ITEM INTERNAL ID HERE} |
Aucune personne : des produits liés à ce produit. Ce sont des éléments consultés ou achetés avec lui, ou les plus populaires de sa catégorie. |
Une cinquième URL, qui se termine par /get[]=…, ne recommande rien. Elle renvoie les champs que vous avez choisis pour les produits que vous désignez, jusqu’à 50 par requête, et sa période (1 jour, 2 jours, Semaine, Toute la période) définit la fenêtre des compteurs d’interactions que vous avez demandés.
La requête est la même depuis un backend, une application ou un modèle d’e-mail. Si votre application remonte déjà des données à Personyze via le SDK mobile, vous pouvez aussi y diffuser la sélection avec une campagne Recos produits pour apps.
6. Automatisation
Cette étape est facultative. Ajoutez des règles qui vous alertent, ou qui agissent, quand les chiffres de cette campagne franchissent un seuil. Voir Automatisation.
7. Performance
L’étape Performance affiche les Statistiques JSON API. Vu compte les recommandations servies à votre application. Cliqués compte les utilisateurs qui sont passés par un click_url renvoyé et sont arrivés sur votre site, en % de Vu. Ajouté au panier et Achetés suivent au cours de la même session, chacun en % de l’étape précédente. Les transactions, les revenus attribués et leur part dans les revenus du site figurent à côté. Cela ne reflète que ce que Personyze peut voir : sans le click_url, les clics et tout ce qui suit ne sont pas comptés. Chaque chiffre est expliqué dans Recommandations de produits et de contenu.
Remarque : il n’y a pas d’étape QA
Contrairement aux campagnes sur le site, les campagnes API JSON n’ont pas d’étape QA, car il n’y a aucun contenu rendu que le panneau pourrait prévisualiser. Validez en appelant vous-même une URL et en lisant la réponse. Vérifiez que vous obtenez le nombre d’éléments attendu, que les champs choisis sont présents et que les valeurs sont renseignées plutôt que vides. Une requête à laquelle il est impossible de répondre renvoie quand même du JSON, sous la forme {"error": "…"}. Par exemple, No recommendations for this user signifie que l’algorithme n’a rien trouvé pour cette personne et qu’aucune solution de repli n’était là pour compléter.
Voir aussi
- Les recommandations en dehors de votre site — par où commencer
- API JSON — recommandations de contenu
- L’objet products et les interactions produit de l’API REST.
- Implémenter une application de recommandations sur mesure, la voie SDK et REST pour les applications, avec un exemple complet.