Productaanbevelingen geleverd als ruwe JSON in plaats van een weergegeven widget, zodat je ze zelf kunt opmaken. Gebruik het voor een zelf ontworpen widget, een single-page app, een native app, een e-mailtemplate of elke andere plek waar jij de presentatie bepaalt en alleen de keuzes wilt. Je haalt ze op met één GET-verzoek.
In het paneel: Nieuwe campagne › App / API › JSON-API — Productaanbevelingen.
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 catalogus moet aanwezig en actueel zijn. Niets kan worden aanbevolen wat Personyze niet kent. Elk item heeft minstens een interne ID, een titel en een URL nodig, plus een afbeelding als je lay-out er een toont. De catalogus staat in Instellingen → Aanbevelingen instellen → Productcatalogus. Zie De product-/contentfeed instellen.
2. Interacties
De engine leert van wat mensen met producten doen: bekeken, in de winkelwagen gelegd, gekocht. Weergaven, toevoegingen aan de winkelwagen en aankopen op je eigen website worden zoals gewoonlijk gevolgd, via Instellingen → Aanbevelingen instellen → Producttracking. Je eigen lay-out is anders: Personyze heeft die niet getekend, dus kan het niet zien wat daar gebeurt.
- Klikken: stuur mensen via de
click_urldie bij elk item wordt meegeleverd. Die opent het product en legt de klik vast. - Alles wat buiten je website gebeurt, zoals een weergave of aankoop in je app, moet je zelf rapporteren. Gebruik daarvoor de REST API voor productinteracties.
Dit is de meest voorkomende reden dat een JSON-aanbeveling zwakke of algemene resultaten geeft: de uitvoer wordt weergegeven, maar er wordt niets teruggerapporteerd.
3. Aanbeveling
Kies het algoritme. De kiezer is dezelfde als die van widgets op de site, gegroepeerd in Gepersonaliseerd & gedragsgericht; Cross-sells, co-views & upsells; Bezoekersgeschiedenis; Catalogusgebeurtenissen; en Aangepast. Een verzoek komt niet van een pagina van je site, dus de rij Pagina biedt in plaats daarvan wat de persoon deed:
- Algemeen: geen specifiek item.
- Items they viewed: verankerd aan wat hij bekeek.
- Items in their cart: verankerd aan zijn winkelwagen.
- Items they purchased: verankerd aan wat hij kocht.
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. Kortere periodes volgen trends, langere zijn stabieler.
- Genomen uit: welk deel van de catalogus. Bijvoorbeeld elke categorie, de categorieën die hij bekeek, zijn laatste winkelwagencategorie of zijn gerapporteerde interesses.
- Sorteren op: Bekeken, Recent aan de catalogus toegevoegd, Gekocht, In winkelwagen, Op verlanglijst gezet, Goedkoop, Hoog beoordeeld of Hoge marge.
De kaart Uitvoer bepaalt hoeveel items er terugkomen (maximaal 12), Fallback-algoritmes die draaien als het hoofdalgoritme te weinig teruggeeft, en Lege cellen vullen om een kort resultaat aan te vullen met populaire items. Daaronder beperken filters de pool. Je kunt items overslaan waarmee de persoon al bezig was, beperken tot gekozen categorieën of tot items met een afbeelding of prijs, of eigen regels schrijven op elk catalogusveld. Items die niet op voorraad zijn, worden automatisch uitgesloten.
Voor de algoritmes zelf, zie Aanbevelingsalgoritmes. Zie ook Filters en Fallbacks.
4. Data in de respons
Personyze antwoordt met een JSON-array van objecten, één per product, met de velden die je hier kiest. Elke rij koppelt een Field on Personyze aan zijn Name in JSON result, zodat je je eigen responscontract bepaalt. Kies precies wat je renderer nodig heeft en niets meer.
Elk product komt ook terug met een click_url, of je die nu opneemt of niet. Stuur de gebruiker naar die URL: die opent het product en legt de klik vast, en de statistieken voor weergaven en klikken worden eruit opgebouwd.
Typische selectie voor een productwidget:
[
{
"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=…"
},
...
]Elk eigen catalogusveld kan worden opgenomen. Toont je lay-out een badge, een beoordeling of een voorraadmelding, koppel dat veld dan hier in plaats van het apart op te zoeken.
5. Code
De stap Code, met de titel Request URL, geeft je kant-en-klare URL’s. Ze verschijnen zodra de campagne is opgeslagen. Doe een GET-verzoek naar een ervan en de aanbevelingen komen terug als JSON. Wat je aan het eind zet, bepaalt voor wie, of waarvoor, ze zijn:
| URL eindigt op | Beveelt aan voor |
|---|---|
/email={INSERT EMAIL HERE} |
De persoon met dat e-mailadres. Een adres dat Personyze nog niet kent, maakt een profiel aan, dus het eerste verzoek registreert hem. |
/internal_id={INSERT INTERNAL ID HERE} |
De persoon met jouw eigen ID voor hem, opgeslagen in zijn profiel als Intern ID. Een onbekende ID maakt ook een profiel aan. |
/u={INSERT PERSONYZE USER ID HERE} |
De eigen numerieke gebruikers-ID van Personyze, de ID die de tracker op je site beschikbaar maakt. Alles behalve een getal wordt geweigerd met Invalid parameter. |
/item_internal_id={INSERT ITEM INTERNAL ID HERE} |
Geen persoon: producten die verwant zijn aan dat product. Dat zijn items die samen ermee bekeken of gekocht zijn, of de populairste in zijn categorie. |
Een vijfde URL, eindigend op /get[]=…, beveelt niets aan. Hij geeft je gekozen velden terug voor de producten die je noemt, tot 50 per verzoek, en zijn periode (1 Day, 2 Days, Week, Alle tijd) bepaalt het venster voor de interactietellers die je hebt gevraagd.
Het verzoek is hetzelfde vanuit een backend, een app of een e-mailtemplate. Rapporteert je app al via de mobiele SDK aan Personyze, dan kun je de keuzes daar ook leveren met een campagne Productaanbevelingen voor apps.
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. Geklikt telt gebruikers die via een teruggegeven click_url op je site kwamen, als % van Bekeken. In winkelwagen en Gekocht volgen in dezelfde sessie, elk als % van de stap ervoor. Transacties, toegeschreven omzet en hun aandeel in de omzet van de site staan ernaast. Het toont alleen wat Personyze kan zien: zonder de click_urlworden klikken en alles daarna niet geteld. Elk cijfer wordt uitgelegd in Product- en contentaanbevelingen.
Let op: er is geen stap QA
Anders dan campagnes op de site hebben JSON API-campagnes geen stap QA, omdat er geen weergegeven content is die het paneel kan tonen. Controleer het door zelf een URL op te vragen en het antwoord te lezen. Kijk of je het verwachte aantal items krijgt, of de gekozen velden aanwezig zijn, en of de waarden gevuld zijn in plaats van leeg. Een verzoek dat niet kan worden beantwoord, geeft nog steeds JSON terug, als {"error": "…"}. Bijvoorbeeld No recommendations for this user betekent dat het algoritme niets voor die persoon vond en dat er geen fallback was om aan te vullen.
Gerelateerd
- Aanbevelingen buiten je site — waar je begint
- JSON API — contentaanbevelingen
- Object products en productinteracties in de REST API.
- Een eigen aanbevelingsapp bouwen, de route via SDK en REST voor apps, met een uitgewerkt voorbeeld.