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. È necessario:

  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 composte da una chiave pubblica, che dà accesso agli endpoint che espongono dati non sensibili, e una chiave privata che consente di lavorare con i dati dello Store e accedere a dati sensibili, come le informazioni su clienti e ordini.

Per motivi di sicurezza, le chiavi private possono essere visualizzate solo una volta dopo la loro creazione, e puoi crearne quante ne desideri per scopi diversi.

1. Sincronizzare i Dati #

Il primo passaggio consiste nell’inserire i dati, permettendo all’AI di Clerk.io di comprendere il tuo webshop e prevedere i risultati. Clerk sincronizza ogni dominio webshop come istanza Store unica, a cui 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 dal primo giorno per comprendere il comportamento attuale dei clienti.

Data Feeds #

Oltre all’utilizzo della CRUD API, è altamente consigliato aggiungere un metodo di sincronizzazione di backup. In fondo, molte cose possono andare storte con le chiamate API.

Ad esempio, il tuo server dei prezzi potrebbe andare in crash, oppure un attributo di un prodotto potrebbe contenere un errore che causa il fallimento di diverse chiamate. Per evitare questi problemi, valuta di utilizzare uno o più Data Feeds come backup quotidiano delle tue chiamate CRUD.

I data feed sono uno o più file JSON che contengono il catalogo attuale dei webshops.

Tutti i dati disponibili nel feed, quando viene caricato, saranno quelli con cui Clerk lavorerà, ad eccezione degli ordini, che vengono registrati e non devono essere inclusi nel feed dopo il primo import.

Utilizzare il data feed è anche un ottimo modo per pre-caricare Clerk con ordini.

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

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

Il/i data feed dovrebbero essere disponibili ad un URL accessibile dall’importatore, che configuri nel backend di my.clerk.io in System status > Data Sync. Puoi proteggere il feed, così che solo il nostro importatore possa accedervi.

2. Recuperare i Dati #

Una volta sincronizzati i dati, 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ù popolari, puoi utilizzare l’endpoint recommendations/trending, e per mostrare i migliori prodotti per una ricerca di “star wars,” puoi utilizzare 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 da restituire.

I parametri aggiuntivi dipendono dall’endpoint che stai chiamando. Ad esempio, per le migliori alternative è richiesto products che è una lista di ID prodotto per cui trovare accessori, e per qualsiasi chiamata relativa alla ricerca serve il parametro query per trovare corrispondenze.

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

Per impostazione predefinita, l’API di Clerk restituisce tutti i risultati disponibili, ma se necessario, è possibile utilizzare i Filtri per definire un sottoinsieme di corrispondenze.

Di seguito un esempio di chiamata ad un endpoint Search per trovare i migliori prodotti 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 all’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"]
        }'

Debugging della risposta #

Quando il debugging è abilitato 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 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. Visualizzare i Risultati #

L’API di Clerk restituisce sempre gli ID delle corrispondenze trovate quando restituisce risultati.

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

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 tutte le informazioni specifiche delle risorse che invii a Clerk, come prezzi, nomi dei brand, URL delle categorie, immagini di copertina dei blog e altro.

Grazie a questo, spesso non è necessario effettuare chiamate individuali al PIM prima di mostrare i risultati, permettendo così di velocizzare il caricamento della 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. Tracciamento #

È necessario aggiungere il tracciamento per mantenere l’AI di Clerk aggiornata e personalizzare i risultati per ogni visitatore durante la sessione. Ciò richiede 4 step:

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

Creare un Visitor ID #

Il session ID viene anche chiamato Visitor ID. È necessario per registrare l’attività di un utente durante una sessione su un webshop, inclusi i prodotti che clicca, le ricerche e le categorie che visita.

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

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

Ad esempio, puoi utilizzare la funzione PHP uniqid(), 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 per consentire il tracciamento.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Aggiungi Labels #

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 è un elenco che contiene almeno una stringa, che dovrebbe essere l’etichetta descrittiva di quella chiamata.

Raccomandiamo di usare etichette che descrivano la pagina dove viene usata la chiamata e il tipo di risultati che mostra. 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"]
        }'

Registrare i Click #

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

È importante effettuare solo questa chiamata 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 contenere anche il campo api che è l’endpoint usato per mostrare il prodotto cliccato, e product che contiene l’ID del prodotto cliccato.

Search & Recommendations #

La registrazione dei click avviene aggiungendo i parametri alla chiamata in base all’endpoint usato per mostrare il prodotto che è stato cliccato. Questo è semplice poiché utilizza i dati impostati da te stesso.

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 click funziona in modo diverso, poiché riceverai i dati da richieste GET inoltrate da Clerk.io. Dovresti monitorare se l’URL include parametri che indicano che i visitatori atterrano su una pagina prodotto tramite una Email Recommendation.

Queste richieste conterranno 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
}

Si consiglia di monitorare se l’URL include clerk_external: 1 e se presente, registrare il click con i dati ricevuti.

clerk_api contiene l’endpoint API con un carattere * per evitare problemi di encoding. Questo dovrebbe essere sostituito con / quando si registra il click. external: 1 deve essere aggiunto alla chiamata così Clerk sa che il click proviene da un’email.

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

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

Registrare i Prodotti #

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

Se usi endpoint che già richiedono l’ID prodotto (ad esempio recommendations/substituting o recommendations/complementary), Clerk.io registrerà automaticamente l’ID del prodotto.

Tuttavia, se non li utilizzi, 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
        }'

Registrare le Vendite #

L’AI di Clerk.io si basa molto sugli ordini per prevedere i risultati, quindi tracciarli in tempo reale è fondamentale. Per questo si utilizza l’endpoint log/sale.

Fornendo il visitor ID in questa chiamata, Clerk è in grado di capire quali prodotti sono stati mostrati, cliccati e infine acquistati. Questo consente all’AI di essere sempre aggiornata e modificare i risultati “al volo” in base al comportamento dei clienti.

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

L’id dei prodotti deve corrispondere agli ID che vengono registrati per i click. Ad esempio, per i prodotti configurabili dovresti tracciare l’ID del padre sia per log/click che per log/sale indipendentemente dalla variante acquistata.
Il price è il prezzo unitario. Verrà moltiplicato per la quantity nelle 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 il rate limiting per garantire un uso equo e mantenere la stabilità durante i picchi di traffico.

I limiti sono:

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

Le richieste all’interno di questi limiti non subiranno mai rate limiting. Le richieste che superano queste soglie potrebbero essere limitate, ma se ciò avvenga effettivamente dipende dalla capacità del server in quel momento.

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

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