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 tracciamento

Chiavi API #

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 consente l’accesso agli endpoint che espongono dati non sensibili, e da una Private Key che permette di lavorare con i dati dello Store e accedere a dati sensibili, come 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 desideri per scopi diversi.

1. Sincronizza i Dati #

Il primo passo è ottenere i dati in entrata, permettendo all’AI di Clerk.io di comprendere il tuo webshop e prevedere i risultati. Clerk sincronizza ogni dominio del 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 CRUD API, che ti consentono 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:

Una delle principali differenze 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 a utilizzare la CRUD API, è fortemente consigliato 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 bloccarsi o un attributo di prodotto potrebbe contenere un errore che causa il fallimento di diverse chiamate. Per evitare questi problemi, prendi in considerazione l’utilizzo di uno o più Data Feeds come backup quotidiano 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 lavora Clerk, fatta eccezione per gli ordini, che vengono registrati e non devono essere inclusi nel feed dopo la prima importazione.

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

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

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

I data feed devono essere disponibili a un URL accessibile all’importatore, che configuri nel backend di my.clerk.io in System status > Data Sync. Puoi mettere in sicurezza il feed, così che solo il nostro importatore possa accedervi.

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

Endpoint #

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, le migliori alternative richiedono products, ovvero 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.

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 a un endpoint Search per trovare i migliori prodotti per una ricerca di “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"]
        }'

Debugging delle risposte #

Quando il debug è abilitato per una richiesta, le risposte dell’API includono un array debug che mostra, in ordine, come le diverse funzionalità hanno influito sui 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. Visualizza Risultati #

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

Per visualizzare i tuoi dati, puoi effettuare chiamate API lato server, recuperare gli ID dei prodotti corrispondenti e quindi recuperare tutte le informazioni specifiche sui prodotti 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 qualsiasi informazione specifica della risorsa 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 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 #

Il tracking deve essere aggiunto per mantenere l’AI di Clerk aggiornata e personalizzare i risultati per un visitatore durante la sua sessione. Sono richiesti 4 passaggi:

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

Crea Visitor ID #

Il session ID è anche chiamato Visitor ID. È necessario per tenere traccia dell’attività dell’utente durante una sessione sul webshop, inclusi i prodotti su cui cliccano, le ricerche e le categorie che visitano.

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

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

Ad esempio, potresti utilizzare la funzione uniqid() di PHP per generare ID univoci 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 una ricerca di corrispondenze o alternative su una pagina prodotto. L’argomento labels è una lista contenente almeno una stringa, che dovrebbe essere l’etichetta descrittiva di questa chiamata.

Raccomandiamo di usare etichette che descrivano la pagina in cui 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"]
        }'

Registra i Click #

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

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

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

Search & Recommendations #

Il logging dei click è fatto aggiungendo i parametri alla chiamata in base all’endpoint utilizzato per mostrare il prodotto cliccato. È semplice, poiché utilizza i dati della configurazione realizzata.

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 dalle richieste GET inoltrate da Clerk.io. Devi monitorare se l’URL include parametri che indicano che i visitatori atterrano su una pagina prodotto da 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 contiene 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 codifica. Questo dovrebbe essere cambiato in / quando si registra il click. external: 1 deve essere aggiunto alla chiamata affinché Clerk sappia che il click proviene da una email.

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

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

Registra Prodotti #

Quando i visitatori visualizzano le pagine dei prodotti, questo deve essere registrato in modo che possa essere utilizzato per 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 usi questi endpoint, è 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
        }'

Registra Vendite #

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

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

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

L’id dei prodotti deve corrispondere agli ID registrati per i click. Ad esempio, per i prodotti configurabili dovresti tracciare l’ID del genitore sia in log/click che in log/sale indipendentemente dalla variante acquistata.
Il 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

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