JSON API — contentaanbevelingen

Contentaanbevelingen geleverd als ruwe JSON in plaats van een weergegeven widget, zodat je ze in je eigen lay-out kunt weergeven. Ideaal voor een zelf ontworpen carrousel, een single-page app, een native app, een e-mailtemplate, of een blok “misschien vind je dit ook leuk” dat precies bij je eigen designsysteem moet passen. Je haalt ze op met één GET-verzoek.

In het paneel: Nieuwe campagne › App / API › JSON-API — Contentaanbevelingen.

De stappen

Zeven stappen: Catalogus, Interacties, Aanbeveling, Data in de respons, Code, Automatisering en Prestaties. Er is geen stap Doelgroep: de keuzes zijn voor wie je verzoek ook noemt.

1. Catalogus

Je contentcatalogus met artikelen, handleidingen en video’s staat in Instellingen → Aanbevelingen instellen → Artikelcatalogus. Elk item heeft een interne ID, een titel en een URL nodig, plus een afbeelding als je lay-out er een gebruikt. Categorieën en tags zijn het waard om goed in te vullen, omdat aanbevelingen dan een onderwerp kunnen volgen in plaats van alleen de algemene populariteit.

2. Interacties

De engine leert van wat mensen lezen, liken, waarop ze reageren en wat ze uitlezen. Gelezen artikelen op je eigen website worden zoals gewoonlijk gevolgd, via Instellingen → Aanbevelingen instellen → Artikeltracking. Wat er in je eigen lay-out gebeurt, is anders, omdat Personyze die niet heeft getekend:

• Klikken: stuur lezers via de click_url die bij elk artikel wordt meegeleverd. Die opent het artikel en legt de klik vast.
• Alles buiten je website, zoals een artikel dat in je app wordt gelezen, moet je zelf rapporteren via de REST API.

Dit overslaan is de gebruikelijke reden dat een JSON-contentaanbeveling iedereen dezelfde algemene lijst geeft: er is geen leesgeschiedenis om op te personaliseren.

3. Aanbeveling

Kies het algoritme. De kiezer is dezelfde als die van widgets op de site, gegroepeerd in Gepersonaliseerd & populair; Co-reads & gerelateerd; Bezoekersgeschiedenis; Catalogusgebeurtenissen; en Aangepast. Een verzoek komt niet van een pagina van je site, dus de rij Pagina biedt in plaats daarvan wat de lezer deed. Gebruik Algemeen voor keuzes zonder een specifiek artikel erachter, en Items they viewed om te volgen wat hij las.

Veel algoritmes hebben eigen instellingen, getoond op de kaart:

• Periode: Onlangs, Vandaag, In de laatste 2 dagen, In de laatste 4 dagen, In de laatste week of Ooit.
• Genomen uit: welk deel van de catalogus. Bijvoorbeeld elke categorie, de categorieën die hij las, of zijn gerapporteerde interesses.
• Sorteren op: bijvoorbeeld meest bekeken of recent aan de catalogus toegevoegd.

Geschikt voor een JSON-feed zijn onder meer Voor jou aanbevolen content, Voor jou aanbevolen content — gepubliceerd sinds het laatste bezoek, Bezoekers die dit lazen, lazen ook, Nu trending en Recent gepubliceerd. De kaart Uitvoer bepaalt hoeveel artikelen er terugkomen (maximaal 12), Fallback-algoritmes voor als het hoofdalgoritme te weinig teruggeeft, en Lege cellen vullen. Filters beperken de pool verder: sla over waarmee de lezer al bezig was, beperk tot gekozen categorieën, of schrijf eigen regels op elk veld van je feed.

Zie Aanbevelingsalgoritmes: contentaanbevelingen voor de algoritmes in detail.

4. Data in de respons

Personyze antwoordt met een JSON-array van objecten, één per artikel, met de velden die je kiest. Je bepaalt hier je eigen responscontract, dus kies precies wat je renderer nodig heeft.

Kies voor elke rij het Field on Personyze uit je catalogus en geef het de Name in JSON result die je in de uitvoer wilt. Elk artikel komt ook terug met een click_url, of je die nu opneemt of niet. Die opent de URL van het artikel en legt de klik vast. Een typische selectie voor content:

[
  {
    "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

De stap Code, met de titel Request URL, geeft je kant-en-klare URL’s zodra de campagne is opgeslagen. Doe een GET-verzoek naar een ervan en de aanbevelingen komen terug als JSON:

Een vijfde URL, eindigend op /get[]=…, geeft je gekozen velden terug voor de artikelen die je noemt (tot 50) en beveelt niets aan. Het verzoek is hetzelfde vanuit een backend, een app of een e-mailtemplate. Voor een app die de mobiele SDK al gebruikt, levert een campagne Contentaanbevelingen voor apps de keuzes daar.

6. Automatisering

Deze stap is optioneel. Voeg regels toe die je waarschuwen, of actie ondernemen, als de cijfers van deze campagne een grens overschrijden. Zie Automatisering.

7. Prestaties

De stap Prestaties toont JSON API-statistieken. Bekeken telt de aanbevelingen die aan je applicatie zijn geleverd. Interactie telt lezers die via een teruggegeven click_url op je site kwamen, als % van Bekeken. Geconverteerd telt wie daarna in dezelfde sessie je contentdoel bereikte. Het kan alleen tellen wat Personyze bereikt: klikken die de click_url overslaan, ontbreken, dus de cijfers geven minder weer dan wat de aanbeveling echt deed. Wat elk cijfer betekent: Contentaanbevelingen.

Let op: er is geen stap QA

JSON API-campagnes hebben geen stap QA, omdat er geen weergegeven content is om te tonen. Controleer het door een URL op te vragen en het antwoord zelf te bekijken: het juiste aantal items, de gekozen velden aanwezig, en waarden die gevuld zijn in plaats van leeg. Een verzoek dat niet kan worden beantwoord, geeft {"error": "…"}terug, bijvoorbeeld No recommendations for this user.

Gerelateerd

• Aanbevelingen buiten je site — waar je begint
• JSON API — productaanbevelingen
• Wizard Contentaanbevelingen: de versie met een weergegeven widget.
• Het object articles in de REST API.