Qualsiasi (webshop)

API

Un modo flessibile per integrare lato server.

Tutta la comunicazione con Clerk avviene tramite l’API:

https://api.clerk.io/v2

La configurazione di questa comunicazione richiede 4 passaggi, illustrati in questa guida. Devi:

Sincronizzare i dati
Recuperare i risultati
Visualizzare i risultati
Aggiungere il tracking

API Keys #

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

Sono composte 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 dello Store e accedere a dati sensibili, come le informazioni su clienti e ordini.

Le Private Keys possono essere visualizzate solo una volta dopo la creazione per motivi di sicurezza, e puoi crearne quante ne vuoi per scopi diversi.

1. Sincronizzare i dati #

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

CRUD API #

Puoi sincronizzare i tuoi dati utilizzando gli endpoint dell’API CRUD, che 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 punti di forza di Clerk è che non c’è periodo di apprendimento, poiché possiamo utilizzare tutti gli ordini esistenti fin dal primo giorno per capire il comportamento attuale dei clienti.

Data Feeds #

Oltre ad utilizzare la CRUD API, è altamente raccomandato aggiungere un metodo di sincronizzazione di backup. Infatti, molte cose possono andare storte con le chiamate API.

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

I data feed 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 lavorerà Clerk, tranne che per gli ordini, che sono registrati e non devono essere inclusi nel feed dopo il primo import.

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

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

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

Il/i data feed dovrebbero essere disponibili su una URL accessibile dall’importer, che configuri nel backend my.clerk.io in System status > Data Sync. Puoi proteggere il feed, così solo il nostro importer può accedervi.

2. Recupero dei 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 recuperare i prodotti più richiesti, puoi usare l’endpoint recommendations/trending e per mostrare i prodotti principali per una ricerca di “star wars,” puoi usare l’endpoint search/predictive.

Endpoints #

Tutti gli endpoint richiedono l’invio della public API key.

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

Parametri aggiuntivi dipendono dall’endpoint che stai chiamando. Ad esempio, le migliori alternative richiedono products che è una lista di ID prodotto per trovare accessori, e qualsiasi chiamata relativa alla ricerca richiede il parametro query per trovare 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 utilizzati per definire un sottoinsieme di corrispondenze.

Search #

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ù richiesti.

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

Debugging della risposta #

Quando il debugging è abilitato per una richiesta, le risposte API includono un array debug che mostra, in ordine, come le diverse feature hanno influenzato i risultati. Ogni voce include una feature, un message leggibile e dei metadata 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. Visualizzazione dei risultati #

L’API di Clerk restituisce sempre gli ID delle corrispondenze trovate nel ritorno dei risultati.

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

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 di brand, URL delle categorie, immagini di copertina dei blog, ecc.

Grazie a ciò, spesso non hai bisogno di effettuare chiamate singole al tuo PIM prima di mostrare i risultati, il che consente di caricare la pagina più rapidamente.

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 #

Il tracciamento deve essere aggiunto per mantenere aggiornata l’AI di Clerk e personalizzare i risultati per il visitatore durante la sua sessione. Richiede 4 passaggi:

Generare un session ID per ogni visitatore.
Aggiungere etichette descrittive alle chiamate API che restituiscono risultati.
Registrare i click del visitatore sui prodotti mostrati da Clerk.
Registrare ogni ordine effettuato sul webshop.

Creare Visitor ID #

Il session ID è chiamato anche Visitor ID. È richiesto per registrare l’attività di un utente durante una sessione sul webshop, inclusi i prodotti su cui clicca, le ricerche effettuate e le categorie visitate.

Questa attività è memorizzata per ogni Store, e Clerk.io non la condivide mai tra Store diversi.

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

Ad esempio, potresti usare 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 all’API di Clerk.io affinché il tracking funzioni.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Aggiungere le etichette #

Le etichette devono essere aggiunte a tutte le chiamate che restituiscono risultati, come le corrispondenze di ricerca o le alternative in una pagina prodotto. L’argomento labels è una lista contenente almeno una stringa, che dovrebbe essere l’etichetta descrittiva di questa chiamata.

Consigliamo di usare etichette che descrivano la pagina in cui viene usata la chiamata e il tipo di risultato visualizzato. Un esempio potrebbe 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 dei click #

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

È importante fare 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 dovrebbe includere anche api, che è l’endpoint usato per mostrare il prodotto cliccato, e product, che contiene l’ID del prodotto cliccato.

Search & Recommendations #

Il log dei click si effettua aggiungendo i parametri alla chiamata in base all’endpoint usato per mostrare il prodotto cliccato. È semplice perché utilizza dati impostati nella tua integrazione.

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 #

Il log dei click funziona diversamente: riceverai i dati da richieste GET inoltrate da Clerk.io. Dovresti monitorare se la URL include parametri che indicano che i visitatori arrivano su una pagina prodotto da una Email Recommendation.

Queste richieste avranno sempre i seguenti query parametri:

{
  "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
}

Raccomandiamo di monitorare se la URL contiene clerk_external: 1 e, in questo caso, registrare il click con i dati ricevuti.

clerk_api contiene l’endpoint API con un carattere * per evitare problemi di encoding. Dovrebbe essere cambiato in / quando si registra il click. external: 1 va incluso nella chiamata così Clerk sa che il click proviene da una email.

Ecco un esempio di chiamata log/click che usa i dati di cui 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 prodotto, questo dovrebbe essere registrato per poter personalizzare i risultati, in particolare quelli legati all’utente come Visitor Recommendations o Visitor Alternatives.

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

Tuttavia, se non li usi, devi effettuare una chiamata separata a log/product, inserendo l’ID del prodotto navigato.

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 si basa fortemente sugli ordini per prevedere i risultati, quindi tracciare questi dati in tempo reale è fondamentale. L’endpoint log/sale viene usato per questo scopo.

Con il visitor ID incluso in questa chiamata, Clerk capirà quali prodotti sono stati mostrati, cliccati e infine acquistati. Ciò permette all’AI di rimanere sempre aggiornata e modificare in tempo reale i risultati in base al comportamento dei clienti.

Questa chiamata associa anche il Visitor ID all’indirizzo email o al customer ID dell’acquirente, consentendo una personalizzazione ancora migliore tramite raccomandazioni specifiche per cliente.

L’id dei prodotti deve corrispondere agli ID registrati per i click. Ad esempio, per prodotti configurabili devi tracciare l’ID del parent sia in log/click che in log/sale a prescindere dalla variante acquistata.

price è il prezzo unitario. Verrà moltiplicato per la 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

Rate Limiting #

L’API utilizza un sistema di rate limiting per garantire un uso equo e mantenere la stabilità durante i periodi di traffico intenso.

I limiti sono:

50 richieste al secondo per Store
100 richieste al secondo per indirizzo IP

Le richieste entro questi limiti non subiranno mai rate limiting. Le richieste che superano queste soglie potrebbero essere soggette a rate limiting, ma la reale applicazione dipende dalla capacità attuale del server.

Clerk.io scala la propria infrastruttura in modo dinamico. Durante eventi di traffico elevato come il Black Friday, vengono attivati più server per gestire il carico aumentato, il che significa che la capacità effettiva è molto più alta dei limiti base.

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