FAQ

Nascondi lo slider delle categorie #

Quando una Recommendation di Clerk.io viene aggiunta a una pagina categoria che contiene pochi prodotti, verranno mostrati gli stessi prodotti già presenti sulla pagina.

Per evitarlo, puoi nascondere la Recommendation nelle pagine categoria aggiungendo un’istruzione if nel codice di design della Recommendation.

Modifica il numero nell’istruzione if in base al numero minimo di prodotti necessari per mostrare la Recommendation.

{% if products.length > 7 %}
 
 <!-- Recommendation code -->

{% endif %}

Ad esempio:

{% if products.length > 7 %}
<div class="clerk-wrapper">
    <div class="clerk-headline-wrapper">
        <h2 class="clerk-headline">{{headline}}</h2>
    </div>
    <div class="clerk-slider-wrapper">
        <div class="clerk-slider">
            {% for item in products %}
            <div class="clerk-slider-content">
                <!-- START PRODUCT CARD -->
                <!-- END PRODUCT CARD -->
            </div>
            {% endfor %}
        </div>
    </div>
</div>
{% endif %}

Questo metodo nasconde solo lo slider, ma viene comunque conteggiato nel tuo utilizzo delle Recommendation. Per alcune categorie, questa soluzione è sufficiente.

Tuttavia, se hai molte categorie con pochi prodotti, ti consigliamo di bloccare l’iniezione dello slider a livello server.

Consiglia prodotti compatibili #

L’intelligenza artificiale di Clerk consiglia prodotti basandosi su ciò che è più probabile venga acquistato insieme. Questo funziona bene per la maggior parte dei negozi, ma alcuni cataloghi contengono prodotti che devono essere fisicamente o tecnicamente compatibili — come parti di auto, componenti elettronici o pezzi di ricambio per macchinari.

In questi casi, la popolarità di un prodotto non è sufficiente. Deve anche adattarsi al prodotto che il cliente sta visualizzando.

La soluzione è etichettare i prodotti con attributi che definiscono la compatibilità, e poi utilizzare il filtro dinamico per limitare le Recommendation solo ai prodotti corrispondenti.

L’intelligenza artificiale di Clerk determinerà comunque quali prodotti mostrare, ma solo all’interno del sottoinsieme che supera il filtro. In questo modo ottieni il meglio di entrambi i mondi — ranking intelligente all’interno di una selezione compatibile.

Aggiungere attributi #

Gli attributi necessari dipendono da come funziona la compatibilità nel tuo catalogo. Devono essere sincronizzati con Clerk come parte dei dati di prodotto, tramite l’integrazione o via API.

Puoi verificare che i tuoi attributi siano disponibili navigando su Data > Products e selezionando un prodotto qualsiasi.

Ecco tre pattern comuni, dal più semplice al più avanzato.

Attributo singolo #

Se tutti i prodotti dello stesso vendor sono garantiti compatibili, aggiungi il vendor come attributo su ogni prodotto. Poi filtra le Recommendation per mostrare solo prodotti con lo stesso vendor.

Nel codice di embed, definisci una variabile con il vendor del prodotto attuale e usala come filtro:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter="vendor = $product_vendor">
</span>

var product_vendor = "ACME Corp";

In questo modo, un cliente che sta visualizzando un prodotto di ACME Corp vedrà solo Recommendation dello stesso vendor.

Attributi multipli #

A volte un solo attributo non basta. Ad esempio, una parte di auto potrebbe dover corrispondere sia al make che al model di un veicolo.

Puoi combinare più condizioni in un unico filtro:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter="make = $product_make and model = $product_model">
</span>

var product_make = "Toyota";
var product_model = "Corolla";

Solo i prodotti che corrispondono sia al make che al model verranno mostrati.

Gruppi di compatibilità #

Nei cataloghi più complessi, ogni prodotto ha una lista unica di altri prodotti compatibili, e questo non può essere gestito solo con attributi condivisi.

La soluzione è calcolare un identificatore di gruppo in base all’insieme degli ID dei prodotti compatibili, e salvarlo come attributo. I prodotti che condividono lo stesso gruppo di compatibilità avranno lo stesso identificatore, consentendo il filtraggio.

Ad esempio, se i prodotti A, B e C sono tutti compatibili tra loro, potresti calcolare un hash partendo dagli ID ordinati e salvarlo come attributo compatibility_group su ciascuno. Poi puoi filtrare così:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter='compatibility_group = $product_group'>
</span>

var product_group = "a1b2c3d4";

Questo approccio funziona bene quando le relazioni di compatibilità derivano da un database esterno o un PIM. L’hash dovrebbe essere ricalcolato ogni volta che cambiano i dati di compatibilità e sincronizzato con Clerk insieme agli altri dati di prodotto.

Suggerimento: Se un prodotto può appartenere a più gruppi di compatibilità, salva gli identificatori come attributo lista e usa l’operatore in invece di =. Puoi saperne di più sulla sintassi dei filtri.

Scegliere l’approccio giusto #

Inizia con l’approccio più semplice che copre il tuo caso d’uso. Puoi sempre aggiungere altri attributi in seguito se hai bisogno di un controllo più preciso.

Per approfondire tutti i modi in cui puoi usare i filtri nei codici embed, vedi Dynamic Filtering.

Mostrare Recommendation in un sidecart dinamico #

Un sidecart è un carrello a scomparsa, minicart, overlay del carrello o altra interfaccia che si apre e si aggiorna senza caricare una nuova pagina. L’HTML può cambiare quando un visitatore aggiunge un prodotto, lo rimuove o ne modifica la quantità.

Le Recommendation in questo tipo di carrello devono seguire lo stato live del carrello. Un’injection normale che viene visualizzata al caricamento della pagina non è sufficiente. L’implementazione deve coordinare il sidecart, gli eventi del carrello, l’Element di Clerk.io e il design della Recommendation.

Prima di iniziare #

Ispeziona il sidecart live prima di creare l’Element o scrivere lo script di design. Prendi nota del container del sidecart, dell’area dei contenuti, del selettore e attributo dell’ID prodotto, dell’indicatore di caricamento, degli eventi di aggiornamento del carrello e se gli aggiornamenti sostituiscono solo il corpo del sidecart o l’intero container.

Non copiare selettori, attributi o eventi da un altro negozio. Il markup dei sidecart varia da tema a plugin. Usa gli eventi del carrello già presenti sulla piattaforma, quando sono affidabili; altrimenti, usa il più piccolo MutationObserver filtrato necessario per rilevare le modifiche al carrello. Evita di osservare tutto il body senza filtri, perché il markup renderizzato da Clerk.io può riattivare l’osservatore.

Crea l’Element #

Crea un Element dedicato per il sidecart. Usa l’API recommendations/complementary e la logica Best Cross-Sell Products. Configuralo per leggere gli ID prodotto dal carrello live, escludere i prodotti già nel carrello e restituire da quattro a otto prodotti.

La configurazione preferibile è passare gli ID del carrello nelle impostazioni dell’Element: imposta l’API su recommendations/complementary, il tipo di ID prodotto su products, la sorgente dell’ID sull’Element, e imposta selettore e attributo di ID sui valori individuati nel sidecart.

Se il sidecart non contiene i suoi ID prodotto quando Clerk.io inizializza l’Element, imposta i parametri tramite script di design:

contentElement.setAttribute("data-api", "recommendations/complementary");
contentElement.setAttribute("data-products", ids.join(","));
contentElement.setAttribute("data-exclude", ids.join(","));
contentElement.setAttribute("data-limit", "8");

Clerk("content", "#" + contentElement.id, function (content) {
  content.param({
    api: "recommendations/complementary",
    products: ids,
    exclude: ids,
    limit: 8
  });
});

Tratta questa configurazione da script come fallback. Deve essere eseguita dopo che gli ID correnti del carrello sono disponibili, non solo al primo caricamento della pagina.

Monta l’Element #

Posiziona l’Element in una posizione stabile e sposta il root delle Recommendation renderizzate all’interno del sidecart dopo che Clerk.io lo ha renderizzato. Usa classi clerk- indipendenti in modo che il design non erediti stili di provider precedenti come classi hr- o aw-.

Su desktop, una rail di Recommendation può stare di fianco al sidecart:

.clerk-sidecart-recs {
  position: absolute;
  top: 0;
  right: 100%;
  width: 250px;
  height: 100vh;
}

Se la piattaforma taglia la rail, aggiungi overflow: visible !important alla classe host del sidecart. Su mobile, sposta il root all’interno del corpo del sidecart e usa position: static.

Mantieni aggiornate le Recommendation #

Le azioni del carrello spesso generano diversi eventi in rapida successione e potrebbero sostituire il corpo del sidecart. Debounce gli eventi del carrello e le relevant DOM mutation, quindi attendi che il carrello abbia finito di aggiornarsi prima del rendering.

Traccia una chiave generata dagli ID prodotto correnti, ad esempio ids.join(","). Esegui il rendering solo quando cambia la chiave finale. Se le variazioni di quantità devono influenzare le Recommendation, includi le quantità nella chiave; altrimenti, una modifica della sola quantità non richiede una nuova richiesta di Recommendation.

Utilizza un render lock e un breve cooldown per chiave per evitare rendering sovrapposti o ripetuti mentre i frammenti si aggiornano. Se il root delle Recommendation viene rimosso durante un refresh, ripristinalo una sola volta per la stessa chiave carrello.

Traccia la chiave carrello sia sull’Element che sul root Recommendation visibile. Prima di applicare una risposta asincrona, confronta la chiave della risposta con quella corrente del carrello. Così una risposta più vecchia non sovrascriverà le Recommendation più recenti.

var key = ids.join(",");
contentElement.setAttribute("data-products", ids.join(","));
contentElement.setAttribute("data-exclude", ids.join(","));
contentElement.setAttribute("data-clerk-sidecart-request-key", key);
root.setAttribute("data-clerk-sidecart-render-key", key);

if (getCartProductIds().join(",") !== key) return;

Evita di usare la presenza delle product card esistenti come unico controllo. Un rendering iniziale può avvenire prima che siano disponibili gli ID del carrello e può lasciare il sidecart bloccato con i prodotti sbagliati.

Rendering di fallback #

Se il root di Clerk.io scompare dopo un refresh del carrello, marca un root fallback creato manualmente con data-clerk-sidecart-fallback="true". Nascondilo mentre è vuoto o in caricamento, rimuovilo quando appare un vero root Clerk.io, e memorizza in cache l’HTML di fallback per chiave carrello per evitare chiamate API duplicate durante il ripristino.

Layout Desktop e Mobile #

Su desktop, la rail delle Recommendation può stare a lato del sidecart. Su mobile, spostala nell’area dei contenuti del sidecart e mostra un solo prodotto alla volta. Usa i controlli slider nativi di Clerk.io o controlli custom, ma non mostrare entrambe le serie di frecce.

Se il design gestisce i controlli, nascondi i controlli generati da Clerk.io in questo design:

.clerk-sidecart-recs .clerk-slider-nav,
.clerk-sidecart-recs .clerk-slider-prev,
.clerk-sidecart-recs .clerk-slider-next,
.clerk-sidecart-recs .clerk-slider-button,
.clerk-sidecart-recs [class*="clerk-slider-arrow"] {
  display: none !important;
}

Spostare un root renderizzato o sostituire i frammenti del carrello durante l’inizializzazione dello slider può lasciare le product card senza frecce visibili. Decidi quale codice gestisce i controlli e verifica questa proprietà dopo ogni refresh.

Aggiungi al carrello #

Se le card Recommendation hanno pulsanti aggiungi al carrello, usa l’endpoint AJAX della piattaforma e previeni la navigazione normale del link. Dopo il successo, scatena l’evento carrello standard della piattaforma se necessario e pianifica una sync dopo la stabilizzazione. Quando Clerk.js è disponibile, traccia anche l’azione con Clerk("cart", "add", productId, { quantity: 1 });.

Verifica il risultato #

Verifica sia il caso di carrello già esistente che di carrello vuoto. Testa apertura e chiusura del sidecart, aggiunta e rimozione prodotti, cambi quantità e aggiornamenti senza ricarica completa della pagina.

Controlla la posizione della rail desktop, la posizione inline su mobile, le slide con un solo prodotto su mobile, lo stato di caricamento, vuoto ed errore. Assicurati che non compaiano placeholder con solo il titolo mentre il carrello è in caricamento.

Nel network panel del browser, controlla le chiamate a api.clerk.io. La stessa chiave carrello non dovrebbe generare richieste Recommendation duplicate e una risposta vecchia non deve sostituire le Recommendation attuali. Infine, aggiungi un prodotto consigliato direttamente dal sidecart e conferma che carrello, tracking e Recommendation si aggiornino correttamente.