Enhver (webshop)

API

En fleksibel måde at integrere serverside på.

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

https://api.clerk.io/v2

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

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

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

1. Synkroniser Data #

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

CRUD API #

Du kan synkronisere dine data ved hjælp af CRUD API-endpoints, som tillader dig at hente, oprette, 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 vigtigste forskelle er, at der ikke er nogen indlæringsperiode, da vi kan bruge alle eksisterende ordrer fra dag ét til at forstå nuværende kundeadfærd.

Data Feeds #

Udover at bruge CRUD API’et anbefales det stærkt at tilføje en backup-synkroniseringsmetode. Der kan trods alt gå meget galt med API-kald.

For eksempel kan din prisserver gå ned, eller et produktattribut kan indeholde en fejl, som får flere kald til at fejle. For at undgå disse problemer bør du overveje at bruge en eller flere Data Feeds som en daglig backup for dine CRUD-kald.

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

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

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

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

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

Data feed(s) skal være tilgængelige på en URL, der kan tilgås af importeren, som du konfigurerer i my.clerk.io backend under System status > Data Sync. Du kan sikre feedet, så kun vores importer kan tilgå det.

2. Hent Data #

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

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

Endpoints #

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

Endpoints, der returnerer resultater, kræver desuden argumentet “limit” for at kontrollere antal resultater, der returneres.

Yderligere parametre afhænger af endpointet, du kalder. F.eks. kræver de bedste alternativer products, som er en liste med produkt-ID’er, der skal findes tilbehør til, og alle søgningsrelaterede kald kræver parameteren query for at finde match.

Du finder de nødvendige argumenter for alle endpoints i vores API documentation.

Som standard returnerer Clerk’s API alle tilgængelige resultater, men om nødvendigt kan Filtre bruges til at definere et underudvalg af match.

Nedenfor ses et eksempel på et kald til et Search-endpoint for at finde de bedste produkter for 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 #

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

Response debugging #

Når debugging er aktiveret for et request, indeholder API-responser et debug array, der viser, i rækkefølge, 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 match, den har fundet, når resultater returneres.

For at visualisere dine data kan du lave API-kald på serversiden, hente ID’erne på de matchende produkter og derefter hente alle produktspecifikke informationer fra din webshop-platform 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 al den ressource-specifikke information, du sender til Clerk, såsom priser, brandnavne, kategori-URL’er, blogforsidebilleder m.m.

På denne måde behøver du ofte ikke at lave individuelle kald til din PIM, før du viser resultater – det giver hurtigere indlæsning af din side.

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 for at personalisere en besøgendes resultater under deres session. Det kræver 4 trin:

  1. Generér et session-ID til 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, der gennemføres på webshoppen.

Opret Visitor ID #

Session-ID’et kaldes også Visitor ID. Det 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 mellem Stores.

Et visitor ID er blot en streng, der bruges til at identificere sessionen. Det kan være enhver alfanumerisk karakter, og vi anbefaler, at de maks. er 8 tegn for optimal performance.

For eksempel kan du bruge PHP’s uniqid(), funktion til at generere ID’er, der som minimum er unikke for nuværende session. Når det er genereret, skal dette ID inkluderes 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, som skal være denne calls beskrivende label.

Vi anbefaler at bruge labels, der beskriver siden, hvor kaldet bruges, og typen af resultater den viser. Et eksempel kunne være Homepage - Trending. Så er de nemme at skelne i analyseværktøjer.

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

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 det produkt, der klikkes på, faktisk vises af Clerk.io og ikke webshop-platformen selv. Ellers vil det se ud som om alle produkter findes via Clerk.

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

Search & Recommendations #

Kliks logges ved at tilføje parametrene til kaldet baseret på det endpoint, der blev brugt til at vise produktet. Dette er ligetil, da det bruger data fra din egen opsætning.

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 #

Logning af klik fungerer anderledes, da du modtager data fra GET-requests, der videresendes af Clerk.io. Du bør overvåge, om URL’en indeholder parametre, der indikerer, at besøgende lander på en produktside fra en Email Recommendation.

Disse requests vil altid indeholde følgende 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 overvåge, om URL’en indeholder clerk_external: 1, og hvis ja, at logge klikket med de data du modtager.

clerk_api indeholder API-endpointet med et *-tegn for at undgå encoding-problemer. Dette bør ændres til /, når klikket logges. external: 1 skal tilføjes til kaldet, så Clerk ved, at klikket kommer fra en e-mail.

Her er et eksempel på et log/click-kald, 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 – især de besøgsrelaterede såsom Visitor Recommendations eller Visitor Alternatives.

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

Bruger du dog ikke disse, skal du lave et separat kald til log/product med ID’et på det produkt, der bliver besøgt.

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

Når en kendt kundes e-mailadresse er tilgængelig i sessionen — uanset om de lige har logget ind eller er vendt tilbage til siden allerede logget ind — skal du logge den med log/email endpoint.

Dette kobler deres visitor ID sammen med deres e-mailadresse, som Clerk.io har brug for til at sende automatiserede e-mails baseret på sessionadfærd, personalisere anbefalinger vist inde i e-mails og anvende Merchandising-kampagner målrettet specifikke Audience-segmenter.

Uden dette kald har Clerk.io ingen måde at forbinde en browsingsession til en e-mailadresse, medmindre den besøgende gennemfører et køb.

Lav kaldet én gang pr. session, når en e-mail er tilgængelig. Spring det helt over for gæste-besøgende:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/email' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}'

Log Salg #

Clerk.io’s AI er i høj grad afhængig af ordrer for at forudsige resultater, så det er vigtigt at tracke disse i realtid. log/sale endpointet bruges til dette.

Når visitor ID er inkluderet i dette kald, vil Clerk forstå hvilke produkter, der blev vist, klikket på og endeligt købt. Dette giver AI’en mulighed for hele tiden at være opdateret og ændre resultater med det samme ud fra kundeadfærd.

Dette kald knytter også Visitor ID sammen med e-mailadresse eller kunde-ID på køberen, hvilket giver endnu bedre personalisering via kunde-specifikke anbefalinger.

id på produkter skal matche de ID’er, der logges for klik. For konfigurerbare produkter bør du spore forældrenes ID i både log/click og log/sale uanset hvilken variant der købes.
price er styksprisen. 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

Rate Limiting #

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

Grænserne er:

  • 50 requests i sekundet pr. Store
  • 100 requests i sekundet pr. IP-adresse

Requests inden for disse grænser vil aldrig opleve rate limiting. Requests over disse grænser kan opleve rate limiting, men om det faktisk sker afhænger af serverkapaciteten på det givne tidspunkt.

Clerk.io skalerer sin infrastruktur dynamisk. Under store trafikbegivenheder som Black Friday, tilføjes flere servere for at håndtere den øgede belastning, så den reelle kapacitet er langt højere end basisgrænserne antyder.

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