Enhver (webshop)

API

En fleksibel måde at integrere serverside på.

Al kommunikation med Clerk foregår via 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 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 endpoints, der viser ikke-følsomme data, og en Private Key, som tillader dig 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 de er oprettet af sikkerhedsmæssige årsager, og du kan oprette så mange som 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, som tilgås med et sæt API Keys.

CRUD API #

Du kan synkronisere dine data ved at bruge CRUD API endpoints, som giver dig mulighed for 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 styrker er, at der ikke er nogen læringsperiode, da vi kan anvende alle eksisterende ordrer fra dag ét til at forstå nuværende kundeadfærd.

Data Feeds #

Ud over at bruge CRUD API anbefales det stærkt at tilføje en backup-synkroniseringsmetode. Mange ting kan gå galt med API-kald.

For eksempel kan din prisserver gå ned, eller et produktattribut 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 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 på det tidspunkt, det indlæses, er det Clerk arbejder med, undtagen ordrer, som logges og ikke behøver at blive inkluderet i feedet efter første import.

Brug af datafeedet 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, der kan tilgås af importøren, hvilket du kan konfigurere i my.clerk.io backend under System status > Data Sync. Du kan sikre feedet, så kun vores importør kan tilgå det.

2. Hent Data #

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

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

Endpoints #

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

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

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

Du kan finde 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 Filters bruges til at definere et delmængde af matches.

Nedenfor ses et eksempel på et kald til et Search endpoint for at finde top-produkterne ved 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 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"]
        }'

Svar-debugging #

Når debugging er aktiveret for en forespørgsel, inkluderer API-svarene et debug array, som viser i rækkefølge, hvordan forskellige funktioner påvirkede resultaterne. Hvert element inkluderer et feature, en menneskelæselig message og struktureret metadata, der beskriver effekterne.

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

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

For at visualisere dine data kan du lave API-kald serverside, hente ID’erne på de matchende produkter og derefter hente alle produkt-specifikke oplysninger fra dit 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 ressourcenspecifikke informationer, som du sender til Clerk, så som priser, mærkenavne, kategori-URL’er, blogforsidebilleder med mere.

Med dette behøver du ofte ikke lave individuelle kald til din PIM før visning af resultater, hvilket får siden 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. Generer et 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, der udføres på webshoppen.

Opret Visitor ID #

Session-ID’et kaldes også Visitor ID. Det skal bruges til 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 aldrig på tværs af Stores.

Et visitor ID er bare en streng, der bruges til at identificere sessionen. Den kan være ethvert alfanumerisk tegn, men vi anbefaler maksimalt 8 tegn for bedst ydeevne.

For eksempel kan du bruge PHP’s uniqid(), funktion til at generere unikke ID’er for den aktuelle 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øgematches eller alternativer på en produktside. Argumentet labels er en liste, som indeholder mindst én streng, som bør være denne kaldes beskrivende label.

Vi anbefaler at bruge labels, der beskriver siden, hvor kaldet bruges, samt typen af resultater den viser. Et eksempel kunne være Homepage - Trending. Det gør det nemt 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 skal logge hvert klik på et Clerk.io produkt med endpointet log/click.

Det er vigtigt kun at lave dette kald, når produktet faktisk vises af Clerk.io og ikke af webshop-platformen selv. Ellers vil det se ud som om alle produkter findes gennem Clerk.

Kaldet skal også indeholde api, som er det endpoint, der blev brugt til at vise produktet, der blev klikket på, samt product, der indeholder ID på produktet, der blev klikket.

Search & Recommendations #

Logning af klik sker 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 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 vil modtage data fra GET requests, der viderestilles af Clerk.io. Du bør overvåge, om URL’en indeholder parametre, der viser, at besøgende lander på en produktside fra en Email Recommendation.

Disse forespørgsler 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 det er tilfældet, at logge klikket med de data, du modtager.

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

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, skal dette logges, så det kan bruges til at personalisere resultater - specifikt de besøgsrelaterede som Visitor Recommendations eller Visitor Alternatives.

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

Men hvis du ikke bruger disse, skal du lave et separat kald til log/product, med ID’et på 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 forudsige resultater, så tracking af disse i realtid er afgørende. Endpointet log/sale bruges til dette.

Når visitor ID’en inkluderes i dette kald, vil Clerk forstå, hvilke produkter der blev vist, klikket på og til sidst købt. Det tillader AI’en altid at være opdateret og ændre resultater hurtigt 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 via kundespecifikke anbefalinger.

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

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