Any (webshop)

API

Un modo flessibile per integrare il lato server.

Tutte le comunicazioni con Clerk avvengono attraverso l’API:

https://api.clerk.io/v2

L’impostazione di questa comunicazione richiede 4 fasi, illustrate in questa guida. È necessario sincronizzare i dati, recuperare i risultati, visualizzarli e aggiungere il monitoraggio per mantenere aggiornata l’IA.

Sincronizzazione dei dati #

Clerk sincronizza ogni dominio del webshop, chiamato Store, come istanza unica, a cui si accede da un insieme di Chiavi API, che si trovano nel sito Clerk admin :

Queste includono una chiave pubblica, che dà accesso agli endpoint che espongono dati non sensibili, e una chiave privata. La chiave privata, combinata con la chiave pubblica, consente di lavorare con i dati del negozio e di accedere ai dati sensibili, come le informazioni sui clienti e sugli ordini.

API CRUD #

È possibile sincronizzare i dati utilizzando gli endpoint dell’API CRUD, che consentono di accedere alle risorse ottenere, post, aggiornare e cancellare su richiesta.

curl --request POST \
     --url 'https://api.clerk.io/v2/products' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "private_key": "osLqDAs5s2tlf3adpLv6Mp1hxxf6GfdDuSE0c2ftT2ot5F3",
          "products":[
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antiuque rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Guaranteed idiot proof. "
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Le risorse disponibili sono:

Uno dei principali fattori di differenziazione di Clerk è che non c’è un periodo di apprendimento, poiché possiamo utilizzare tutti gli ordini esistenti fin dal primo giorno per capire il comportamento attuale dei clienti.

Alimentazione dei dati #

Oltre all’utilizzo dell’API CRUD, si consiglia di aggiungere un metodo di sincronizzazione di backup.

Dopo tutto, molte cose possono andare storte con le chiamate API. Ad esempio, il server dei prezzi potrebbe bloccarsi o un attributo del prodotto potrebbe contenere un errore che fa fallire diverse chiamate. Per evitare questi problemi, si consiglia di utilizzare Alimentazione dei dati come backup giornaliero per le chiamate CRUD.

Il feed è un file JSON che contiene lo stato attuale del catalogo di un webshop. Tutti i dati disponibili nel feed al momento del caricamento saranno quelli con cui lavora Clerk, ad eccezione degli ordini, che vengono registrati e non devono essere inclusi nel feed dopo la prima importazione. L’uso del feed di dati è anche un ottimo modo per precaricare Clerk con gli ordini.

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

Il feed di dati deve essere disponibile in un URL accessibile dall’importatore, configurato nel backend di my.clerk.io:

È possibile proteggere il feed, in modo che solo il nostro importatore possa accedervi.

Recupero dei dati #

Una volta sincronizzati i dati, l’intelligenza artificiale li analizza e costruisce indici intelligenti che possono essere recuperati tramite endpoint unici a seconda del caso d’uso.

Ad esempio, per recuperare i prodotti più caldi, si può utilizzare l’endpoint raccomandazioni/trending, mentre per visualizzare i prodotti migliori per una ricerca su “guerre stellari”, si può utilizzare l’endpoint ricerca/predittivo.

Endpoint #

Tutti gli endpoint richiedono l’invio dell’indirizzo chiave API pubblica.

I punti finali che restituiscono risultati richiedono anche l’argomento " limite" per controllare il numero di risultati da restituire.

Gli argomenti aggiuntivi dipendono dall’endpoint che si sta chiamando. Ad esempio, i prodotti complementari richiedono il parametro elenco di ID prodotto per trovare gli accessori, mentre le chiamate relative alla ricerca richiedono il parametro “query” per trovare le corrispondenze, e così via.

Gli argomenti necessari per tutti gli endpoint si trovano nel nostro Documentazione API.

Per impostazione predefinita, Clerks API restituisce tutti risultati disponibili, ma se necessario, Filtri può essere usato per definire un sottoinsieme di corrispondenze.

Esempio di raccomandazioni #

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"]
        }'

Esempio di ricerca #

curl --request POST \
     --url 'https://api.clerk.io/v2/search/predictive' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "query": "star wars",
          "labels": ["Search - Predictive"]
        }'

Visualizzazione dei risultati #

ClerkL’API restituisce sempre ID delle corrispondenze trovate quando restituisce i risultati.

// Call
curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 5,
          "labels": ["Homepage - Trending"]
        }'

// Response
{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693,
        12791,
        1546
    ],
    "count": 3902,
    "facets": null
}

Per visualizzare i dati, è possibile effettuare chiamate API lato server, recuperare gli ID dei prodotti corrispondenti e quindi recuperare tutte le informazioni specifiche del prodotto dalla piattaforma del webshop o dal PIM prima di renderizzarle.

ClerkL’API può anche essere configurata in modo da restituire tutte le informazioni specifiche delle risorse inviate a Clerk, come prezzi, nomi di marche, URL di categorie, immagini di copertina dei blog e altro ancora. In questo modo, spesso non è necessario effettuare singole chiamate al PIM prima di mostrare i risultati, il che rende più veloce il caricamento della pagina.

// Call
curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

// Response
{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693,
        12791,
        1546
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/2/8/2807199-baccarat-eye-small-oval-red-vase.jpg",
            "name": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "/"
        },
        {
            "id": 13827,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/1/t/1transatvj.jpg",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "/"
        },
        {
            "id": 12693,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/2/t/2transatdl.jpg",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "/"
        },
        {
            "id": 12791,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/1/8/1845244-baccarat-dom-perignon-champagne-flute-_set-of-2_.jpg",
            "name": "Baccarat Dom Perignon Champagne Flute (Set of 2)",
            "price": 260.0,
            "url": "/"
        },
        {
            "id": 1546,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/m/a/maison-berger-ocean-breeze-1-litre-lamp-refill.jpg",
            "name": "Maison Berger Ocean Breeze 1 Litre Lamp Refill",
            "price": 29.0,
            "url": "/"
        }
    ]
}

Tracciamento #

Infine, è necessario aggiungere il tracciamento per mantenere aggiornata l’AI di Clerk e personalizzare i risultati dei visitatori durante la loro sessione. Il tracciamento di Clerk si configura in 4 fasi:

  1. Generazione di un ID di sessione per ogni visitatore
  2. Aggiunta di etichette descrittive di tracciamento alle chiamate API che restituiscono risultati, utilizzati per mostrare le analisi dei singoli endpoint.
  3. Registrazione dei clic del visitatore sui prodotti mostrati da Clerk
  4. Registrazione di ogni ordine effettuate sul webshop

ID visitatore (sessione) #

L’ID di sessione è chiamato anche ID visitatore in Clerk. È strettamente necessario per registrare l’attività di un utente durante una sessione sul webshop, compresi i prodotti cliccati, le ricerche effettuate e le categorie sfogliate. Questa attività viene memorizzata per ogni dominio e Clerk non la condivide mai tra i vari negozi.

Ad esempio, si può usare la funzione uniqid() di PHP per generare ID unici almeno per la sessione corrente. Una volta generato, questo ID deve essere incluso nelle chiamate di tutti a Clerk perché il tracciamento funzioni.

<?php

session_start();

$current_visitor = uniqid(); //Example: "646f1f0584371"

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Etichette #

Le etichette devono essere aggiunte a qualsiasi chiamata che restituisca risultati, come i risultati di una ricerca o le alternative in una pagina di prodotto. L’argomento labels è un elenco contenente almeno una stringa, che deve essere l’etichetta di questa chiamata.

Si consiglia di utilizzare etichette che contengano la pagina in cui viene utilizzata ogni chiamata e il tipo di risultati che mostra, come “Homepage - Trending”. In questo modo è facile distinguerle in analytics.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Registrazione dei clic #

Quindi, è necessario registrare ogni clic su un prodotto Clerk con log/click. È importante solo effettuare questa chiamata quando il prodotto cliccato è effettivamente mostrato da Clerk e non dalla piattaforma webshop stessa; altrimenti, sembrerà che i prodotti tutti siano trovati attraverso Clerk.

Includere il id prodotto product e idealmente anche l’endpoint api e il labels dalla chiamata API che ha mostrato il prodotto. Se questo non è incluso, Clerk farà risalire il clic all’ultima chiamata API che ha mostrato il prodotto.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Homepage - Trending"],
          "api": "recommendations/trending",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Registrazione delle vendite #

Infine, utilizzare log/vendita per tracciare ogni ordine non appena viene inserito nel negozio web. Grazie all’ID del visitatore incluso in questa chiamata, Clerk capirà quali prodotti sono stati mostrati, cliccati e infine acquistati. Ciò consente all’intelligenza artificiale di essere sempre aggiornata e di modificare al volo i risultati in base al comportamento dei clienti.

Importante:

  • L’indirizzo id dei prodotti deve corrispondere agli ID registrati con log/click. Ad esempio, per i prodotti configurabili si dovrebbe tenere traccia dell’ID dei genitori sia in log/click che in log/sale, indipendentemente dalla variante acquistata.
  • price è il prezzo unitario per i prodotti. Clerk lo moltiplica per la quantità nella nostra analisi.
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0",
          "sale": 567,
          "products": [
            {
              "id": 12793,
              "price": 99.95,
              "quantity": 2
            },
            {
              "id": 1546,
              "price": 14.00,
              "quantity": 2
            }
          ],
          "customer": 1234,
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}' \
       https://api.clerk.io/v2/log/sale

Dettagli dell’ID visitatore #

Per impostazione predefinita, Clerk.io è senza cottura e utilizza un ID visitatore anonimo anziché memorizzare i cookie.

L’ID viene utilizzato per fornire analisi nelle Dashboard di Clerk.io e per le funzionalità del sito, come i consigli “Hai visitato in precedenza”.

Per maggiori dettagli sul funzionamento della personalizzazione senza cookie, consultate questo articolo.

Per cosa utilizziamo l’ID? #

Cruscotti, analisi e attribuzione.

Clerk.io tiene traccia di tutti gli ordini effettuati sul webshop e confronta quelli impattati da Clerk.io con gli ordini non impattati.

Attraverso l’ID del visitatore, possiamo tracciare quando un consumatore fa clic su un prodotto in un elemento di Clerk.io e procede a effettuare un ordine contenente quel prodotto per consentire l’attribuzione.

Funzionalità in loco

Attraverso l’ID del visitatore, raccogliamo gli ID dei prodotti che un consumatore naviga e le ricerche che effettua.

Questo ci permette di personalizzare le raccomandazioni sul webshop, compresi i banner come " Le nostre raccomandazioni per te" e " Hai già visto" che mostrano i prodotti correlati alla navigazione sul webshop.

L’ID visitatore e il suo funzionamento #

Ogni chiamata effettuata a Clerk.io conterrà l’ID anonimo del visitatore sopra descritto, che potrà essere utilizzato per gli scopi sopra indicati.

Quando un visitatore scrive il proprio indirizzo e-mail sul webshop e/o effettua un ordine, l’ID visitatore viene associato al suo indirizzo e-mail se tracciamento delle vendite è attivato.

Un indirizzo e-mail in Clerk.io può contenere più ID visitatore che possono essere visualizzati nella pagina dei clienti in my.clerk.io:

Se un utente accetta riceve dei cookie dal vostro sito, potete configurare Clerk per aggiungere un cookie che consenta il tracciamento a lungo termine con questo ID generato. Per farlo è sufficiente aggiunta di visitatore: ‘persistente’ a Clerk.js.

Disattivare l’ID “visitatore”. #

Per impostazione predefinita, Clerk.js viene eseguito in modalità cookieless, quindi se il parametro visitatore non è impostato, verrà registrata l’attività della sessione senza aggiungere un cookie.

Se si desidera consentire al visitatore di scegliere di non essere tracciato in alcun modo, è possibile disattivare completamente l’ID aggiungendo visitatore’: null:

Impiegato.js

Nelle configurazioni che utilizzano Clerk.js, aggiungerlo al codice Clerk.js per quel visitatore:

API

Se si utilizzano chiamate API dirette, includerle come argomento:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "yu0tX54BcDAIuBp8RkNoldtcir9Dwip8",
          "limit": 30,
          "labels": ["Bestsellers"]
          "visitor": null}' \
     http://api.clerk.io/v2/recommendations/popular

Se avete domande sul tracciamento dei visitatori, non esitate a contattare il nostro team Customer Success attraverso la live-chat nell’angolo in basso a destra.

Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.