API | clerk.io

Sincronizzazione dei dati #

Clerk sincronizza ogni dominio del webshop, chiamato Store, come istanza unica, a cui si accede tramite una serie di chiavi API che si trovano nell’amministrazione di Clerk:

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 ottenere, postare, aggiornare e eliminare le risorse 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 è l’assenza di un periodo di apprendimento, poiché possiamo utilizzare tutti gli ordini esistenti fin dal primo giorno per comprendere 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, oppure un attributo del prodotto potrebbe contenere un errore che fa fallire diverse chiamate. Per evitare questi problemi, si consiglia di utilizzare un Data Feed 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 quando viene caricato saranno quelli con cui lavora Clerk, tranne gli 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 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 attraverso endpoint unici a seconda del caso d’uso.

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

Endpoint #

Tutti gli endpoint richiedono l’invio della chiave API pubblica.

Gli endpoint che restituiscono risultati richiedono anche l’argomento “limit “ per controllare il numero di risultati da restituire.

Altri argomenti dipendono dall’endpoint che si sta chiamando. Ad esempio, i prodotti complementari richiedono un elenco di ID prodotto per cui trovare gli accessori, e qualsiasi chiamata relativa alla ricerca necessita del parametro “query “ per trovare le corrispondenze, e così via.

Gli argomenti necessari per tutti gli endpoint sono disponibili nella nostra [documentazione API] (https://docs.clerk.io/reference).

Per impostazione predefinita, Clerks API restituisce tutti i risultati disponibili, ma se necessario, è possibile utilizzare Filters 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 #

L’API di Clerk restituisce sempre gli 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.

L’API di Clerk può anche essere configurata in modo da restituire tutte le informazioni specifiche sulle 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:

Generazione di un [ID di sessione per ogni visitatore] (https://docs.clerk.io/docs/visitor-tracking).
Aggiunta di etichette di tracciamento descrittive alle chiamate API che restituiscono risultati, utilizzati per mostrare le analisi dei singoli endpoint.
Registrazione dei clic dei visitatori sui prodotti mostrati da Clerk.
Registrazione di ogni ordine effettuato nel negozio web

ID visitatore (sessione) #

L’ID di sessione è chiamato anche ID visitatore con Clerk. È strettamente necessario per registrare l’attività di un utente durante una sessione del 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ò utilizzare la funzione uniqid() di PHP per generare ID unici almeno per la sessione corrente. Una volta generato, questo ID deve essere incluso in tutte le chiamate 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"]
        }'

Clic di registrazione #

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

Includere il product id product, e idealmente anche l’endpoint api e le labels della chiamata API che ha mostrato il prodotto. Se questi dati non sono inclusi, 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/sale per tracciare ogni ordine non appena viene inserito nel negozio web. Con l’ID del visitatore incluso in questa chiamata, Clerk capirà quali prodotti sono stati mostrati, cliccati e infine acquistati. Questo permette all’intelligenza artificiale di rimanere sempre aggiornata e di modificare i risultati al volo in base al comportamento dei clienti.

**Importante

Gli id dei prodotti devono 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.
Il prezzo è il prezzo unitario dei prodotti. Clerk lo moltiplica per la quantità nelle nostre 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 del visitatore #

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

L’ID viene utilizzato per fornire analisi nei 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, consultare questo articolo.

Per cosa utilizziamo l’ID? #

**Dashboard, analisi e attribuzione.

Clerk.io tiene traccia di tutti gli ordini effettuati sul webshop e confronta quelli impattati da Clerk.io con quelli 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 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 il sales-tracking è 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 i cookie dal vostro sito, potete configurare Clerk in modo che aggiunga un cookie che consenta il tracciamento a lungo termine con l’ID generato. Ciò avviene semplicemente aggiungendo visitor: ‘persistent’ a Clerk.js.

Disattivazione dell’ID “visitatore #

Per impostazione predefinita, Clerk.js viene eseguito in modalità cookieless, quindi se il parametro visitor 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 ‘visitor’: null:

Clerk.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 di Customer Success attraverso la live-chat nell’angolo in basso a destra.