Enhver (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 vejledning. Du skal:

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

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 i 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 webshopdomæne som sin egen unikke butikinstans, som tilgås via 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": "Grøn Lightsaber",
                  "description": "Antik rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Dødsstjernen Deluxe",
                  "description": "Dødsstjernen. Fejlsikker."
                  "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å den 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 mislykkes. 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 være inkluderet i feedet efter den første import.

At bruge datafeedet er også en god 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 Systemstatus > 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 alle søge-relaterede 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 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": ["Søgning - 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": ["Hjemmeside - 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 webshopplatform eller PIM, før du gengiver dem.

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": ["Hjemmeside - Trending"]
        }'

Svar

{
    "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, blogcoverbilleder 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": ["Hjemmeside - Trending"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

Svar

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

Sporing 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 foretaget på webshoppen.

Opret besøgendes ID #

Session-ID’et kaldes også besøgendes ID. Det er nødvendigt for at logge en brugers aktivitet under en session på webshoppen, herunder 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øgendes 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 i mindst den nuværende session. Når det er genereret, skal dette ID inkluderes i alle opkald til Clerk.io’s API for at sporing 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 skal være den beskrivende etiket for dette opkald.

Vi anbefaler at bruge etiketter, der beskriver siden, hvor opkaldet bruges, og typen af resultater, det viser. Et eksempel kunne være Hjemmeside - 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": ["Hjemmeside - 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 bruges 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 gø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": ["Hjemmeside - 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": "Velkomstemail - Bedst sælgende",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Velkomstemail - Bedst sælgende",
  "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, log 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 klikket 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": ["Velkomstemail - Bedst sælgende"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Log produkter #

Når besøgende ser produktsider, skal dette logges, så det kan bruges til at personalisere resultater - specifikt de besøgendes relaterede som Besøgendes Anbefalinger eller Besøgendes 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 browses.

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å sporing af disse i realtid er nøglen. Endpointet log/sale bruges til dette.

Med besøgendes ID 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 i realtid baseret på kundeadfærd.

Dette opkald forbinder også besøgendes ID med e-mailadressen eller kunde-ID’et for køberen, hvilket muliggør endnu bedre personalisering gennem kundespecifikke anbefalinger.

id 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 er købt.
price er enhedsprisen. Den vil blive multipliceret med quantity i analyser.
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.