Enhver (webshop)

API

En fleksibel måde at integrere serverside.

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

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 i din Store. De findes i my.clerk.io > Developers > API Keys.

De består af en Public key, som giver adgang til endepunkter, der viser ikke-følsomme data, og en Private Key, som giver dig mulighed for at arbejde med data på Store og få adgang til følsomme data, såsom kunde- og ordreinformation.

Private Keys kan kun ses én gang efter oprettelsen 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 via et sæt API-nøgler.

CRUD API #

Du kan synkronisere dine data ved hjælp af CRUD API-endepunkterne, som giver dig mulighed for at get, post, update og delete 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 differentieringspunkter er, at der ikke er nogen indlæringsperiode, da vi kan udnytte alle eksisterende ordrer fra dag ét for at forstå nuværende kundeadfærd.

Data Feeds #

Ud over at bruge CRUD API’et, anbefales det kraftigt at tilføje en backup-synkroniseringsmetode. Der kan trods alt gå meget galt med API-kald.

For eksempel kan din prisserver crashe, eller et produktegenskab kan indeholde en fejl, der får flere kald til at fejle. For at undgå disse problemer, overvej at bruge en eller flere Data Feeds som daglig backup for dine CRUD-kald.

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

Alle data, der er tilgængelige 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 første import.

Brug af data feedet 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 importøren, som du opsætter i my.clerk.io backend under System status > Data Sync. Du kan sikre feedet, så kun vores importør kan få adgang.

2. Hent data #

Når data er synkroniseret, analyseres de af AI’et og der bygges intelligente indeks, der kan hentes gennem unikke endepunkter afhængigt af use-case.

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

Endepunkter #

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

Endepunkter, der returnerer resultater, kræver også argumentet “limit” for at kontrollere, hvor mange resultater der skal returneres.

Yderligere parametre afhænger af det endepunkt, du kalder. F.eks. kræver de bedste alternativer products, som er en liste over produkt-ID’er til at finde tilbehør, og alle søge-relaterede kald kræver parameteren query for at finde matches.

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

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

Nedenfor er et eksempel på at lave et kald til et Search-endepunkt 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 er et eksempel på et kald til Recommendations-endepunktet 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"]
        }'

Fejlfinding af svar #

Når fejlfinding er aktiveret for et kald, inkluderer API-svarene et debug array, der viser i rækkefølge, hvordan forskellige funktioner påvirkede resultaterne. Hver post inkluderer en feature, en læsbar message og struktureret metadata, der beskriver de specifikke 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. Visualisér resultater #

Clerk’s API returnerer altid ID’er på de matches, det fandt, 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 al produkt-specifik information 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 alle ressource-specifikke oplysninger, som du sender til Clerk tilbage, såsom priser, mærkenavne, kategori-URL’er, blogbilleder og meget mere.

På denne måde behøver du ofte ikke lave individuelle kald til din PIM, før du viser resultater, hvilket vil gøre din side hurtigere at indlæse.

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 sessionen. Det kræver 4 trin:

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

Opret Visitor ID #

Session-ID’et kaldes også Visitor ID. Det kræves 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 lagres for hver Store, og Clerk.io deler aldrig disse på tværs af Stores.

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

For eksempel kunne du bruge PHP’s uniqid()-funktion til at generere ID’er, der er unikke for mindst den aktuelle session. Når den er genereret, skal dette ID inkluderes i alle kald til Clerk.io’s API for at tracking fungerer.

<?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øgeresultater eller alternativer på en produktside. Argumentet labels er en liste, der indeholder mindst én streng, som bør være den beskrivende label for dette kald.

Vi anbefaler at bruge labels, der beskriver siden, hvor kaldet bruges og typen af resultater, det viser. Et eksempel kunne være Homepage - Trending. Det gør dem lette 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-endepunktet.

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 endepunktet, brugt til at vise produktet, der blev klikket på, og product, som indeholder ID’et for det klik-kede produkt.

Search & Recommendations #

Logging af klik gøres ved at tilføje parametrene til kaldet baseret på det endepunkt, der bruges til at vise produktet, 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 Recommendations #

Logging af klik fungerer anderledes, da du får dataene fra GET-requests, der videresendes af Clerk.io. Du bør monitorere, 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 monitorere om URL’en inkluderer clerk_external: 1, og hvis ja, logge klikket med de modtagne data.

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

Her er et eksempel på et log/click-kald med 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, skal dette logges, så det kan bruges til at personalisere resultater – særligt besøgsrelaterede som Visitor Recommendations eller Visitor Alternatives.

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

Men hvis du ikke gør det, skal du lave et separat kald til log/product, med ID’et på det viste produkt.

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øglen. log/sale-endepunktet bruges til dette.

Når visitor ID inkluderes i dette kald, forstår Clerk, hvilke produkter der blev vist, klikket på og endelig købt. Dette gør det muligt for AI’et altid at være opdateret og ændre resultaterne løbende baseret på kundeadfærd.

Dette kald forbinder også Visitor ID med e-mailadressen eller kunde-ID’et på køberen, hvilket giver endnu bedre personalisering gennem kunde-specifikke anbefalinger.

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

Grænserne er:

  • 50 requests per sekund per Store
  • 100 requests per sekund per IP-adresse

Forespørgsler inden for disse grænser vil aldrig opleve rate limiting. Forespørgsler, der overskrider disse tærskler, kan blive rate limited, men om det rent faktisk sker afhænger af den aktuelle serverkapacitet.

Clerk.io skalerer sin infrastruktur dynamisk. Under højtrafikker som Black Friday sættes flere servere i drift for at håndtere den øgede belastning, hvilket betyder, at den effektive kapacitet er langt højere end de basale grænser antyder.

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