Any (webshop)

API

En fleksibel måde at integrere serverside.

Al kommunikation med Clerk foregår gennem API’en:

https://api.clerk.io/v2

Opsætning af denne kommunikation kræver 4 trin, som er beskrevet i denne guide. Du skal:

  1. Synkronisere data
  2. Hente resultater
  3. Visualisere resultaterne
  4. Tilføje tracking

API-nøgler #

Disse nøgler bruges til at få adgang til dataene fra din butik. De findes i my.clerk.io > Indstillinger > API-nøgler.

De består af en offentlig nøgle, som giver adgang til endpoints, der eksponerer ikke-følsomme data, og en privat nøgle, som giver dig mulighed for at arbejde med data på butikken og få adgang til følsomme data, såsom kunde- og ordreinformation.

Private nøgler kan kun ses én gang efter at være oprettet af sikkerhedsmæssige årsager, og du kan oprette så mange, som du har brug for til forskellige formål.

1. Synkronisere data #

Det første skridt er at få data ind, så Clerk.io’s AI kan forstå din webshop og forudsige resultater. Clerk synkroniserer hver webshop-domæne som sin egen unikke butikinstans, som tilgås af et sæt API-nøgler.

CRUD API #

Du kan synkronisere dine data ved hjælp af CRUD API-endpoints, som giver dig mulighed for at hente, poste, opdatere og slette ressourcer efter behov.

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

De tilgængelige objekter er:

En af Clerk’s primære differentieringsfaktorer er, at der ikke er nogen læringsperiode, da vi kan udnytte alle eksisterende ordrer fra dag ét for at forstå nuværende kundeadfærd.

Datafeeds #

Ud over at bruge CRUD API’en, anbefales det stærkt at tilføje en backup synkroniseringsmetode. Trods alt kan mange ting gå galt med API-opkald.

For eksempel kan din prisserver gå ned, eller et produktattribut kan indeholde en fejl, der får flere opkald til at fejle. For at undgå disse problemer, overvej at bruge en eller flere Datafeeds som en daglig backup for dine CRUD-opkald.

Datafeeds er en eller flere JSON-filer, der indeholder webshoppens nuværende katalog.

Enhver data, der er tilgængelig i feedet, når det indlæses, vil være det, Clerk arbejder med, undtagen ordrer, som logges og ikke behøver at blive inkluderet i feedet efter den første import.

At bruge datafeedet er også en fantastisk måde at forudindlæse Clerk med ordrer.

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

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

Datafeedene skal være tilgængelige på en URL, der kan tilgås af importøren, som du konfigurerer i my.clerk.io backend i System status > Data Sync. Du kan sikre feedet, så kun vores importør kan få adgang til det.

2. Hente data #

Når data er synkroniseret, analyserer AI’en det og bygger intelligente indekser, der kan hentes gennem unikke endpoints afhængigt af brugssagen.

F.eks. for at hente de hotteste produkter, kan du bruge recommendations/trending endpointet, og for at vise de bedste produkter til en søgning på “star wars,” kan du bruge search/predictive endpointet.

Endpoints #

Alle endpoints kræver, at du sender den offentlige API-nøgle.

Endpoints, der returnerer resultater, kræver også argumentet " limit" for at kontrollere antallet af resultater, der skal returneres.

Yderligere parametre afhænger af det endpoint, du kalder. F.eks. de bedste alternativer kræver products, som er en liste over produkt-ID’er for at finde tilbehør til, og enhver søgerelateret opkald har brug for query parameteren for at finde match.

Du kan finde de nødvendige argumenter for alle endpoints i vores API-dokumentation.

Som standard returnerer Clerk’s API alle tilgængelige resultater, men hvis det er nødvendigt, kan Filtre bruges til at definere et delmængde af matches.

Søgning #

Nedenfor er et eksempel på at foretage et opkald til et søge-endpoint for at finde de bedste produkter til en søgning på “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"]
        }'

Anbefalinger #

Nedenfor er et eksempel på at foretage et opkald til et anbefalings-endpoint for at finde de hotteste produkter.

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. Visualisere resultater #

Clerk’s API returnerer altid ID’erne på de matches, den fandt, når den returnerer resultater.

For at visualisere dine data kan du foretage API-opkald server-side, hente ID’erne på de matchende produkter og derefter hente alle produkt-specifikke oplysninger fra din webshop-platform eller PIM, før de vises.

Opkald

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

Respons

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null
}

Clerk’s API kan også konfigureres til at sende tilbage enhver ressource-specifik information, som du sender til Clerk, såsom priser, brandnavne, kategori-URL’er, blog-coverbilleder og mere.

Med dette behøver du ofte ikke at foretage individuelle opkald til din PIM, før du viser resultater, hvilket vil indlæse din side hurtigere.

Opkald

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

Respons

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

Tracking skal tilføjes for at holde Clerk’s AI opdateret og personalisere en besøgendes resultater under deres session. Det kræver 4 trin:

  1. Generere et session-ID for hver besøgende.
  2. Tilføje beskrivende etiketter til API-opkald, der returnerer resultater.
  3. Logge en besøgendes klik på produkter vist af Clerk.
  4. Logge hver ordre lavet på webshoppen.

Opret besøgende ID #

Session-ID’et kaldes også besøgende ID. Det er nødvendigt for at logge en brugers aktivitet under en session på webshoppen, inklusive produkter de klikker på, deres søgninger og kategorier de browser.

Denne aktivitet gemmes for hver butik, og Clerk.io deler aldrig det på tværs af butikker.

Et besøgende ID er blot en streng, der bruges til at identificere sessionen. Det kan være enhver alfanumerisk karakter, og vi anbefaler at holde dem til maksimalt 8 karakterer for den bedste ydeevne.

For eksempel kan du bruge PHP’s uniqid(), funktion til at generere ID’er, der er unikke for mindst den nuværende session. Når det er genereret, skal dette ID inkluderes i alle opkald til Clerk.io’s API for at tracking kan fungere.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Tilføj etiketter #

Etiketter skal tilføjes til alle opkald, der returnerer resultater, såsom søgematches eller alternativer på en produktside. Argumentet labels er en liste, der indeholder mindst én streng, som bør være den beskrivende etiket for dette opkald.

Vi anbefaler at bruge etiketter, der beskriver den side, hvor opkaldet bruges, og typen af resultater, det viser. Et eksempel kunne være Homepage - Trending. Dette gør dem nemme at skelne i analyser.

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

Du bør logge hvert klik på et Clerk.io produkt med log/click endpointet.

Det er vigtigt kun at foretage dette opkald, når det klikkede produkt faktisk vises af Clerk.io og ikke webshopplatformen selv. Ellers vil det se ud som om alle produkter findes gennem Clerk.

Opkaldet skal også indeholde api, som er endpointet, der blev brugt til at vise det produkt, der blev klikket på, og product, som indeholder ID’et på det produkt, der blev klikket på.

Søgning & Anbefalinger #

Logging af klik udføres ved at tilføje parametrene til opkaldet baseret på det endpoint, der blev brugt til at vise det produkt, der blev klikket på. Dette er ligetil, da det bruger data fra den opsætning, du selv har lavet.

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

Logging af klik fungerer anderledes, da du vil modtage data fra GET-anmodninger, der videresendes af Clerk.io. Du bør overvåge, om URL’en inkluderer parametre, der angiver, at besøgende lander på en produktside fra en Email Anbefaling.

Disse anmodninger vil altid indeholde følgende forespørgselsparametre:

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

Vi anbefaler at overvåge, om URL’en inkluderer clerk_external: 1, og hvis den gør, logge klik med de data, du modtager.

clerk_api indeholder API-endpointet med et * tegn for at undgå kodningsproblemer. Dette skal ændres til / når du logger klik. external: 1 skal tilføjes til opkaldet, så Clerk ved, at klik kommer fra en email.

Her er et eksempel på et log/click opkald, der bruger ovenstående data:

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

Når besøgende ser produktsider, bør dette logges, så det kan bruges til at personalisere resultater - specifikt de besøgende-relaterede som Besøgende Anbefalinger eller Besøgende Alternativer.

Hvis du bruger nogen endpoints, der allerede har brug for produkt-ID’et for at fungere, som recommendations/substituting eller recommendations/complementary, vil Clerk.io automatisk logge produkt-ID’et.

Men hvis du ikke bruger disse, skal du foretage et separat opkald til log/product, med ID’et på det produkt, der bliver browsed.

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

Clerk.io’s AI er stærkt afhængig af ordrer for at forudsige resultater, så tracking af disse i realtid er nøgle. Endpointet log/sale bruges til dette.

Med besøgende ID’et inkluderet i dette opkald, vil Clerk forstå, hvilke produkter der blev vist, klikket på, og endelig købt. Dette gør det muligt for AI’en altid at være opdateret og ændre resultaterne på farten baseret på kundeadfærd.

Dette opkald forbinder også besøgende ID’et med emailadressen eller kunde-ID’et på køberen, hvilket muliggør endnu bedre personalisering gennem kunde-specifikke anbefalinger.

ID’et på produkter skal matche de ID’er, der logges for klik. F.eks. for konfigurerbare produkter bør du spore forælderens ID i både log/click og log/sale uanset hvilken variant der købes.
price er enhedsprisen. Den vil blive multipliceret med quantity i 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

Denne side er oversat af en hjælpsom AI, og der kan derfor være sproglige fejl. Tak for forståelsen.