API JSON — recommandations de contenu

Des recommandations de contenu livrées en JSON brut au lieu d’un widget prêt à afficher, pour que vous les affichiez dans votre propre mise en page. Idéal pour un carrousel au design sur mesure, une application monopage, une application native, un modèle d’e-mail, ou un bloc « vous aimerez aussi » qui doit correspondre exactement à votre propre design system. Vous les récupérez avec une seule requête GET.

Dans le panneau : Nouvelle campagne › App / API › API JSON — Recos de contenu.

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 de contenu (articles, guides et vidéos) se trouve dans Paramètres → Configuration des recommandations → Catalogue d’articles. Chaque élément a besoin d’un ID interne, d’un titre et d’une URL, plus une image si votre mise en page en utilise une. Les catégories et les tags méritent d’être correctement renseignés, car ils permettent aux recommandations de suivre un sujet plutôt que la seule popularité globale.

2. Interactions

Le moteur apprend de ce que les gens lisent, aiment, commentent et terminent. Les lectures sur votre propre site web sont suivies comme d’habitude, depuis Paramètres → Configuration des recommandations → Suivi des articles. Ce qui se passe dans votre propre mise en page est différent, car ce n’est pas Personyze qui l’a dessinée :

Clics : faites passer les lecteurs par le click_url renvoyé avec chaque article. Il ouvre l’article et enregistre le clic.
Tout ce qui se passe en dehors de votre site web, comme un article lu dans votre application, doit être remonté par vous via l’API REST.

Négliger cette étape est la raison habituelle pour laquelle une recommandation de contenu JSON renvoie la même liste générique à tout le monde : elle n’a aucun historique de lecture sur lequel s’appuyer pour personnaliser.

3. Recommandation

Choisissez l’algorithme. Le sélecteur est le même que celui des widgets sur le site, regroupé en Personnalisés et populaires ; Co-lectures et similaires ; 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 le lecteur a fait. Utilisez Général pour une sélection sans article particulier derrière, et Items they viewed pour suivre ce qu’il a lu.

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.
Source : la partie du catalogue concernée. Par exemple, n’importe quelle catégorie, les catégories qu’il a lues, ou ses centres d’intérêt déclarés.
Trier par : par exemple, les plus consultés ou les plus récemment ajoutés au catalogue.

Parmi ceux qui conviennent à un flux JSON : Contenu recommandé pour vous, Contenu recommandé pour vous — publié depuis la dernière visite, Les visiteurs qui ont lu ceci ont aussi lu, Tendances du moment et Publiés récemment. La carte Sortie règle le nombre d’articles renvoyés (jusqu’à 12), les Algorithmes de repli pour les cas où l’algorithme principal en renvoie trop peu, et Remplir les cellules vides. Les filtres restreignent encore le vivier : ignorer ce avec quoi le lecteur a déjà interagi, se limiter à des catégories choisies, ou écrire des règles personnalisées sur n’importe quel champ de votre flux.

Voir Algorithmes de recommandation : recommandations de contenu pour le détail des algorithmes.

4. Données de la réponse

Personyze répond par un tableau JSON d’objets, un par article, contenant les champs que vous sélectionnez. Vous définissez ici votre propre contrat de réponse : choisissez donc exactement ce dont votre moteur d’affichage a besoin.

Pour chaque ligne, choisissez le Field on Personyze dans votre catalogue et donnez-lui le Name in JSON result que vous voulez dans la sortie. Chaque article revient aussi avec un click_url, que vous l’ayez listé ou non. Il ouvre l’URL de l’article et enregistre le clic. Une sélection type pour du contenu :

[
  {
    "internal_id": "nw-a001",
    "title": "How to layer for winter hiking",
    "category": "Skills",
    "image_1": "https://example.test/img/layering.jpg",
    "url": "https://example.test/journal/how-to-layer-for-winter-hiking",
    "click_url": "https://pic.personyze.com/href/k=…"
  },
  ...
]

5. Code

L’étape Code, intitulée Request URL, vous fournit des URL prêtes à l’emploi une fois la campagne enregistrée. Faites une requête GET sur l’une d’elles et les recommandations reviennent en JSON :

L’URL se termine par	Recommande pour
`/email={INSERT EMAIL HERE}`	Le lecteur qui a cette adresse e-mail. Une adresse que Personyze n’a jamais vue crée un profil.
`/internal_id={INSERT INTERNAL ID HERE}`	Le lecteur désigné par votre propre ID, conservé sur son profil comme ID interne.
`/u={INSERT PERSONYZE USER ID HERE}`	L’ID utilisateur numérique de Personyze, tel que le tracker l’expose sur votre site.
`/item_internal_id={INSERT ITEM INTERNAL ID HERE}`	Aucun lecteur : des articles liés à cet article. Ce sont des articles lus avec lui, ou les plus populaires de sa rubrique.

Une cinquième URL, qui se termine par /get[]=…, renvoie les champs que vous avez choisis pour les articles que vous désignez (jusqu’à 50) et ne recommande rien. La requête est la même depuis un backend, une application ou un modèle d’e-mail. Pour une application qui utilise déjà le SDK mobile, une campagne Recos de contenu pour apps y diffuse la sélection.

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. Engagé compte les lecteurs qui sont passés par un click_url renvoyé et sont arrivés sur votre site, en % de Vu. Converti compte ceux qui ont ensuite atteint votre objectif de contenu au cours de la même session. Seul ce qui parvient à Personyze peut être compté : les clics qui contournent le click_url manquent, si bien que les chiffres sous-estiment ce qu’a accompli la recommandation. Ce que signifie chaque chiffre : Recommandations de contenu.

Remarque : il n’y a pas d’étape QA

Les campagnes API JSON n’ont pas d’étape QA, car il n’y a aucun contenu rendu à prévisualiser. Validez en appelant une URL et en vérifiant vous-même la réponse : le bon nombre d’éléments, la présence des champs sélectionnés, et des valeurs renseignées plutôt que vides. Une requête à laquelle il est impossible de répondre renvoie {"error": "…"}, par exemple No recommendations for this user.

Voir aussi

Les recommandations en dehors de votre site — par où commencer
API JSON — recommandations de produits
Assistant de recommandations de contenu : la version sous forme de widget affiché.
Objet articles de l’API REST.