Enhver (webshop)

API

En fleksibel måde at integrere serverside.

Al kommunikation med Clerk foregår via API’et:

https://api.clerk.io/v2

Opsætning af denne kommunikation kræver 4 trin, som gennemgås 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 data fra din Store. De findes i my.clerk.io > Developers > API Keys.

De består af en Public key, der giver adgang til endpoints med ikke-følsomme data, og en Private Key, der gør det muligt at arbejde med data på Store og få adgang til følsomme data, som kunde- og ordreinformation.

Private Keys kan kun vises én gang efter oprettelse af sikkerhedsmæssige årsager, og du kan oprette så mange, du har brug for, til forskellige formål.

1. Synkroniser data #

Første trin er at få data ind, så Clerk.io’s AI kan forstå din webshop og forudsige resultater. Clerk synkroniserer hvert webshopdomæne som sin egen unikke Store-instans, som tilgås af et sæt API Keys.

CRUD API #

Du kan synkronisere dine data ved hjælp af CRUD API endpoints, der gør det muligt at gette, 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": "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
                }
             ]
           }'

De tilgængelige objekter er:

En af Clerks primære differentieringsfaktorer er, at der ikke er nogen indlæringsperiode, da vi kan udnytte alle eksisterende ordrer fra dag ét til at forstå aktuel kundeadfærd.

Data Feeds #

Ud over at bruge CRUD API’et anbefales det stærkt at tilføje en backup-metode til synkronisering. Der kan jo opstå fejl ved API-kald.

F.eks. kan din pristjeneste gå ned, eller et produkt-attribut kan indeholde fejl, hvilket får flere kald til at fejle. For at undgå disse problemer bør du overveje at bruge en eller flere Data Feeds som daglig backup til dine CRUD-kald.

Data feeds er én eller flere JSON-filer, der indeholder webshoppens aktuelle katalog.

Alle data i feedet, når det indlæses, vil være dem, Clerk arbejder med, bortset fra ordrer, som logges og ikke behøver at være i feedet efter første import.

Brug af data feed er også en god måde at forudindlæse Clerk med ordrer på.

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

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

Data feed(s) skal være tilgængelige på en URL, som kan tilgås af importøren, hvilket du konfigurerer i my.clerk.io backend i System status > Data Sync. Du kan sikre feedet, så kun vores importør har adgang.

2. Hent data #

Når data er synkroniseret, analyserer AI’en det og opbygger intelligente indeks, der kan hentes via unikke endpoints afhængigt af use-case.

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

Endpoints #

Alle endpoints kræver, at du sender public API key.

Endpoints, der returnerer resultater, kræver også argumentet “limit” for at styre antallet af returnerede resultater.

Yderligere parametre afhænger af det specifikke endpoint. F.eks. kræver bedste alternativer products, som er en liste med produkt-ID’er til at finde tilbehør til, og alle søge-relaterede kald behøver parameteren query til at finde match.

Du kan finde 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 match.

Herunder ses et eksempel på et kald til et Search 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"]
        }'

Recommendations #

Herunder ses et eksempel på et kald til et Recommendations endpoint for at finde de mest populære 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"]
        }'

Respons-debugging #

Når debugging er aktiveret for en request, indeholder API-svar et debug array, der i rækkefølge viser, hvordan forskellige funktioner påvirkede resultaterne. Hver post indeholder et feature, en læsbar message, og struktureret metadata, der beskriver de konkrete effekter.

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

Clerk’s API returnerer altid ID’er på de matches, der findes, når der returneres resultater.

For at visualisere dine data kan du lave API-kald serverside, hente ID’erne på de matchende produkter og derefter hente alle de produktspecifikke informationer fra din webshopplatform eller PIM, før de vises.

Kald

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

Svar

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

Clerk’s API kan også konfigureres til at sende tilbage alle ressourcerelaterede informationer, som du sender til Clerk, fx priser, brandnavne, kategori-URL’er, blog-forsidebilleder og meget mere.

Med dette har du ofte ikke brug for at lave individuelle kald til dit PIM før visning af resultater, hvilket får din side til at indlæse hurtigere.

Kald

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

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. Tracking #

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

  1. Generér en session ID for hver besøgende.
  2. Tilføj beskrivende labels til API-kald, der returnerer resultater.
  3. Log en besøgendes klik på produkter vist af Clerk.
  4. Log hver ordre foretaget på webshoppen.

Opret Visitor ID #

Session ID’en kaldes også Visitor ID. Den er påkrævet for at logge en brugers aktivitet under en session på webshoppen, herunder produkter de klikker på, deres søgninger og kategorier de besøger.

Denne aktivitet gemmes for hver Store, og Clerk.io deler den aldrig på tværs af Stores.

Et visitor ID er blot en streng, der bruges til at identificere sessionen. Det kan være vilkårlige alfanumeriske tegn, og vi anbefaler at holde dem på maksimalt 8 tegn for bedst ydeevne.

For eksempel kan du bruge PHP’s uniqid() funktion til at generere ID’er, der er unikke for i det mindste den aktuelle session. Når det er genereret, skal dette ID medtages i alle kald til Clerk.io’s API for at tracking virker.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Tilføj Labels #

Labels skal tilføjes til alle kald, der returnerer resultater, såsom søgematch eller alternativer på en produktside. Argumentet labels er en liste med mindst én streng, der bør være den beskrivende label for dette kald.

Vi anbefaler at bruge labels, der beskriver siden, hvor kaldet bruges, og resultat-typen der vises. Et eksempel kan være Homepage - Trending. Dette gør det let at adskille dem i 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"]
        }'

Log klik #

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

Det er vigtigt kun at lave dette kald, når produktet der klikkes på faktisk vises af Clerk.io og ikke webshopplatformen selv. Ellers vil det se ud som om alle produkter findes via Clerk.

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

Search & Recommendations #

Logging af klik foretages ved at tilføje parametre til kaldet, afhængigt af det endpoint, der blev brugt til visning. Det 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 Recommendations #

Logging af klik fungerer anderledes, da du vil modtage data fra GET requests, 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 Recommendation.

Disse requests indeholder altid følgene query parametre:

{
  "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 holde øje med om URL’en inkluderer clerk_external: 1 og, hvis det gør, logge klikket med de data, du modtager.

clerk_api indeholder API endpointet med et * tegn for at undgå encode-problemer. Dette bør skiftes til / ved logging af klik. external: 1 skal tilføjes til kaldet, så Clerk ved, at klikket stammer fra en email.

Her er et eksempel på et log/click kald, der benytter 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 – især dem, der relaterer sig til besøgende som Visitor Recommendations eller Visitor Alternatives.

Hvis du bruger endpoints, der allerede kræver produkt ID for at virke, som recommendations/substituting eller recommendations/complementary, logger Clerk.io automatisk produkt ID’et.

Hvis ikke, skal du lave et separat kald til log/product, med det ID for det produkt, der bliver set.

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 kunne forudsige resultater, så tracking af dem i realtid er afgørende. End-pointet log/sale bruges til dette.

Med visitor ID inkluderet i dette kald, vil Clerk forstå hvilke produkter der blev vist, klikket og til sidst købt. Dette gør det muligt konstant at holde AI’en opdateret og at tilpasse resultater on-the-fly efter kundeadfærd.

Dette kald kobler også Visitor ID til e-mailadressen eller kunde-ID for køberen, så der kan personliggøres endnu mere gennem kunde-specifikke anbefalinger.

id på produkter skal matche ID’erne, der logges for klik. F.eks. skal du tracke parent ID for konfigurerbare produkter i både log/click og log/sale uanset hvilken variant der købes.
price er enhedsprisen. Den bliver ganget 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

Rate Limiting #

API’et bruger rate limiting for at sikre fair brug og opretholde stabilitet under perioder med spidsbelastning.

Grænserne er:

  • 50 forespørgsler per sekund per Store
  • 100 forespørgsler per sekund per IP-adresse

Forespørgsler indenfor disse grænser vil aldrig blive rate-limited. Forespørgsler over disse grænser kan blive rate-limited, men om dette faktisk sker, afhænger af serverkapaciteten på det givne tidspunkt.

Clerk.io skalerer sin infrastruktur dynamisk. Under trafikspidser som Black Friday startes flere servere op, så kapaciteten er langt højere end de grundlæggende grænser antyder.

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