Clerk.js

Oversigt #

Clerk.js er et JavaScript-bibliotek, der forenkler integrationen af vores API med frontend. Med kun 37,7 kb er det en super letvægtsløsning.

Der er tre fordele ved at bruge Clerk.js:

• Det er robust, da det bliver indlæst asynkront. Det betyder, at resten af siden ikke er afhængig af et API-svar før indlæsning.
• Det er ofte hurtigere, da din server kan begynde at gengive siden parallelt med, at Clerk.js foretager kald og gengiver resultater.
• Besøgs- og kliksporing håndteres automatisk for alle visninger, der vises af Clerk. Dette kræver ingen cookies, da vi genererer en hashed værdi ud fra besøgendes IP og useragent kombineret med et unikt butiks-salt, som roterer hver 30. dag.

Clerk.js indlæses med et initialiseringsscript, der tilføjes til headeren på hjemmesiden:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
  (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){ w.__clerk_q.push(arguments) };
  })(window,document);

  Clerk('config', {
    key: 'insert_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Det indlæser biblioteket fra vores CDN og lader dig tilgå dets funktioner gennem objektet Clerk og konfigurerer Clerk.js med API-nøglen, så det allerede ved, hvilken Store det laver API-kald for.

Snippets #

Når siden indlæses, scanner Clerk.js den for alle snippets med klassen “clerk”.

Derefter bruger den attributterne fra snippetten til at bygge et API-kald, mens API-nøglen hentes fra config i initialiseringsscriptet.

<span
  class="clerk"
  data-api="recommendations/popular"
  data-limit="10"
  data-template="@clerk-product-template">
</span>

Det visuelle håndteres af Designet, som også refereres af snippetten.

Clerk.js bruger Liquid designs til at gengive HTML med de data, API’et returnerer. Disse er formateret som scripts, der refereres ved deres ID i data-template i din snippet.

<span class="clerk"
     data-api="search/search"
     data-query="jedi"
     data-limit="20"
     data-template="#clerk-template">
</span>

<script type="text/x-template" id="clerk-template">
  <h1>Søgeresultat for {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Køb nu</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Indlæs flere resultater</a>
</script>

Snippets kan også forsimples til blot at inkludere en reference til et Element block ved brug af syntaksen data-template="@element-block-id":

<span class="clerk"
     data-template="@product-page-alternatives"
     data-products="[12352]">
</span>

Designs håndteres herefter med Design Editor eller med Liquid HTML code på en brugervenlig måde fra my.clerk.io.

Dine snippets skal kun indeholde klassen clerk, side-specifik information som produkt-ID’er og en reference til ID’et på et Element block i data-template.

Injection #

Injection er en funktion, der gør det muligt at indsætte indholdssnippets på dit website uden at skulle gøre det manuelt. I stedet vælger du blot en CSS Selector, som snippetten skal injiceres i, og Clerk.js indføjer den automatisk ved sidens indlæsning.

Læs mere om Injection her.

Konfiguration #

Clerk.js tillader en række konfigurationer, der ændrer, hvordan det fungerer.

Besøgs-ID’er #

Som standard genererer Clerk.js anonyme besøgs-ID’er, som bruges til at spore sessionerne.

Hvis kunder accepterer cookies, kan Clerk.js konfigureres til at placere en persistent cookie med besøgs-ID, hvilket gør det muligt at spore over en længere periode.

Hvis du foretrækker at håndtere session-ID’er manuelt, kan du konfigurere parameteren visitor, som Clerk bruger i API-kald. Alternativt kan du slå sessionssporing helt fra ved at sætte visitor til null.

// Persistent besøgs-ID
Clerk('config', {
  visitor: 'persistent'
});

// Custom besøgs-ID
Clerk('config', {
  visitor: 'ABC123'
});

// Deaktiver sporing af besøgende
Clerk('config', {
  visitor: null
});

Sidekontekst #

Konfigurerer Clerk.js med konteksten for den side, en besøgende aktuelt ser. Dette bruges til at berige sporingsdata til personaliseringsfunktioner som Email Triggers, Audience segmentering og Chat kontekst.

Clerk('context', {
  product: null,  // Angiv produkt-ID på produktsider, fx 12345 eller null
  category: null, // Angiv kategori-ID på kategorisider, fx 67 eller null
  page: null      // Angiv side-ID eller type på andre sider, fx 'homepage' eller null
});

Sprog #

Konfigurerer Clerk.js med websitets skriftsprog. Dette bruges af Clerk.io til at håndtere grammatiske regler korrekt i Search, og til at hente de rigtige oversættelser når du bruger multi-language feeds.

Clerk('config', {
  language: 'italian'
});

Accepterede værdier findes under Supported languages.

Erstat pladsholderværdierne med din platforms logik for at hente ID’erne dynamisk. Hver værdi skal sættes baseret på hvilken side-type, den besøgende er på:

• product: ID’et på produktet, der vises på produktsider. Sæt til null på ikke-produkt-sider.
• category: ID’et på kategorien, der vises på kategorisider. Sæt til null på ikke-kategori-sider.
• page: En sideidentifikator eller type string på andre sider som forside, kurv eller checkout. Sæt til null hvis ikke relevant.

Hvis din platform ikke har et specifikt ID tilgængeligt for en sidetype, så lad værdien være null. Sæt kun værdier for de sidetyper, der er relevante.

Designfunktioner #

Clerk.js understøtter tilføjelse af Formatters og Globals, som kan bruges til at skabe brugerdefineret javascript-funktionalitet til dine design scopes.

Formatters #

Disse bruges til at påvirke eller ændre attributter. Fx kan du kun ønske at vise de første 40 tegn af en beskrivelse, eller måske skal du udregne en specifik rabatprocent baseret på typen af kunde, der er logget ind.

Globals #

Disse er tiltænkt frontend-data, du vil tilgå i designs. Det kan være eksempler som det resterende beløb for at opnå fri fragt, navnet på en logget ind kunde, et valutasymbol eller en valutakurs.

Herunder er et eksempel på opsætning af formatters og globals.

Config #

Clerk('config', {
  formatters: {
    uppercase: function(string) {
        return string.toUpperCase();
    }
  },
  globals: {
    currency_symbol: '$'
  }
});

Design #

<div class="name">{{ product.name | uppercase }}</div>
<div class="price">{{ currency_symbol }}{{ product.price }}</div>

Output #

<div class="name">GREEN LIGHT SABER</div>
<div class="price">$1999.99</div>

Email Tracking #

Clerk.js kan automatisk indsamle e-mails i kundens session til brug for personalisering af email-anbefalinger, selvom de endnu ikke har lagt en ordre.

Aktiver collect_email i din Clerk.js konfiguration:

<script type="text/javascript">
  Clerk('config', {
    key: 'insert_api_key',
    collect_email: true
  });
</script>

Når dette aktiveres, overvåger Clerk.js email-inputs og sender automatisk log/email, når besøgende indtaster en emailadresse.

Hvis du ønsker at logge en e-mail manuelt, kan du også tilføje et snippet som dette:

<span class="clerk" data-api="log/email" data-email="EMAIL@EXAMPLE.COM"></span>

Hvordan forbindelsen fungerer #

Når en email logges, sender Clerk både besøgs-ID og emailadresse til API’et, så de kan forbindes.

Dette lader Clerk identificere, hvad den besøgende har gjort i sin historik (fx sete produkter, klik og søgninger) og associere den adfærd med emailadressen.

Med denne forbindelse kan den samme adfærdsdata bruges til emailbrug (fx triggerede og personaliserede emails) og til onsite personalisering i anbefalinger til loggede brugere.

Custom Rendering #

Dette bruges primært med Single Page Apps (SPA), Progressive Web Apps (PWA) og andre applikationer, der ikke anvender traditionelle sideindlæsninger.

Clerk.js gengiver alle elementer med klassen clerk, men andre klasser kan bruges til at tilpasse rendering som custom selectors.

Som standard kræves det, at du kører Clerk("content", "SELECTOR") for at vise indhold hver gang det skal vises.

Hvis du tilføjer auto_init_custom_selectors: true til konfigurationen, vil Clerk.js automatisk initialisere custom selector-elementer, efterhånden som DOM’en ændres, så længe de allerede har været gengivet med Clerk("content", "SELECTOR") mindst én gang.

Denne adfærd fortsætter, indtil der sker en fuld sideopdatering.

Fejlfinding #

Clerk.js har en indbygget debug-mode, der logger diagnostisk information til browserens konsol. Den gemmer sin konfiguration i sessionStorage under nøglen __clerk_debug, så debug-mode forbliver aktiv på tværs af side-navigationer indenfor samme browser-session.

Som standard er debug-mode aktiveret med level sat til warn og collect sat til true.

Aktiveringsmetoder #

Der er tre måder at aktivere debug-mode.

Console shorthand

Den nemmeste måde er at kalde Clerk('debug') fra browserkonsollen. Den accepterer flere argumentformater:

Clerk('debug');              // Aktiver med standardindstillinger
Clerk('debug', true);        // Aktiver
Clerk('debug', false);       // Deaktiver
Clerk('debug', 'on');        // Aktiver
Clerk('debug', 'off');       // Deaktiver
Clerk('debug', 'warn');      // Sæt logniveau direkte
Clerk('debug', {             // Send et komplet konfigurationsobjekt
  enable: true,
  level: 'log',
  group: true
});

Config path

Debug-mode kan også konfigureres gennem det normale config-kald:

Clerk('config', 'debug', {
  enable: true,
  level: 'log',
  collect: true,
  group: true,
  collapsed: false
});

URL-hash

Debug-mode kan aktiveres ved at tilføje et hash-fragment til URL’en. Dette er nyttigt til at dele debug-links med kollegaer:

https://yourwebsite.com/#clerkjs:debug.enable=true&debug.level=warn

Når det aktiveres via URL-hash, gemmes konfigurationen også i sessionStorage under nøglen __clerk_tmp_config.

Config Valgmuligheder #

Session Storage #

Når debug-mode er aktiveret, gemmes konfigurationen i sessionStorage under nøglen __clerk_debug. Dette sikrer, at debug-indstillinger bevares, mens besøgende navigerer mellem sider, uden at det påvirker andre browsere eller varer længere end sessionen.

Consent Management Platforms (CMPs) som Cookiebot kan markere __clerk_debug som et storage-item, der kræver dokumentation. Det er en funktionel nøgle, der kun bruges til udvikler-debugging. Den indeholder ikke persondata eller sporingsinformation.

For detaljer om strukturen i API-debug-responser, se Response debugging.

UI Kit #

Clerk.js indeholder et sæt UI-værktøjer til vigtige elementer, der kan bruges til at forbedre brugeroplevelsen. Disse sparer ofte udviklingstid for specialopsætninger.

Instant Search #

En central del af en god e-handels søgeoplevelse er at få resultater med det samme, man begynder at skrive. Vores Instant Search UI-komponent gør denne brugeroplevelse hurtig og nem at bygge.

Ethvert Clerk.io indhold kan i princippet laves om til en Instant Search-komponent, men det fungerer bedst som en dropdown, der viser søgeresultater.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Instant Search"]'
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE">
  
  <dl class="product-search-result-list">
    <dt>Produkter matcher <i>{{ query }}</i></dt>
    
    {% for product in products %}
      <dd class="product clerk-instant-search-key-selectable">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Køb nu</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Læs mere om Instant Search UI-værktøjet her.

Search Page #

En nøgle til en god e-handels søgeoplevelse er at få gode søgeresultater. Vores Search Page gør denne oplevelse hurtig og nem at bygge.

Search Page lader dig oprette en hel side, der viser de bedst mulige matches for en given forespørgsel.

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Search Page"]'
  data-query="INSERT_QUERY_HERE"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">>
  
  <div class="product-search-result-list">
    <div>Produkter matcher <i>{{ query }}</i></div>
    
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Køb nu</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Vis flere resultater
    		</div>
    {% endif %}
  </div>
</span>

Læs mere om Search Page UI-værktøjet her.

Category Page #

En veldisponeret categorieside er nøglen til en succesfuld e-handelsforretning. Vores Category Page gør denne oplevelse hurtig og nem at bygge. Den lader dig oprette en komplet side, der viser de bedste resultater for enhver kategori.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Category Page Grid"]'
  data-category="INSERT_CATEGORY_ID"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">
  
  <div class="product-category-result-list">
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Køb nu</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Vis flere resultater
    		</div>
    {% endif %}
  </div>
</span>

Læs mere om Category Page UI-værktøjet her.

Facetter #

Clerk.js har indbygget understøttelse af dynamisk facetteret navigation til både søgning og kategorier. Alle produktegenskaber, du sender til os, kan bruges som facetter.

Her er et eksempel på grundlæggende brug:

<div id="clerk-search-filters"></div>

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "PRICE-TRANSLATION", "categories": "CATEGORIES-TRANSLATION", "brand": "BRAND-TRANSLATION"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="View More"
  data-facets-searchbox-text="Search for "
  data-facets-design="133995">
</span>

Læs mere om Facets UI-værktøjet her.

Exit Intent #

Exit intent-popuppen reagerer, når en besøgende forsøger at forlade dit website ved at bevæge musen tæt på toppen af browser-vinduet. Den popper op og viser interessante produkter, hvilket muligvis kan konvertere en besøgende på vej væk til en betalende kunde.

Alle Element blocks kan aktiveres ved besøgendes exit-intent ved at tilføje attributten data-exit-intent="true" til snippetten.

<span
  class="clerk"
  
  data-api="recommendations/visitor/complementary"
  data-limit="20"
  data-labels='["Exit Intent / Popup"]'
  
  data-exit-intent="true">
</span>

Læs mere om Exit Intent UI-værktøjet her.

Popup #

UI Kit indeholder et simpelt popup-bibliotek til hurtigt at lave enkle, brugervenlige popups med hvilket som helst indhold. Alle HTML-elementer på dit website med klassen clerk-popup vil blive vist som en popup.

<div id="my-popup" class="clerk-popup">Hello, world!</div>

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // vis popup
  my_popup.show(); 
  /* eller */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // skjul popup
  my_popup.hide(); 
  /* eller */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Læs mere om Popup UI-værktøjet her.

Udelukkelse af produkter #

Clerk.js har to forskellige måder at udelukke produkter på, afhængig af om du vil udelukke bestemte ID’er eller undgå at vise dubletter mellem forskellige sliders.

Udelukkelse af bestemte ID’er #

Tilføj ganske enkelt attributten data-exclude til snippetten. Indholdet af data-exclude skal være en liste over de produkt-ID’er, du ikke ønsker vist – fx produkterne i kundens kurv eller en liste over produkter, de ikke må se.

<span class="clerk"
  data-template="@clerk-complementary"
  data-exclude="[45654, 3244, 12352]">
</span>

Undgå dubletter #

Dette gøres ved at tilføje attributten data-exclude-from på Clerk Block, hvor du vil fjerne dubletten. Værdien af attributten skal være en CSS-selector for de andre snippets, du vil undgå dubletter fra.

I eksemplet nedenfor udelukker .clerk-2 ethvert produkt, der er i .clerk-1, og .clerk-3 udelukker produkter, der er i enten .clerk-1 eller .clerk-2.

<span class="clerk clerk-1"
  data-template="@clerk-banner-1">
</span>
 
<span class="clerk clerk-2"
  data-exclude-from=".clerk-1"
  data-template="@clerk-banner-2">
</span>
 
<span class="clerk clerk-3"
  data-exclude-from=".clerk-1,.clerk-2"
  data-template="@clerk-banner-3">
</span>

Events #

Når du bygger mere tilpassede opsætninger, skal du ofte kunne reagere på eller ændre resultater fra Clerk, før de bliver vist. Det er her, Events er nyttige.

Med Events kan du opsætte event-lyttere, der kører kode på bestemte tidspunkter, før, under eller efter Clerk.js gengiver sine resultater.

Et almindeligt eksempel er at hente kundespecifikke priser i et B2B-setup. Et event kan køre, straks efter Clerks API er færdig, så du kan hente de specialpriser til kunden og indsætte dem i produktelementerne:

var customer_id = INSERT_CUSTOMER_ID;
Clerk("on", "rendered", function(content, data){
  for (i = 0; i < data.product_data.length; i++) {
      var product = data.product_data[i];
        var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
        let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
        price_container.innerText = custom_price;
    }
})

Læs mere om Events her.

SEO og performance #

Clerk.js driver personaliserede shoppingoplevelser uden at gøre dit website langsommere eller skade SEO. Ved at bruge client-side rendering og optimeret indlæsning balanceres hastighed, ydelse og søgebarhed.

SEO og hastighed #

Det er en misforståelse, at JavaScript-funktioner som Clerk.js skader ydelsen eller SEO. Automatiske værktøjer overser ofte optimeringer som caching, parallelt indlæsning og server-side håndtering.

Fordele ved Clerk.js integration #

• Clerk.js-skriptet (≈ 37 - 38 KB) indlæses asynkront, så dit website kan vises, mens Clerk initialiseres.
• Clerk-elementer renderes på klientsiden, så dit basis-HTML forbliver cachebart, og de dynamiske komponenter indsprøjtes først efter load.
• Dette muliggør effektiv server-side caching og ikke-blokerende indlæsning af Clerk.js-assets.

Indvirkning på performance #

• Clerk.js er letvægts og asynkront, hvilket typisk giver meget lille impact på sidens indlæsningstid.
• Eventuelle performance-udfordringer skyldes typisk eksterne billeder, der vises i anbefalingerne – ikke selve scriptet. For at minimere påvirkning:
  • Brug billeder i passende størrelse og i effektive formater som WebP.
  • Skaler billeder til visningsdimensionerne (fx 400×400 px → 420×420 px maks).
• For at undgå layout-skift (CLS), reserver plads til indsprøjtet Clerk-indhold.

F.eks.:

.clerk-slider-wrapper {
  min-height: 300px; /* juster efter behov */
  width: 100%;
}

SEO-overvejelser #

Forståelse af, hvordan Clerk.js interagerer med søgemaskiner, hjælper med at sikre, at din implementering understøtter både brugeroplevelse og søgebarhed.

Linking og crawlability #

• Clerk.js indsætter anbefalingslinks dynamisk på klientsiden.
• Disse links kan forbedre intern linking ved at forbinde relaterede sider, hvis søgemaskinerne gengiver og følger dem korrekt.
• Da de indsprøjtes via JavaScript, bør du verificere, hvordan søgemaskinernes crawlere opfatter og fortolker dem.
• Korrekt crawlede links kan forbedre crawlability og lade søgemaskiner opdage og indeksere flere sider.

PageRank distribution #

• Når søgemaskiner kan crawle dem, kan Clerk.js-links hjælpe med at fordele linkværdi (PageRank) til vigtige sider.
• Det understøtter bedre synlighed og ranking af produkt- og kategorisider.

Observerede fordele #

• En korrekt Clerk.js-integration kan korrelere med stærkere interne linkstrukturer, hvilket kan understøtte bedre synlighed i søgeresultater.
• Clerk.io dashboards giver analyser på ordrepåvirkning, konverteringsløft og omsætningsbidrag fra Search, Recommendations, Email og Audience funktioner.

Anbefalede best practices #

1. Optimer billeder (WebP-format, korrekt opløsning).
2. Reserver layout-plads til dynamiske elementer for at undgå layoutskift.
3. Overvåg rigtige metrikker i stedet for kun at stole på automatiske scores. Brug Clerks dashboards til at evaluere effekten på tværs af kanaler.