Qualsiasi (webshop)

API

Un modo flessibile per integrare lato server.

Tutta la comunicazione con Clerk avviene tramite l’API:

https://api.clerk.io/v2

Configurare questa comunicazione richiede 4 passaggi, che sono illustrati in questa guida. Devi:

  1. Sincronizzare i dati
  2. Recuperare i risultati
  3. Visualizzare i risultati
  4. Aggiungere il tracciamento

API Keys #

Queste chiavi vengono utilizzate per accedere ai dati del tuo Store. Si trovano in my.clerk.io > Developers > API Keys.

Sono costituite da una Public key, che dà accesso agli endpoint che espongono dati non sensibili, e da una Private Key che consente di lavorare con i dati sullo Store e accedere a dati sensibili, come le informazioni sui clienti e sugli ordini.

Per motivi di sicurezza, le Private Key possono essere visualizzate una sola volta dopo la creazione, e puoi crearne quante ne hai bisogno per scopi diversi.

1. Sincronizzazione dei dati #

Il primo passo è inserire i dati, consentendo all’AI di Clerk.io di comprendere il tuo webshop e prevedere i risultati. Clerk sincronizza ogni dominio del webshop come una propria istanza unica di Store, alla quale si accede tramite un set di API Keys.

CRUD API #

Puoi sincronizzare i tuoi dati utilizzando gli endpoint CRUD API, che ti permettono di get, post, update e delete 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": "osLqDAs5s2tlf3adpLv6Mp1hxx3f",
          "products":[
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antique rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Fool proof."
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Gli oggetti disponibili sono:

Uno dei principali elementi distintivi di Clerk è che non esiste un periodo di apprendimento, poiché possiamo utilizzare tutti gli ordini esistenti fin dal primo giorno per comprendere il comportamento attuale dei clienti.

Data Feeds #

Oltre all’uso delle CRUD API, è altamente raccomandato aggiungere un metodo di sincronizzazione di backup. Dopotutto, molte cose possono andare storte con le chiamate API.

Ad esempio, il server dei prezzi potrebbe andare in crash, o un attributo del prodotto potrebbe contenere un errore che causa il fallimento di più chiamate. Per evitare questi problemi, considera l’utilizzo di uno o più Data Feeds come backup quotidiano per le tue chiamate CRUD.

I data feeds sono uno o più file JSON che contengono il catalogo attuale del webshop.

Qualsiasi dato disponibile nel feed al momento del caricamento sarà quello su cui Clerk lavora, fatta eccezione per gli ordini, che vengono registrati e non devono essere inclusi nel feed dopo il primo import.

Utilizzare il data feed è anche un ottimo modo per precaricare Clerk con gli ordini.

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

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

I feed dei dati dovrebbero essere disponibili a un URL accessibile dall’importatore, che configuri nel backend di my.clerk.io in System status > Data Sync. Puoi mettere in sicurezza il feed, così solo il nostro importatore potrà accedervi.

2. Recuperare i Dati #

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

Ad esempio, per ottenere i prodotti più popolari, puoi usare l’endpoint recommendations/trending, e per visualizzare i prodotti principali per una ricerca su “star wars,” puoi usare l’endpoint search/predictive.

Endpoints #

Tutti gli endpoint richiedono di inviare la public API key.

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

I parametri aggiuntivi dipendono dall’endpoint che stai chiamando. Ad esempio, le migliori alternative richiedono products che è una lista di ID prodotto per cui trovare accessori, e tutte le chiamate relative alla ricerca necessitano del parametro query per trovare le corrispondenze.

Puoi trovare gli argomenti necessari per tutti gli endpoint nella nostra documentazione API.

Di default, l’API di Clerk restituisce tutti i risultati disponibili, ma se necessario, Filtri possono essere usati per definire un sottoinsieme di risultati.

Di seguito un esempio di chiamata a un endpoint Search per trovare i prodotti principali per una ricerca su “star wars,”

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"]
        }'

Recommendations #

Di seguito un esempio di chiamata a un endpoint Recommendations per trovare i prodotti più popolari.

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"]
        }'

Response debugging #

Quando il debug è attivato per una richiesta, le risposte dell’API includono un array debug che mostra, in ordine, come le diverse funzionalità hanno influenzato i risultati. Ogni voce include una feature, un message leggibile e metadati strutturati che descrivono gli effetti specifici.

{
  "status": "ok",
  "result": [
    "riverbank",
    "pretty-tree"
  ],
  "count": 2,
  "hits": 2,
  "debug": [
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: Test-promote-in-results. Any calculated effects are available in the metadata.",
      "metadata": {
        "promote_in_result": {
          "frequency=(2, 0)": {
            "promoted_products": [
              [
                "riverbank"
              ]
            ]
          }
        }
      }
    },
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: test-promote-to-position. Any calculated effects are available in the metadata.",
      "metadata": {
        "promote_to_position": {
          "position=(0, 1)": {
            "promoted_products": [
              [
                "0001",
                "FFFF"
              ]
            ]
          }
        },
        "adjust_position": {
          "FFFF": [
            {
              "max_depth": 1,
              "boost": 100000
            }
          ]
        }
      }
    },
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: Test campaign. Any calculated effects are available in the metadata.",
      "metadata": {
        "boost": {
          "SPACER0": -2.0
        }
      }
    }
  ]
}

3. Visualizzare i Risultati #

L’API di Clerk restituisce sempre gli ID delle corrispondenze che trova quando restituisce i risultati.

Per visualizzare i tuoi dati, puoi effettuare chiamate API lato server, recuperare gli ID dei prodotti corrispondenti e quindi ottenere tutte le informazioni specifiche dei prodotti dalla tua piattaforma webshop o PIM prima di renderizzarli.

Chiamata

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

Risposta

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

L’API di Clerk può anche essere configurata per restituire qualsiasi informazione specifica della risorsa che invii a Clerk, come prezzi, nomi dei brand, URL delle categorie, immagini di copertina dei blog, e altro.

Con questa modalità, spesso non è necessario effettuare chiamate individuali al tuo PIM prima di mostrare i risultati, il che velocizzerà il caricamento della tua pagina.

Chiamata

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

Risposta

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.awesomestore.com/image/14df",
            "name": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "https://admin.awesomestore.com/product/14df"
        },
        {
            "id": 13827,
            "image": "https://admin.awesomestore.com/image/51xs",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/51xs"
        },
        {
            "id": 12693,
            "image": "https://admin.awesomestore.com/image/62x1",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/62x1"
        }
    ]
}

4. Tracking #

Deve essere aggiunto il tracking per mantenere aggiornata l’AI di Clerk e personalizzare i risultati per il visitatore durante la sessione. Sono necessari 4 passaggi:

  1. Generare un ID di sessione per ogni visitatore.
  2. Aggiungere etichette descrittive alle chiamate API che restituiscono risultati.
  3. Registrare i clic di un visitatore sui prodotti mostrati da Clerk.
  4. Registrare ogni ordine effettuato sul webshop.

Crea Visitor ID #

L’ID di sessione è chiamato anche Visitor ID. È necessario per tracciare l’attività di un utente durante una sessione sul webshop, inclusi i prodotti che clicca, le sue ricerche e le categorie visitate.

Questa attività viene archiviata per ogni Store, e Clerk.io non la condivide mai tra gli Store.

Un visitor ID è semplicemente una stringa utilizzata per identificare la sessione. Può essere composta da qualsiasi carattere alfanumerico e consigliamo di mantenerla a un massimo di 8 caratteri per le migliori prestazioni.

Ad esempio, puoi utilizzare la funzione uniqid() di PHP per generare ID che siano unici almeno per la sessione corrente. Una volta generato, questo ID deve essere incluso in tutte le chiamate all’API di Clerk.io affinché il tracking funzioni.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Aggiungi Etichette #

Le etichette devono essere aggiunte a tutte le chiamate che restituiscono risultati, come ricerche o alternative su una pagina prodotto. L’argomento labels è una lista che contiene almeno una stringa, ovvero l’etichetta descrittiva di questa chiamata.

Consigliamo di usare etichette che descrivano la pagina dove viene usata la chiamata, e il tipo di risultati che mostra. Un esempio può essere Homepage - Trending. Questo le rende facilmente distinguibili nelle 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"]
        }'

Log Clicks #

Dovresti registrare ogni clic su un prodotto di Clerk.io tramite l’endpoint log/click.

È importante effettuare questa chiamata solo quando il prodotto cliccato è effettivamente mostrato da Clerk.io e non dalla piattaforma webshop stessa. Altrimenti, sembrerà che tutti i prodotti siano trovati tramite Clerk.

La chiamata deve inoltre includere api che è l’endpoint utilizzato per mostrare il prodotto cliccato, e product che contiene l’ID del prodotto cliccato.

Search & Recommendations #

La registrazione dei clic avviene aggiungendo i parametri alla chiamata in base all’endpoint usato per mostrare il prodotto cliccato. È semplice perché utilizza i dati della configurazione che hai già impostato.

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --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
        }'

Email Recommendations #

La registrazione dei clic funziona in modo diverso, poiché riceverai i dati tramite richieste GET inoltrate da Clerk.io. Dovresti monitorare se l’URL include parametri che indicano che i visitatori arrivano su una pagina prodotto da una Email Recommendation.

Queste richieste includeranno sempre i seguenti parametri di query:

{
  "utm_source": "clerk",
  "utm_medium": "email",
  "utm_campaign": "Welcome Email - Bestsellers",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Welcome Email - Bestsellers",
  "clerk_api": "recommendations/popular",
  "clerk_n": 0,
  "clerk_external": 1
}

Consigliamo di monitorare se l’URL contiene clerk_external: 1 e, in tal caso, di registrare il clic con i dati ricevuti.

clerk_api contiene l’endpoint API con un carattere * per evitare problemi di codifica. Questo deve essere cambiato in / quando si registra il clic. external: 1 deve essere aggiunto alla chiamata così che Clerk sappia che il clic proviene da un’email.

Ecco un esempio di chiamata log/click che utilizza i dati sopra:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Welcome Email - Bestsellers"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Log dei Prodotti #

Quando i visitatori visualizzano le pagine dei prodotti, questo deve essere registrato così da poter personalizzare i risultati – in particolare quelli relativi al visitatore come Visitor Recommendations o Visitor Alternatives.

Se utilizzi degli endpoint che già necessitano dell’ID prodotto, come recommendations/substituting o recommendations/complementary, Clerk.io registrerà automaticamente l’ID prodotto.

Tuttavia, se non utilizzi questi endpoint, devi effettuare una chiamata separata a log/product, con l’ID del prodotto visualizzato.

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

Log delle Vendite #

L’AI di Clerk.io fa ampio affidamento sugli ordini per prevedere i risultati, quindi il tracciamento in tempo reale è fondamentale. L’endpoint log/sale viene utilizzato a questo scopo.

Includendo il Visitor ID in questa chiamata, Clerk capirà quali prodotti sono stati mostrati, cliccati e infine acquistati. In questo modo, l’AI resta sempre aggiornata e modifica i risultati in tempo reale in base al comportamento del cliente.

Questa chiamata associa anche il Visitor ID all’indirizzo email o all’ID cliente dell’acquirente, permettendo una personalizzazione ancora più avanzata tramite raccomandazioni cliente-specifiche.

L’id dei prodotti deve corrispondere agli ID che vengono registrati per i clic. Ad esempio, per i prodotti configurabili dovresti tracciare l’ID padre sia in log/click che in log/sale indipendentemente dalla variante acquistata.
price è il prezzo unitario. Verrà moltiplicato per quantity in Analytics.
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

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