Enhver (webshop)

API

En fleksibel måde at integrere serverside.

Al kommunikation med Clerk sker 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 data for din Store. De findes i my.clerk.io > Developers > API Keys.

De består af en Public key, som giver adgang til endepunkter 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, såsom kunde- og ordreinformation.

Private Keys kan kun ses én gang efter oprettelsen af sikkerhedshensyn, og du kan oprette så mange du skal bruge 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 af API-nøgler.

CRUD API #

Du kan synkronisere dine data ved hjælp af CRUD API-endepunkterne, som gør det muligt at get, post, update og delete ressourcer on demand.

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 differentieringer er, at der ikke er nogen læringsperiode, da vi kan udnytte alle eksisterende ordrer fra dag ét til at forstå nuværende kundeadfærd.

Data Feeds #

Udover brugen af CRUD API anbefales det kraftigt at tilføje en backup-synkroniseringsmetode. Mange ting kan gå galt med API-kald.

For eksempel kan din prisserver gå ned, eller en produktattribut kan indeholde en fejl, der forårsager at flere kald fejler. 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 en eller flere JSON-filer, som indeholder webshoppens aktuelle katalog.

Alle data, der er tilgængelige i feedet når det indlæses, er dem Clerk arbejder med, undtagen ordrer, som logges og ikke skal inkluderes i feedet efter første import.

Brugen af data feed er også en god måde at præloade 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 konfigurerer i my.clerk.io backend’en under System status > Data Sync. Du kan sikre feedet, så kun vores importør kan få adgang.

2. Hent Data #

Når data er synkroniserede, analyserer AI’en dem og bygger intelligente indeks, der kan hentes gennem unikke endepunkter afhængigt af brugsscenariet.

F.eks. til at hente de hotteste produkter, kan du bruge recommendations/trending-endepunktet, og for at vise top-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 styre antallet af resultater der returneres.

Yderligere parametre afhænger af det endepunkt du kalder. F.eks. de bedste alternativer kræver products, som er en liste af produkt-ID’er til at finde accessories til, og ethvert søge-relateret kald skal bruge parametret query for at finde matches.

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

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

Herunder ses et eksempel på et kald til et Search-endepunkt 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-endepunkt 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 slået til for et request, inkluderer API-responser et debug array, der viser, i rækkefølge, hvordan forskellige features påvirkede resultaterne. Hvert element inkluderer et feature, en letforståelig message og struktureret metadata, som 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. Visualiser Resultater #

Clerks API returnerer altid ID’er på de matches det fandt, når det returnerer resultater.

For at visualisere dine data kan du lave API-kald server-side, hente ID’erne på de matchende produkter, og dernæst hente alle produkt-specifikke 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"]
        }'

Respons

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

Clerks API kan også konfigureres til at sende enhver ressource-specifik information, du sender til Clerk, såsom priser, brandnavne, kategori-URL’er, blog-coverbilleder og mere.

Med dette behøver du ofte ikke at lave individuelle kald til din PIM før du viser resultater, hvilket vil give 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"]
        }'

Respons

{
    "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 Clerks AI opdateret og personliggøre resultater for besøgende under deres session. Det kræver 4 trin:

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

Opret Visitor ID #

Session ID kaldes også Visitor ID. Det kræves for at logge en brugers aktivitet under en session på webshoppen, inklusive hvilke produkter de klikker på, deres søgninger, og hvilke 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 bare en streng, der bruges til at identificere sessionen. Det kan være en hvilken som helst alfanumerisk kombination, og vi anbefaler at holde den på maks. 8 tegn for bedst performance.

For eksempel kan du bruge PHP’s uniqid()-funktion til at generere ID’er, der er unikke i det mindste 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øgeresultater eller alternativer på produktsider. 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 der vises. Et eksempel kunne være Homepage - Trending. Så er de nemme at skelne mellem 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 log/click-endepunktet.

Det er vigtigt, at du kun laver dette kald, når det produkt der klikkes på vises af Clerk.io og ikke webshop-platformen selv. Ellers vil det se ud som om alle produkter bliver fundet via Clerk.

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

Search & Recommendations #

Klik logges ved at tilføje parametrene til kaldet baseret på hvilket endepunkt der blev brugt til at vise det klikkede produkt. Dette er ligetil, da det bruger data fra opsætningen 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 #

Kliklogning fungerer anderledes her, da du modtager data fra GET requests, som videresendes af Clerk.io. Du skal overvåge om URL’en indeholder parametre, der indikerer, at besøgende lander på en produktside gennem 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 den gør, log klikket med de data du modtager.

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

Her er et eksempel på 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, bør dette logges, så det kan bruges til at personliggøre resultater – særligt de besøgsrelaterede som Visitor Recommendations eller Visitor Alternatives.

Hvis du bruger nogle endpoints 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 bruger disse, skal du lave et separat kald til log/product med produktets ID.

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.ios AI afhænger i høj grad af ordrer for at forudsige resultater, så tracking i realtid er afgørende. log/sale-endepunktet bruges til dette.

Med visitor-ID’et inkluderet i kaldet forstår Clerk hvilke produkter der blev vist, klikket på og til sidst købt. Dette gør at AI’en hele tiden holdes opdateret og kan ændre resultaterne on-the-fly baseret på kundeadfærd.

Dette kald knytter også Visitor ID sammen med e-mailadresse eller kunde-ID på køberen, så personalisering kan forbedres yderligere via kundespecifikke anbefalinger.

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