> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom integratie
> Roep de Strategies API rechtstreeks aan om custom storefront-ervaringen aan te sturen - PDP-carrousels, custom cart-upsells en overal waar de eigen surfaces van Aftersell niet reiken.
## Overzicht
Wanneer noch de eigen surfaces van Aftersell (post-purchase, checkout, Upcart), noch een kant-en-klare integratie past, kun je de Strategies API zelf aanroepen vanuit je Shopify-thema en de geretourneerde producten weergeven zoals jij dat wilt.
Het patroon is in elk geval hetzelfde: bouw een contextpayload vanuit Liquid (zodat Shopify-attributen zoals het huidige product, de winkelwageninhoud en klantvelden bij het renderen worden ingevuld), `POST` deze naar `/api/public/strategy/evaluate` en render het antwoord.
Deze pagina behandelt twee implementatiepatronen:
* **PDP-context** - plaats een sectie op productpagina's die de API aanroept met het **momenteel bekeken product** en een carrousel van geretourneerde aanbevelingen weergeeft.
* **Cart-context** - render een upsellblok binnen een custom winkelwagen die de API aanroept met **alle huidige regelitems in de winkelwagen** en de geretourneerde producten weergeeft.
De vorm van de **productcontext** is wat tussen de twee verschilt: één product op de PDP, een array van alle regelitems in de winkelwagen.
***
## Wat je nodig hebt
1. **Je Strategy API-sleutel.** Ga in Aftersell naar **Settings → Product Strategy** en kopieer in de kaart **Security Token** je token (dit is je Strategy API-sleutel).
2. **De Strategy-ID.** Open de Strategy die je wilt uitvoeren in de Aftersell Strategy-editor en kopieer de ID.
3. **Toegang tot themacode.** Je voegt een Liquid-sectie (PDP) of blok (custom winkelwagen) toe aan je Shopify-thema - Online Store → Themes → ... → Edit code.
Je Strategy API-sleutel staat in client-side themacode, waardoor deze zichtbaar is voor iedereen die de paginabron bekijkt. Behandel deze als een publieke storefront-credential en roteer de sleutel via Aftersell **Settings → Product Strategy** als deze ooit op een onbedoelde manier wordt blootgesteld.
***
## PDP-context: sectiesnippet
Dit patroon voegt een Shopify-sectie toe aan je productpagina. Wanneer de pagina rendert, sluit Liquid het huidige product, de winkelwagen en de klantattributen in de payload in, waarna JavaScript naar de Strategies API post en de geretourneerde producten in een Splide-carrousel weergeeft.
### Installeren
1. Ga in je Shopify-beheer naar **Online Store → Themes**, klik op **...** bij je thema en selecteer **Edit code**.
2. Maak in de map **Sections** een nieuw bestand aan met de naam `aftersell-upsell-carousel.liquid`.
3. Plak de onderstaande snippet in het nieuwe bestand en vervang `YOUR_STRATEGY_API_KEY` door de API-sleutel uit Aftersell.
4. Sla op.
5. Open je producttemplate (meestal `templates/product.json` of `sections/main-product.liquid`) en voeg de sectie **Aftersell Carousel** toe waar je de carrousel wilt laten verschijnen. Vanuit de thema-editor kun je deze ook rechtstreeks op de productpagina slepen.
6. Plak in de instellingen van de sectie je **Strategy-ID**.
### Wat de sectie verstuurt
Voor elke PDP-weergave bevat de payload:
* **products** - een array met één element dat het momenteel bekeken product bevat (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
* **cart** - subtotaal, aantal items, aantal regels van de huidige winkelwagen van de shopper (weggelaten als de winkelwagen leeg is).
* **cartToken** - zodat de API deze evaluatie aan dezelfde sessie kan koppelen.
* **customer** - tags, land, provincie, taalinstelling, aantal bestellingen, totaal besteed en de accepts-marketing-vlag, maar **alleen als de shopper is ingelogd**.
* **session** - valutacode uit `shop.currency`.
De sectie stuurt standaard geen UTM-parameters mee. Als je op UTM gebaseerde targeting op de PDP wilt, leg deze dan client-side vast en voeg ze toe aan het `session`-object vóór de fetch.
### De snippet
```liquid theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{% comment %}
Aftersell Carousel (Splide)
Type: Section — save to sections/aftersell-upsell-carousel.liquid
{% endcomment %}
{% if product %}
{{ section.settings.heading | default: 'You might also like' }}
Het sectieschema biedt vier door de merchant bewerkbare instellingen: **Strategy ID**, **Heading**, **CTA Button Label** en **Max Products to Show**. Voeg instellingen toe of verwijder ze in het `{% schema %}`-blok om meer knoppen aan de thema-editor beschikbaar te stellen.
De CSS is gescoped onder `.aftersell-*`-klassenamen en bevat een door Splide aangedreven carrousel met 4 items, die terugvalt naar 2 items bij 768px en 1 item bij 480px. Pas deze vrij aan om bij je thema te passen - niets ervan is vereist om de API-aanroep te laten werken.
***
## Cart-context: custom cart-upsellblok
Dit patroon is structureel hetzelfde als het PDP-patroon, met één belangrijk verschil: de **productcontext-array** wordt opgebouwd uit de regelitems van de winkelwagen in plaats van het momenteel bekeken product. De Strategy ontvangt dan elk item dat de shopper heeft toegevoegd en retourneert aanbevelingen op basis van de winkelwagen als geheel.
De implementatie leeft waar je custom winkelwagencode leeft - een Liquid-sectie die de cart drawer rendert, een custom blok in een headless storefront, of een thematemplate zoals `cart.liquid`. De vorm van de API-aanroep en de responseverwerking zijn identiek aan het PDP-voorbeeld - alleen de `products`-array verschilt.
De structuur ziet er als volgt uit:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
var products = {{ cart.items | json }}.map(function(item) {
return {
productId: 'gid://shopify/Product/' + item.product_id,
variantId: 'gid://shopify/ProductVariant/' + item.variant_id,
quantity: item.quantity,
price: item.price / 100
// ...other fields as needed
};
});
```
De rest van de payload (cart, customer, session, cartToken) en de `fetch`-aanroep naar `/api/public/strategy/evaluate` zijn ongewijzigd ten opzichte van het PDP-patroon hierboven - alleen de `products`-array wisselt van `[productContext]` naar de uit de winkelwagen afgeleide array.
***
## Wat er gebeurt wanneer de Strategy een resultaat geeft
De vorm van de response is hetzelfde, ongeacht welke context je hebt verstuurd:
```json theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{
"success": true,
"products": [ /* enriched recommended products */ ],
"evaluationId": "f3a1c2e0-...",
"resolution": { "strategyId": "...", "matchedRuleIds": [...], "fallbackUsed": false },
"meta": { "servedFromCache": false, "processingTimeMs": 12, "data": {} }
}
```
De `evaluationId` is een unieke id voor deze evaluatie. Als je deze vastlegt en koppelt aan de producten die je rendert, kun je de resulterende bestelling terugkoppelen aan de exacte aanbeveling die deze heeft opgeleverd - zie [Attributie](#attribution) hieronder.
Hoe je de `products`-array rendert, is volledig aan je themacode. De PDP-snippet hierboven rendert ze als een carrousel van kaarten met variantkiezers en toevoegen-aan-winkelwagen-knoppen; een custom cart-blok zou ze als een verticale lijst binnen de drawer kunnen renderen.
Zie voor het volledige request- en responseschema de [Evaluate Strategy API-referentie](/nl/aftersell/strategies_api_reference_evaluate_strategy).
***
## Wanneer er geen product wordt geretourneerd
Als de Strategy geen producten retourneert (`products: []`), is het aan je code hoe je hiermee omgaat. De PDP-snippet hierboven verbergt de carrousel volledig. Een custom cart-blok zou kunnen terugvallen op de standaard upselllijst van de winkelwagen, of simpelweg niets renderen.
Om een lege response te voorkomen, configureer je een **Catch all** in de Strategy, zodat er altijd een terugvalproduct is om te retourneren. Zie de pagina [Strategies bouwen](/nl/aftersell/strategies_building_in_app) voor het instellen van een Catch all.
***
## Tips voor custom integraties
* **Bouw de context in Liquid.** Liquid draait op het moment van renderen en heeft toegang tot de volledige Shopify-objectgraaf - product, winkelwagen, klant, winkel, request. Gebruik het om de payload server-side te vullen in plaats van naar client-side aanroepen te grijpen.
* **Houd de API-sleutel uit publieke repositories.** De sleutel komt in je themacode terecht, die naar de browser wordt verzonden - dat is prima. Maar plak hetzelfde thema niet in een publieke repository en deel de bundel niet extern.
* **Gebruik een Catch all.** Storefront-ervaringen ogen kapot wanneer een slot verdwijnt. Een Catch all met een kleine set veilige standaardproducten houdt de UI consistent.
* **Cache waar het zinvol is.** De Strategies API doet lichte caching server-side (`meta.servedFromCache`), maar voor PDP's met veel verkeer wil je aanroepen mogelijk ook debounce of memoizeren op de client (bijv. niet opnieuw aanroepen wanneer hetzelfde product twee keer in een sessie wordt gerenderd).
***
## Attributie
Wanneer een shopper op de toevoegen-aan-winkelwagen-knop in de snippet klikt, voegt de `/cart/add.js`-aanroep **line item properties** toe aan het winkelwagenitem:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "Aftersell",
"_attribution": "CTA"
}
```
Deze properties reizen met het regelitem mee tot aan de Shopify-bestelling, waar ze op het regelitemrecord verschijnen. Je kunt ze verderop gebruiken om omzet toe te schrijven, bestellingen te filteren of analysetools te voeden die line item properties lezen.
De sleutels en waarden zijn conventies, geen vereisten - de API-aanroep werkt hetzelfde ongeacht wat je hier invult. Pas ze aan aan je eigen attributiemodel. Bijvoorbeeld:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "PDP Carousel",
"_strategy_id": "{{ section.settings.strategy_id }}",
"_campaign": "summer-2026"
}
```
Property-sleutels die met een underscore (`_`) beginnen, zijn verborgen in de winkelwagen- en checkout-UI, maar worden nog steeds aan de bestelling gekoppeld. Gebruik de underscore-prefix voor metadata die alleen voor attributie is en die je niet aan shoppers wilt tonen.
Pas hetzelfde patroon toe in de cart-context-implementatie - elke toevoegen-aan-winkelwagen-aanroep die je vanuit een custom upsellblok doet, kan alle properties bevatten die je nodig hebt.
### Terugkoppelen naar de evaluatie
Om een bestelling terug te koppelen aan de **exacte evaluatie** die het product heeft aanbevolen - in plaats van alleen "kwam van een Strategy" - leg je de `evaluationId` uit de response vast en koppel je deze aan het regelitem onder de property `__as_offer_id`. AfterSell leest deze sleutel, zodat bestellingen die ermee zijn getagd in de rapportage aan de specifieke evaluatie worden toegeschreven.
Houd in de `evaluate()`-handler de id uit de response vast:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.then(function(data) {
if (!data || !data.success || !data.products || !data.products.length) {
clearSkeletons(); return;
}
evaluationId = data.evaluationId; // declare `var evaluationId;` alongside your other state
renderCards(data.products.slice(0, MAX_PRODUCTS));
})
```
Neem deze vervolgens op in de toevoegen-aan-winkelwagen-properties:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: Object.assign(
{ "_source": "Aftersell", "_attribution": "CTA" },
evaluationId ? { "__as_offer_id": evaluationId } : {}
)
```
Behoud de dubbele underscore in `__as_offer_id` - het is de sleutel waar AfterSell naar zoekt, en de underscore-prefix houdt deze verborgen voor shoppers. Als `evaluationId` ontbreekt (bijvoorbeeld omdat er geen producten zijn geretourneerd), sla de property dan over in plaats van een lege waarde te versturen.
