> ## 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.
# Intégration personnalisée
> Appelez directement l'API Strategies pour alimenter des expériences de boutique personnalisées - carrousels PDP, upsells de panier personnalisés, et partout où les surfaces natives d'Aftersell n'arrivent pas.
## Aperçu
Lorsque ni les surfaces natives d'Aftersell (post-achat, checkout, Upcart) ni une intégration packagée ne conviennent, vous pouvez appeler vous-même l'API Strategies depuis votre thème Shopify et afficher les produits renvoyés comme bon vous semble.
Le schéma est le même dans tous les cas : construisez une charge utile de contexte depuis Liquid (afin que les attributs Shopify comme le produit actuel, le contenu du panier et les champs client soient remplis au moment du rendu), envoyez-la en `POST` à `/api/public/strategy/evaluate`, et affichez la réponse.
Cette page couvre deux schémas d'implémentation :
* **Contexte PDP** — déposez une section sur les pages produit qui appelle l'API avec le **produit actuellement consulté** et affiche un carrousel des recommandations renvoyées.
* **Contexte panier** — affichez un bloc d'upsell dans un panier personnalisé qui appelle l'API avec **toutes les lignes d'articles actuelles du panier** et affiche les produits renvoyés.
C'est la forme du **contexte produit** qui diffère entre les deux : un seul produit sur la PDP, un tableau de toutes les lignes d'articles dans le panier.
***
## Ce dont vous aurez besoin
1. **Votre clé API Strategy.** Dans Aftersell, accédez à **Settings → Product Strategy** et, dans la carte **Security Token**, copiez votre jeton (c'est votre clé API Strategy).
2. **Le Strategy ID.** Ouvrez la Strategy que vous souhaitez exécuter dans l'éditeur de Strategy d'Aftersell et copiez son ID.
3. **L'accès au code du thème.** Vous ajouterez une section Liquid (PDP) ou un bloc (panier personnalisé) à votre thème Shopify — Online Store → Themes → ... → Edit code.
Votre clé API Strategy se trouve dans le code de thème côté client, ce qui la rend visible pour quiconque consulte le code source de la page. Traitez-la comme un identifiant public de boutique et régénérez-la depuis Aftersell **Settings → Product Strategy** si elle est un jour exposée d'une manière non souhaitée.
***
## Contexte PDP : extrait de section
Ce schéma ajoute une section Shopify à votre page produit. Au rendu de la page, Liquid intègre les attributs du produit actuel, du panier et du client dans la charge utile, puis JavaScript envoie une requête à l'API Strategies et affiche les produits renvoyés dans un carrousel Splide.
### Installation
1. Dans votre admin Shopify, accédez à **Online Store → Themes**, cliquez sur **...** sur votre thème et sélectionnez **Edit code**.
2. Dans le dossier **Sections**, créez un nouveau fichier nommé `aftersell-upsell-carousel.liquid`.
3. Collez l'extrait ci-dessous dans le nouveau fichier et remplacez `YOUR_STRATEGY_API_KEY` par la clé API provenant d'Aftersell.
4. Enregistrez.
5. Ouvrez votre template produit (généralement `templates/product.json` ou `sections/main-product.liquid`) et ajoutez la section **Aftersell Carousel** là où vous souhaitez que le carrousel apparaisse. Depuis l'éditeur de thème, vous pouvez aussi la faire glisser directement sur la page produit.
6. Dans les paramètres de la section, collez votre **Strategy ID**.
### Ce que la section envoie
Pour chaque affichage de PDP, la charge utile inclut :
* **products** — un tableau à un seul élément contenant le produit actuellement consulté (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
* **cart** — sous-total, nombre d'articles, nombre de lignes du panier actuel de l'acheteur (omis si le panier est vide).
* **cartToken** — pour que l'API puisse rattacher cette évaluation à la même session.
* **customer** — tags, pays, province, locale, nombre de commandes, total dépensé et indicateur d'acceptation du marketing, mais **uniquement si l'acheteur est connecté**.
* **session** — code de devise provenant de `shop.currency`.
La section n'envoie pas les paramètres UTM par défaut. Si vous souhaitez un ciblage basé sur les UTM sur la PDP, capturez-les côté client et ajoutez-les à l'objet `session` avant le fetch.
### L'extrait
```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' }}
Le schéma de la section expose quatre paramètres modifiables par le marchand : **Strategy ID**, **Heading**, **CTA Button Label** et **Max Products to Show**. Ajoutez ou retirez des paramètres dans le bloc `{% schema %}` pour exposer davantage de réglages dans l'éditeur de thème.
Le CSS est isolé sous des noms de classes `.aftersell-*` et inclut un carrousel Splide à 4 éléments qui passe à 2 éléments à 768 px et à 1 élément à 480 px. Modifiez-le librement pour l'adapter à votre thème — rien de tout cela n'est requis pour que l'appel API fonctionne.
***
## Contexte panier : bloc d'upsell de panier personnalisé
Ce schéma est structurellement identique à celui de la PDP, avec une différence clé : le **tableau de contexte produit** est construit à partir des lignes d'articles du panier plutôt qu'à partir du produit actuellement consulté. La Strategy reçoit alors chaque article ajouté par l'acheteur et renvoie des recommandations basées sur le panier dans son ensemble.
L'implémentation se trouve là où réside le code de votre panier personnalisé — une section Liquid qui affiche le tiroir de panier, un bloc personnalisé dans une boutique headless, ou un template de thème comme `cart.liquid`. La forme de l'appel API et le traitement de la réponse sont identiques à l'exemple PDP — seul le tableau `products` diffère.
La structure ressemble à ceci :
```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
};
});
```
Le reste de la charge utile (cart, customer, session, cartToken) et l'appel `fetch` à `/api/public/strategy/evaluate` sont inchangés par rapport au schéma PDP ci-dessus — seul le tableau `products` passe de `[productContext]` au tableau dérivé du panier.
***
## Ce qui se passe quand la Strategy renvoie un résultat
La forme de la réponse est la même quel que soit le contexte envoyé :
```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": {} }
}
```
L'`evaluationId` est un identifiant unique pour cette évaluation. Si vous le capturez et l'attachez aux produits que vous affichez, vous pouvez attribuer la commande résultante à la recommandation exacte qui l'a produite — voir [Attribution](#attribution) ci-dessous.
La manière dont vous affichez le tableau `products` dépend entièrement du code de votre thème. L'extrait PDP ci-dessus les affiche sous forme de carrousel de cartes avec sélecteurs de variantes et boutons d'ajout au panier ; un bloc de panier personnalisé pourrait les afficher en liste verticale dans le tiroir.
Pour le schéma complet de requête et de réponse, consultez la [référence de l'API Evaluate Strategy](/fr/aftersell/strategies_api_reference_evaluate_strategy).
***
## Quand aucun produit n'est renvoyé
Si la Strategy ne renvoie aucun produit (`products: []`), c'est à votre code de décider comment gérer la situation. L'extrait PDP ci-dessus masque entièrement le carrousel. Un bloc de panier personnalisé pourrait se rabattre sur la liste d'upsells par défaut du panier, ou simplement ne rien afficher.
Pour éviter une réponse vide, configurez un **Catch all** dans la Strategy afin qu'il y ait toujours un produit de repli à renvoyer. Consultez la page [Construire des Strategies](/fr/aftersell/strategies_building_in_app) pour savoir comment configurer un Catch all.
***
## Conseils pour les intégrations personnalisées
* **Construisez le contexte en Liquid.** Liquid s'exécute au moment du rendu et a accès à l'ensemble du graphe d'objets Shopify — produit, panier, client, boutique, requête. Utilisez-le pour remplir la charge utile côté serveur plutôt que de recourir à des appels côté client.
* **Gardez la clé API hors des dépôts publics.** Elle finira dans le code de votre thème, qui est envoyé au navigateur — c'est acceptable. Mais ne collez pas le même thème dans un dépôt public et ne partagez pas le bundle en externe.
* **Utilisez un Catch all.** Les expériences de boutique semblent cassées quand un emplacement disparaît. Un Catch all avec un petit ensemble de valeurs par défaut sûres garde l'interface cohérente.
* **Mettez en cache là où c'est pertinent.** L'API Strategies effectue une mise en cache légère côté serveur (`meta.servedFromCache`), mais pour les PDP à fort trafic, vous pouvez aussi vouloir temporiser (debounce) ou mémoïser les appels côté client (par ex. ne pas rappeler l'API lorsque le même produit est affiché deux fois dans une session).
***
## Attribution
Lorsqu'un acheteur clique sur le bouton d'ajout au panier dans l'extrait, l'appel `/cart/add.js` attache des **propriétés de ligne d'article** à l'article du panier :
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "Aftersell",
"_attribution": "CTA"
}
```
Ces propriétés accompagnent la ligne d'article jusqu'à la commande Shopify, où elles apparaissent sur l'enregistrement de la ligne. Vous pouvez les utiliser en aval pour attribuer les revenus, filtrer les commandes ou alimenter des outils d'analyse qui lisent les propriétés de lignes d'articles.
Les clés et les valeurs sont des conventions, pas des exigences — l'appel API fonctionne de la même manière quel que soit leur contenu. Modifiez-les pour les adapter à votre propre modèle d'attribution. Par exemple :
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "PDP Carousel",
"_strategy_id": "{{ section.settings.strategy_id }}",
"_campaign": "summer-2026"
}
```
Les clés de propriété qui commencent par un underscore (`_`) sont masquées dans l'interface du panier et du checkout mais restent attachées à la commande. Utilisez le préfixe underscore pour les métadonnées d'attribution que vous ne voulez pas montrer aux acheteurs.
Appliquez le même schéma dans l'implémentation en contexte panier — tout appel d'ajout au panier effectué depuis un bloc d'upsell personnalisé peut transporter les propriétés dont vous avez besoin.
### Attribuer à l'évaluation d'origine
Pour relier une commande à l'**évaluation exacte** qui a recommandé le produit — plutôt qu'à un simple « provient d'une Strategy » — capturez l'`evaluationId` de la réponse et attachez-le à la ligne d'article sous la propriété `__as_offer_id`. AfterSell lit cette clé, donc les commandes qui la portent sont attribuées à l'évaluation spécifique dans les rapports.
Dans le gestionnaire `evaluate()`, conservez l'identifiant de la réponse :
```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));
})
```
Puis incluez-le dans les propriétés d'ajout au panier :
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: Object.assign(
{ "_source": "Aftersell", "_attribution": "CTA" },
evaluationId ? { "__as_offer_id": evaluationId } : {}
)
```
Conservez le double underscore sur `__as_offer_id` — c'est la clé qu'AfterSell recherche, et le préfixe underscore la garde masquée pour les acheteurs. Si `evaluationId` est absent (par exemple, aucun produit n'a été renvoyé), omettez la propriété plutôt que d'envoyer une valeur vide.
