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, che sono illustrati in questa guida. Devi:

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

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 chiave pubblica, che permette l’accesso agli endpoint che espongono dati non sensibili, e una chiave privata che consente di lavorare con i dati dello Store e accedere ai dati sensibili, come informazioni su clienti e ordini.

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

1. Sincronizzare i Dati #

Il primo passaggio è inserire i dati, permettendo all’AI di Clerk.io di capire il tuo webshop e prevedere i risultati. Clerk sincronizza ogni dominio del webshop come una propria istanza unica di Store, 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 ottenere, inviare, aggiornare ed eliminare 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’è alcun periodo di apprendimento, poiché possiamo utilizzare tutti gli ordini esistenti fin dal primo giorno per comprendere il comportamento attuale dei clienti.

Data Feeds #

Oltre a utilizzare la CRUD API, è altamente consigliato aggiungere un metodo di sincronizzazione di backup. Dopotutto, molte cose possono andare storte con le chiamate API.

Ad esempio, il tuo server prezzi potrebbe andare in crash oppure un attributo di un prodotto potrebbe contenere un errore che fa fallire più chiamate. Per evitare questi problemi, considera l’uso di uno o più Data Feeds come backup giornaliero delle tue chiamate CRUD.

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

Qualsiasi dato presente nel feed al momento del caricamento sarà quello su cui Clerk lavorerà, eccetto 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 pre-caricare Clerk con gli ordini.

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

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

Il/i feed di dati devono essere disponibili a un URL accessibile dall’importer, che configuri nel backend my.clerk.io in System status > Data Sync. Puoi proteggere il feed, affinché solo il nostro importer 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 ottenere i prodotti più popolari, puoi usare l’endpoint recommendations/trending, e per mostrare i prodotti principali di una ricerca su “star wars,” puoi usare l’endpoint search/predictive.

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.

Gli altri parametri dipendono dall’endpoint che stai chiamando. Ad esempio, le migliori alternative richiedono products che è una lista di ID prodotto per individuare gli accessori, e tutte le chiamate relative alla ricerca hanno bisogno del parametro query per trovare le corrispondenze.

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

Di default, l’API di Clerk restituisce tutti i risultati disponibili, ma se necessario puoi usare Filtri per definire un sottoinsieme di corrispondenze.

Di seguito un esempio di chiamata ad un endpoint Search per trovare i migliori prodotti di 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 di tendenza.

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 delle risposte #

Quando il debugging è attivo per una richiesta, le risposte API includono un array debug che mostra, nell’ordine, come le diverse funzionalità hanno influenzato i risultati. Ogni voce comprende una feature, un message leggibile e un metadata strutturato che descrive 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 durante la restituzione dei risultati.

Per visualizzare i tuoi dati, puoi effettuare chiamate API lato server, recuperare gli ID dei prodotti corrispondenti e poi recuperare tutte le informazioni specifiche sul prodotto dalla tua piattaforma webshop o dal 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 tutte le informazioni specifiche della risorsa che invii a Clerk, come prezzi, marchi, URL di categoria, immagini di copertina del blog e altro.

In questo modo, spesso non sarà necessario effettuare chiamate singole al tuo PIM prima di mostrare i risultati, rendendo più veloce 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. Tracking #

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

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

Creare il Visitor ID #

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

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

Un visitor ID è semplicemente una stringa che identifica la sessione. Può essere composta da qualsiasi carattere alfanumerico e si consiglia di limitarla a massimo 8 caratteri per prestazioni ottimali.

Ad esempio, potresti usare 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 il tracking.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Aggiungere le Etichette #

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

Si consiglia di utilizzare etichette che descrivano la pagina dove viene usata la chiamata e il tipo di risultati visualizzato. Un esempio può essere Homepage - Trending. Questo le rende facilmente distinguibili nell’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 con l’endpoint log/click.

È importante fare questa chiamata solo quando il prodotto cliccato è effettivamente mostrato da Clerk.io e non dalla piattaforma del webshop stesso. Altrimenti risulterà che tutti i prodotti sono trovati tramite Clerk.

La chiamata deve anche includere api ovvero 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 cliccato. È semplice poiché utilizza dati della configurazione effettuata.

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 diversamente, poiché riceverai i dati da richieste GET inoltrate da Clerk.io. Dovresti monitorare se l’URL contiene parametri che indicano che i visitatori arrivano su una pagina prodotto da un’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
}

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

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

Ecco un esempio di chiamata log/click che usa 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
        }'

Registrare i Prodotti #

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

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

Tuttavia, se non li utilizzi, è necessario 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 l’Email #

Ogni volta che l’indirizzo email di un cliente noto è disponibile nella sessione — che abbia appena eseguito l’accesso o sia già ritornato loggato sul sito — va registrato tramite l’endpoint log/email.

Questo collega il loro visitor ID all’indirizzo email, che Clerk.io utilizza per attivare email automatiche in base al comportamento in sessione, personalizzare le recommendations mostrate nelle email e applicare campagne di Merchandising rivolte a segmenti di Audience specifici.

Senza questa chiamata, Clerk.io non ha modo di collegare una sessione di navigazione a un indirizzo email, a meno che il visitatore non completi un acquisto.

Effettua la chiamata una sola volta per sessione quando hai a disposizione l’email. Evitala completamente per i visitatori ospiti:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/email' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}'

Registrare le Vendite #

L’AI di Clerk.io si basa fortemente sugli ordini per prevedere i risultati, quindi è fondamentale monitorarli in tempo reale. Si usa l’endpoint log/sale.

Con il visitor ID incluso nella chiamata, Clerk saprà quali prodotti sono stati mostrati, cliccati e infine acquistati. Questo permette all’AI di restare sempre aggiornata e di modificare i risultati in tempo reale in base al comportamento del cliente.

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

L’id dei prodotti deve coincidere con gli ID registrati per i click. Ad esempio, per prodotti configurabili dovresti tracciare l’ID principale 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

Rate Limiting #

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

I limiti sono:

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

Le richieste entro questi limiti non subiscono mai limitazioni. Le richieste che eccedono queste soglie possono essere limitate, ma se questo avviene o meno dipende dalla capacità attuale del server.

Clerk.io scala dinamicamente la propria infrastruttura. Durante eventi ad alto traffico come il Black Friday, vengono aggiunti 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.