Any (webshop)

API

En fleksibel måde at integrere på serversiden.

Al kommunikation med Clerk sker via API’et:

https://api.clerk.io/v2

Opsætning af denne kommunikation kræver 4 trin, som er beskrevet i denne vejledning. Du skal synkronisere data, hente resultater, visualisere disse resultater og tilføje sporing for at holde AI’en opdateret.

Synkronisering af data #

Clerk synkroniserer hvert webshopdomæne, kaldet en Store, som sin egen unikke instans, der tilgås af et sæt API-nøgler,, som findes i Clerk admin :

Disse omfatter en offentlig nøgle, som giver adgang til slutpunkter, der udstiller ikke-følsomme data, og en privat nøgle. Når den private nøgle kombineres med den offentlige nøgle, kan du arbejde med data i butikken og få adgang til følsomme data, f.eks. kunde- og ordreoplysninger.

CRUD API #

Du kan synkronisere dine data ved hjælp af CRUD API-slutpunkterne, som giver dig mulighed for at få, indlæg, opdater 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": "osLqDAs5s2tlf3adpLv6Mp1hxxf6GfdDuSE0c2ftT2ot5F3",
          "products":[
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antiuque rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Guaranteed idiot proof. "
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

De tilgængelige ressourcer er:

En af Clerk’s primære forskelle er, at der ikke er nogen indlæringsperiode, da vi kan bruge alle eksisterende ordrer fra første dag til at forstå den aktuelle kundeadfærd.

Datafeed #

Ud over at bruge CRUD-API’en anbefales det stærkt at tilføje en backup-synkroniseringsmetode.

Når alt kommer til alt, kan mange ting gå galt med API-opkald. For eksempel kan din prisserver gå ned, eller en produktattribut kan indeholde en fejl, der får flere kald til at mislykkes. For at undgå disse problemer bør du overveje at bruge Datafeed som en daglig backup af dine CRUD-kald.

Feedet er en JSON-fil, der indeholder den aktuelle tilstand i en webshops katalog. Alle data, der er tilgængelige i feedet, når det indlæses, vil være det, Clerk arbejder med, bortset fra ordrer, som logges og ikke behøver at blive 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
  }
}

Datafeedet skal være tilgængeligt på en URL, som importøren kan få adgang til, og som du konfigurerer i my.clerk.io backend:

Du kan sikre feedet, så kun vores importør kan få adgang til det.

Hentning af data #

Når data er synkroniseret, analyserer AI’en dem og opbygger intelligente indekser, som kan hentes via unikke slutpunkter afhængigt af brugssituationen.

Hvis du f.eks. vil hente de hotteste produkter, kan du bruge endpointet recommendations/trending, og hvis du vil vise de bedste produkter til en søgning på “star wars”, kan du bruge endpointet search/predictive.

Slutpunkter #

Alle endpoints kræver, at du sender offentlig API-nøgle.

Endpoints, der returnerer resultater, kræver også argumentet " begrænsning" for at styre antallet af resultater, der skal returneres.

Yderligere argumenter afhænger af det endpoint, du kalder. For eksempel kræver komplementære produkter en liste over produkt-id’er for at finde tilbehør til, og alle søgerelaterede kald har brug for parameteren “forespørgsel” for at finde matches og så videre.

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

Som standard returnerer Clerks API alle tilgængelige resultater, men hvis det er nødvendigt, kan Filtre bruges til at definere en delmængde af matches.

Anbefalinger Eksempel #

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

Eksempel på søgning #

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

Visualisering af resultater #

Clerk’s API returnerer altid ID’er for de match, den har fundet, når den returnerer resultater.

// Call
curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 5,
          "labels": ["Homepage - Trending"]
        }'

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

For at visualisere dine data kan du foretage API-kald på serversiden, hente ID’erne for de matchende produkter og derefter hente alle de produktspecifikke oplysninger fra din webshop-platform eller PIM, før du gengiver dem.

ClerkAPI’en kan også konfigureres til at sende alle ressourcespecifikke oplysninger tilbage, som du sender til Clerk, f.eks. priser, mærkenavne, kategori-URL’er, blogforsidebilleder og meget mere. Med dette behøver du ofte ikke at foretage individuelle opkald til dit PIM, før du viser resultater, hvilket vil indlæse din side hurtigere.

// Call
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"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

// Response
{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693,
        12791,
        1546
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/2/8/2807199-baccarat-eye-small-oval-red-vase.jpg",
            "name": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "/"
        },
        {
            "id": 13827,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/1/t/1transatvj.jpg",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "/"
        },
        {
            "id": 12693,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/2/t/2transatdl.jpg",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "/"
        },
        {
            "id": 12791,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/1/8/1845244-baccarat-dom-perignon-champagne-flute-_set-of-2_.jpg",
            "name": "Baccarat Dom Perignon Champagne Flute (Set of 2)",
            "price": 260.0,
            "url": "/"
        },
        {
            "id": 1546,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/m/a/maison-berger-ocean-breeze-1-litre-lamp-refill.jpg",
            "name": "Maison Berger Ocean Breeze 1 Litre Lamp Refill",
            "price": 29.0,
            "url": "/"
        }
    ]
}

Sporing #

Til sidst skal der tilføjes sporing for at holde Clerk’s AI opdateret og personliggøre en besøgendes resultater i løbet af deres session. Clerk sporing opsættes i 4 trin:

  1. Generering af en sessions-ID for hver besøgende
  2. Tilføjelse af beskrivende sporingsetiketter til API-kald, der returnerer resultater, som bruges til at vise analyser for individuelle slutpunkter
  3. Logning af en besøgendes klik på produkter, der vises af Clerk
  4. Logning af hver ordre lavet på webshoppen

Besøgende (session) ID #

Sessions-id’et kaldes også besøgs-id’et med Clerk. Det er strengt nødvendigt for at logge en brugers aktivitet under en session på webshoppen, herunder produkter, der er klikket på, søgninger, der er foretaget, og kategorier, der er gennemset. Denne aktivitet gemmes for hvert domæne, og Clerk deler den aldrig på tværs af butikker.

Du kan f.eks. 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 ’s kald til Clerk, for at sporingen kan fungere.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Etiketter #

Labels skal tilføjes til ethvert kald, der returnerer resultater, f.eks. søgeresultater eller alternativer på en produktside. Argumentet labels er en liste, der indeholder mindst én streng, som skal være etiketten for dette kald.

Vi anbefaler at bruge labels, der indeholder den side, hvert kald bruges på, og den type resultater, det viser, som “Homepage - Trending”. Det gør det nemt at skelne mellem dem i analyserne.

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

Logning af klik #

Derefter skal du logge hvert klik på et Clerk -produkt med log/klik. Det er vigtigt, at kun foretager dette opkald, når det produkt, der klikkes på, faktisk vises af Clerk og ikke af selve webshop-platformen; ellers vil det se ud, som om alle -produkter findes via Clerk.

Inkluder produkt-id product , og ideelt set også api endpoint og labels fra det API-kald, der viste dette produkt. Hvis dette ikke er inkluderet, vil Clerk backtracke klikket til det sidste API-kald, der viste dette produkt.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --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
        }'

Logning af salg #

Til sidst skal du bruge log/salg til at spore hver ordre, så snart den er placeret på webshoppen. Med den besøgendes ID inkluderet i dette opkald vil Clerk forstå, hvilke produkter der blev vist, klikket på og til sidst købt. Det gør det muligt for AI’en altid at være opdateret og ændre resultaterne undervejs baseret på kundernes adfærd.

Det er vigtigt:

  • Produkternes id skal matche de ID’er, der er logget med log/click. For konfigurerbare produkter skal du f.eks. spore forældre-id’et i både log/click og log/sale, uanset hvilken variant der er købt.
  • price er enhedspris for produkter. Clerk multiplicerer det med antallet i vores 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

Detaljer om den besøgendes ID #

Som standard er Clerk.io uden madlavning og bruger anonyme besøgs-ID’er i stedet for at gemme cookies.

ID’et bruges til at levere analyser i Clerk.io’s Dashboards og til on-site funktionalitet som “Du har tidligere besøgt”-anbefalinger.

For flere detaljer om, hvordan Cookieless Personalisation fungerer, tjek denne artikel.

Hvad bruger vi ID’et til? #

Dashboards, analyser og attribuering.

Clerk.io sporer alle ordrer, der er afgivet på webshoppen, og sammenligner dem, der er påvirket af Clerk.io, med de ordrer, der ikke er påvirket.

Via besøgs-ID’et kan vi spore, hvornår en forbruger klikker på et produkt i et Clerk.io-element og fortsætter med at afgive en ordre, der indeholder det pågældende produkt, for at give mulighed for attribuering.

Funktionalitet på stedet

Gennem besøgs-ID’et indsamler vi ID’erne på de produkter, som en forbruger gennemser, og de søgninger, de foretager.

Dette giver os mulighed for at tilpasse anbefalinger på webshoppen, herunder bannere som “Vores anbefalinger til dig” og “Du har tidligere set”, der viser produkter, der er relateret til browsing på webshoppen.

Besøgs-ID’et og hvordan det fungerer #

Hvert opkald til Clerk.io vil indeholde det anonyme besøgs-ID, der er beskrevet ovenfor, så det kan bruges til de ovennævnte formål.

Når en besøgende skriver sin e-mailadresse på webshoppen og/eller afgiver en ordre, knyttes besøgs-ID’et til e-mailadressen, hvis salgssporing er aktiveret.

En e-mailadresse i Clerk.io kan indeholde flere Visitor ID’er, som kan ses på kundesiden i my.clerk.io:

Hvis en bruger accepterer cookies fra dit websted, kan du konfigurere Clerk til at tilføje en cookie, der muliggør langtidssporing med dette genererede ID. Dette gøres ganske enkelt ved at tilføjer visitor: ‘persistent’ til Clerk.js.

Deaktivering af ‘besøgende’-ID’et #

Som standard kører Clerk.js i cookieless-tilstand, så hvis parameteren besøgende ikke er indstillet, logger vi sessionsaktiviteten uden at tilføje en cookie.

Hvis du vil give den besøgende mulighed for at vælge ikke at blive sporet på nogen måde, kan ID’et deaktiveres helt ved at tilføje ‘besøgende’: null:

Clerk.js

I opsætninger, der bruger Clerk.js, skal du tilføje det til Clerk.js-koden for den pågældende besøgende:

API

Hvis du bruger direkte API-kald, skal du inkludere det som et argument:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "yu0tX54BcDAIuBp8RkNoldtcir9Dwip8",
          "limit": 30,
          "labels": ["Bestsellers"]
          "visitor": null}' \
     http://api.clerk.io/v2/recommendations/popular

Hvis du har spørgsmål om besøgssporing, er du velkommen til at kontakte vores Customer Success-team via live-chatten i nederste højre hjørne.

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