Any (webshop)

API

Un modo flessibile per integrare il server.

Tutte le comunicazioni con Clerk avvengono tramite l’API:

https://api.clerk.io/v2

Impostare questa comunicazione richiede 4 passaggi, che sono delineati in questa guida. È necessario:

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

Chiavi API #

Queste chiavi vengono utilizzate per accedere ai dati del tuo Negozio. Si trovano in my.clerk.io > Impostazioni > Chiavi API.

Consistono in una chiave pubblica, che consente l’accesso agli endpoint che espongono dati non sensibili, e una chiave privata che ti consente di lavorare con i dati del Negozio e accedere a dati sensibili, come informazioni sui clienti e sugli ordini.

Le chiavi private possono essere visualizzate solo una volta dopo essere state create per motivi di sicurezza, e puoi crearne quante ne hai bisogno per scopi diversi.

1. Sincronizzare i Dati #

Il primo passo è ottenere dati in, consentendo all’AI di Clerk.io di comprendere il tuo webshop e prevedere i risultati. Clerk sincronizza ogni dominio webshop come una propria istanza unica del Negozio, a cui si accede tramite un insieme di chiavi API.

API CRUD #

Puoi sincronizzare i tuoi dati utilizzando gli endpoint API CRUD, che ti consentono di ottenere, inviare, aggiornare e 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": "Lightsaber Verde",
                  "description": "Lightsaber ribelle antico.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. A prova di errore."
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Gli oggetti disponibili sono:

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

Feed Dati #

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

Ad esempio, il tuo server dei prezzi potrebbe andare in crash, o un attributo del prodotto potrebbe contenere un errore che causa il fallimento di diverse chiamate. Per evitare questi problemi, considera di utilizzare uno o più Feed Dati come backup quotidiano per le tue chiamate CRUD.

I feed dati sono uno o più file JSON contenenti il catalogo attuale dei webshop.

Qualsiasi dato disponibile nel feed quando viene caricato sarà ciò con cui Clerk lavora, eccetto per gli ordini, che vengono registrati e non devono essere inclusi nel feed dopo il primo import.

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

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

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

Il/ i feed dati devono essere disponibili a un URL che può essere accessibile dall’importatore, che configuri nel backend di my.clerk.io in Stato del sistema > Sincronizzazione dati. Puoi proteggere il feed, in modo che solo il nostro importatore possa accedervi.

2. Recuperare 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 es. per recuperare i prodotti più richiesti, puoi utilizzare l’endpoint recommendations/trending, e per visualizzare i prodotti migliori per una ricerca su “star wars,” puoi utilizzare l’endpoint search/predictive.

Endpoint #

Tutti gli endpoint richiedono di inviare la chiave API pubblica.

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 es. le migliori alternative richiedono products che è un elenco di ID prodotto per trovare accessori, e qualsiasi chiamata relativa alla ricerca ha bisogno del 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, Filtri possono essere utilizzati per definire un sottoinsieme di corrispondenze.

Ricerca #

Di seguito è riportato un esempio di chiamata a un endpoint di Ricerca per trovare i prodotti migliori 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": ["Ricerca - Predittiva"]
        }'

Raccomandazioni #

Di seguito è riportato un esempio di chiamata a un endpoint di Raccomandazioni 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"]
        }'

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 lato server, recuperare gli ID dei prodotti corrispondenti e poi recuperare tutte le informazioni specifiche del prodotto 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 di marca, URL di categoria, immagini di copertura del blog e altro ancora.

Con questo, spesso non è necessario effettuare chiamate individuali al tuo PIM prima di mostrare i risultati, il che caricherà la tua pagina più velocemente.

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": "Vaso Ovale Rosso Baccarat Eye Piccolo",
            "price": 520.0,
            "url": "https://admin.awesomestore.com/product/14df"
        },
        {
            "id": 13827,
            "image": "https://admin.awesomestore.com/image/51xs",
            "name": "Cucchiaio da Zuppa Verde 22cm Sabre Transat",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/51xs"
        },
        {
            "id": 12693,
            "image": "https://admin.awesomestore.com/image/62x1",
            "name": "Forchetta da Cena Blu Chiaro 22cm Sabre Transat",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/62x1"
        }
    ]
}

4. Tracciamento #

Il tracciamento deve essere aggiunto per mantenere l’AI di Clerk aggiornata e personalizzare i risultati di un visitatore durante la loro sessione. Richiede 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.

Creare ID Visitatore #

L’ID di sessione è anche chiamato ID Visitatore. È necessario per registrare l’attività di un utente durante una sessione sul webshop, inclusi i prodotti su cui clicca, le loro ricerche e le categorie che esplorano.

Questa attività è memorizzata per ogni Negozio, e Clerk.io non condivide mai queste informazioni tra i Negozi.

Un ID visitatore è semplicemente una stringa utilizzata per identificare la sessione. Può essere composto da qualsiasi carattere alfanumerico, e si consiglia di mantenerlo a un massimo di 8 caratteri per le migliori prestazioni.

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

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Aggiungere Etichette #

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

Si consiglia di utilizzare etichette che descrivano la pagina in cui viene utilizzata la chiamata e il tipo di risultati che mostra. Un esempio potrebbe essere Homepage - Trending. Questo le rende facili da distinguere nelle analisi.

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 Clic #

Dovresti registrare ogni clic su un prodotto 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 webshop stessa. Altrimenti, sembrerà che tutti i prodotti siano stati trovati tramite Clerk.

La chiamata dovrebbe contenere anche l’api che è l’endpoint utilizzato per mostrare il prodotto che è stato cliccato, e product che contiene l’ID del prodotto che è stato cliccato.

Ricerca e Raccomandazioni #

La registrazione dei clic viene effettuata aggiungendo i parametri alla chiamata in base all’endpoint utilizzato per mostrare il prodotto che è stato cliccato. Questo è semplice poiché utilizza i dati dalla configurazione che hai fatto tu 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
        }'

Raccomandazioni via Email #

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

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 sì, registrare il clic con i dati ricevuti.

clerk_api contiene l’endpoint API con un carattere * per evitare problemi di codifica. Questo dovrebbe essere cambiato in / quando si registra il clic. external: 1 dovrebbe essere aggiunto alla chiamata affinché 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
        }'

Registrare i Prodotti #

Quando i visitatori visualizzano le pagine prodotto, questo dovrebbe essere registrato in modo che possa essere utilizzato per personalizzare i risultati - specificamente quelli relativi ai visitatori come Raccomandazioni per Visitatori o Alternative per Visitatori.

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

Tuttavia, se non stai utilizzando questi, 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 fortemente sugli ordini per prevedere i risultati, quindi il tracciamento di questi in tempo reale è fondamentale. L’endpoint log/sale viene utilizzato per questo.

Con l’ID visitatore incluso in questa chiamata, Clerk comprenderà quali prodotti sono stati mostrati, cliccati e infine acquistati. Questo consente all’AI di rimanere sempre aggiornata e modificare i risultati al volo in base al comportamento dei clienti.

Questa chiamata associa anche l’ID Visitatore con l’indirizzo email o l’ID cliente dell’acquirente, consentendo una personalizzazione ancora migliore attraverso raccomandazioni specifiche per il cliente.

L’id dei prodotti dovrebbe corrispondere agli ID che sono registrati per i clic. Ad es. per prodotti configurabili dovresti tenere traccia dell’ID dei genitori sia in log/click che in log/sale, indipendentemente dalla variante acquistata.
price è il prezzo unitario. Sarà 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.