Clerk.js

Oversigt #

Clerk.js er et JavaScript-bibliotek, der forenkler integrationen af vores API med frontend. Med kun 37,7kb 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 den indlæses.
• Det er ofte hurtigere, da din server kan starte med at gengive siden parallelt med, at Clerk.js foretager kald og viser resultater.
• Besøgs- og klikksporing håndteres automatisk for alle resultater vist af Clerk. Dette kræver ingen cookies, da vi genererer en hashværdi af besøgendes IP og useragent, kombineret med et unikt butikssalt, der roterer hver 30. dag.

Clerk.js indlæses med et initialiseringsscript tilføjet til websitets header:

<!-- 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 funktionaliteter gennem Clerk-objektet, og konfigurerer Clerk.js med API-nøglen, så det allerede ved, hvilken Store det skal lave API-kald for.

Snippets #

Når siden er indlæst, scanner Clerk.js den for snippeter med klassen “clerk”.

Herefter bruger den attributterne fra snippetet til at bygge et API-kald, mens den henter API-nøglen fra konfigurationen i initialiseringsscriptet.

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

Udseendet håndteres af Designet, som også refereres af snippetet.

Clerk.js bruger Liquid-designs til at gengive HTML med dataene, der returneres af API’et. Disse er formateret som scripts, refereret ved deres ID i data-template i dit 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>Search result for {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Buy Now</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Load More Results</a>
</script>

Snippeter kan også forsimples til blot at inkludere en reference til en Element-blok ved at bruge syntaxen data-template="@element-block-id":

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

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

Dine snippets skal kun indeholde klassen clerk, eventuel sidespecifik information såsom produkt-ID’er, og en reference til ID’et på et Element-blok i data-template.

Injection #

Injection er en funktion, der gør det muligt at indsætte indholdssnippets på din hjemmeside uden at skulle tilføje det manuelt. I stedet vælger du blot en CSS-selector til at indsætte snippetet, og Clerk.js vil automatisk tilføje det ved sidelæsning.

Læs mere om Injection her.

Konfiguration #

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

Visitor IDs #

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

Hvis kunder accepterer cookies, kan Clerk.js konfigureres til at placere en vedvarende cookie med besøgs-ID’et, hvilket tillader sporing over længere tid.

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

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

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

// Deaktivering af besøgs-sporing
Clerk('config', {
  visitor: null
});

Sprog #

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

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

Accepterede værdier findes under Supported languages.

Designfunktioner #

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

Formatters #

Disse bruges til at påvirke eller ændre attributter. For eksempel kan du kun ønske at vise de første 40 tegn af en beskrivelse, eller du kan have brug for at beregne en specifik rabatprocent baseret på typen af kunde, der er logget ind.

Globals #

Disse er beregnet til at blive brugt med frontend-data, som du ønsker adgang til i designs. Dette kan f.eks. være det resterende beløb, der skal bruges for at opnå fri fragt, navnet på en indlogget kunde, et valutasymbol eller en konverteringsrate.

Nedenfor er et eksempel på konfigurering 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 emails i kundens session for at personalisere email-anbefalinger, selvom de ikke har foretaget en ordre endnu.

Dette gøres ved at konfigurere Clerk.js med collect_email: true som vist her:

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

Med dette vil Clerk.js overvåge alle inputfelter på websitet og logger det med log/email, når en besøgende indtaster en emailadresse i et af dem:

https://api.clerk.io/v2/log/email?payload={"email":"test@test.com","key":"insert_api_key","visitor":"auto"}

Brugerdefineret Rendering #

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

Clerk.js renderer alle elementer med klassen clerk, men andre klasser kan anvendes for at tilpasse rendering som brugerdefinerede selectors.

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

Tilføjer du auto_init_custom_selectors: true til konfigurationen, gør Clerk.js automatisk initialisering af alle brugerdefinerede selector-elementer, efterhånden som DOM’en ændres, så længe de allerede er blevet gengivet med Clerk("content", "SELECTOR") én gang.

Denne adfærd forbliver aktiv, indtil der foretages en fuld sideopdatering.

Debugging #

Clerk.js har indbygget debug-tilstand, der logger diagnostisk information til konsollen og fastholder dette for sessionen på tværs af sidelæsninger.

Aktiver det fra konsollen:

Clerk("debug");

Eller aktiver det via URL-parametre:

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

For detaljer om strukturen af API-debug-svar, se Response debugging.

Debuggeren har 4 parametre:

UI Kit #

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

Instant Search #

En vigtig del af en god e-commerce-Search-oplevelse er at få resultater med det samme, du begynder at skrive. Vores Instant Search UI-komponent gør denne brugeroplevelse hurtig og nem at bygge.

Alt Clerk.io-indhold kan teoretisk omdannes 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>Products matching <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 }}">Buy Now</a>
      </dd>
    {% endfor %}
  </dl>
</span>

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

Search Page #

En vigtig del af en god e-commerce-Search-oplevelse er at få gode søgeresultater. Vores Search Page gør denne brugeroplevelse hurtig og nem at bygge.

Search Page lader dig oprette en fuld side, der viser de bedst mulige matches for enhver 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>Products matching <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 }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

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

Category Page #

En velstruktureret kategoriside er nøglen til en succesfuld e-handelsforretning. Vores Category Page gør denne brugeroplevelse hurtig og nem at bygge. Dette lader dig oprette en fuld side, der viser de bedst mulige 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 }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

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

Facets #

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

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-popup reagerer, når en besøgende forsøger at forlade dit site ved at føre musen tæt på toppen af browseren. Den popper op og viser interessante produkter, hvilket muligvis kan konvertere en forladende besøgende til en købende kunde.

Ethvert Element-blok kan blive udløst, når en besøgende viser exit-intent, ved at tilføje attributten data-exit-intent="true" til snippetet.

<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, der gør det nemt at oprette simple, men brugervenlige popups med ethvert indhold. Ethvert HTML-element på din hjemmeside 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.

Ekskludering af produkter #

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

Ekskludere specifikke ID’er #

Tilføj blot attributten data-exclude til snippetet. Indholdet af data-exclude skal være en liste over de produkt-ID’er, du ikke ønsker vist, f.eks. produkterne i kundens indkøbskurv eller en liste over varer, 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 fra. Værdien af attributten bør være en CSS-selector for et andet/andre snippets, du vil forhindre dubletter fra.

I eksemplet nedenfor ekskluderer .clerk-2 ethvert produkt, der er i .clerk-1, og .clerk-3 ekskluderer alle 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, har du ofte behov for at reagere på eller ændre resultater fra Clerk, før de vises. Det er her Events er nyttige.

Events tillader dig at opsætte event-lyttere, der kører kode på bestemte tidspunkter før, under eller efter at Clerk.js renderer sine resultater.

Et almindeligt eksempel er at hente brugerdefinerede priser for en indlogget kunde i en B2B-opsætning. Et event kan køres lige efter Clerks API har færdiggjort renderingen, så du kan hente brugerdefinerede priser til en kunde og tilføje dem til 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 leverer personaliserede shopping-oplevelser uden at gøre dit site langsommere eller skade SEO. Ved at bruge client-side rendering og optimeret indlæsning balancerer det hastighed, ydeevne og synlighed i søgning.

SEO og Hastighed #

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

Clerk.js Integration Fordele #

• Clerk.js-scriptet (≈ 37 - 38 KB) indlæses asynkront, så dit website kan gengives, mens Clerk initialiserer.
• Clerk-elementer er client-rendered, hvilket betyder at din basale HTML forbliver cachebar, og dynamiske komponenter først injiceres efter indlæsning.
• Dette muliggør effektiv server-side caching og ikke-blokerende indlæsning af Clerk.js-aktiver.

Performancepåvirkning #

• Clerk.js’ lette og asynkrone natur betyder typisk minimal påvirkning af sidens indlæsningstider.
• Den reelle påvirkning kommer ofte af ekstra billeder, der vises i anbefalingerne, ikke af selve scriptet. For at minimere påvirkningen:
  • Brug passende billedstørrelser og effektive formater som WebP.
  • Resize billeder, så de matcher visningsstørrelsen (f.eks. 400×400 px → 420×420 px max).
• For at undgå layoutskift (CLS), reserver pladsen til injiceret Clerk-indhold.

F.eks.:

.clerk-slider-wrapper {
  min-height: 300px; /* justér som nødvendigt */
  width: 100%;
}

SEO-overvejelser #

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

Intern Linking og Crawlability #

• Clerk.js injicerer 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 er JavaScript-injicerede, skal du verificere, hvordan søgemaskiners crawlere gengiver og fortolker dem.
• Korrekt crawlbare links kan forbedre crawlability og give søgemaskiner mulighed for at opdage og indeksere flere sider.

PageRank Distribution #

• Når søgemaskiner kan crawle dem, kan Clerk.js-links hjælpe med at distribuere linkværdi (PageRank) til nøglesider.
• Dette understøtter bedre synlighed og rangering af produkt- og kategorisider.

Observerede fordele #

• Korrekt Clerk.js-integration kan korrelere med stærkere interne linkstrukturer, hvilket kan understøtte bedre synlighed i søgeresultaterne.
• Clerk.io dashboards tilbyder analytics på ordreindflydelse, konverteringsløft og omsætningsbidrag fra Search, Recommendations, Email og Audience-funktioner.

Anbefalede bedste praksisser #

1. Optimer billeder (WebP-format, korrekt opløsning).
2. Reserver layoutplads til dynamiske elementer for at undgå layoutskift.
3. Overvåg virkelige måledata i stedet for kun at stole på automatiserede scores. Brug Clerks dashboards til at evaluere påvirkning på tværs af kanaler.