Klarna Docs - FAQ

FAQ

What is the On-site messaging JavaScript library?

The JavaScript Library delivers the core functionality of the On-site messaging:

  • Communication with On-Site Messaging to deliver messaging for placements
  • Optimizing the user experience by leveraging a cache layer
  • Setting cookies in order to assure consistency in delivered messaging
  • Handle interstitial operations to allow user interaction without affecting the website

What does it look like

An example On-Site JavaScript library snippet looks like the code below:

MARKUP
<script
    src="https://eu-library.klarnaservices.com/lib.js"
    async
    data-client-id="11111111-2222-3333-4444-555555555555"
></script>
AttributeDescription
srcKlarna On-Site Messaging script url
asyncMakes loading script non-blocking
data-client-idOn-Site Messaging Client Identifier

How does the JavaScript Library work?

The flow of On-Site JavaScript Library will vary slightly depending on the functions it is called upon to perform. Below is a high level summary:

1. Set cookies

The JavaScript Library sets cookies to serve accurate and personalized content to specific website visitors. Cookies are set as follows:

CookieDescription
ku1-vidFirst party cookie containing visitor identifier
ku3-vidThird party cookie containing visitor identifier
ku1-sidFirst party cookie containing session id used for caching purposes

2. Visitor profile

The JavaScript Library will attempt to match the current visitor to a Klarna user profile. This will allow for messaging to be personalized for the visitor and improve the user experience.

3. Scan DOM tree for placements

The JavaScript library will look for placements tags in the DOM tree. An AdServer will match content to the placement tag ID and return the content that will render in the tag.

4. Listen for interstitials

Many ads will contain interstitial events that are initiated when a user clicks a call to action. The JavaScript Library will listen for those events and render the interstitial on click.

5. Data layer

The JavaScript library utilizes a data transfer layer to make working with placements flexible. The data layer is a very simplified queue of events that the library will react to.

What are placement tags?

Placement tags are the HTML tags decide where to display messaging to visitors on your website. Placements have some basic configurations to adjust them for your needs. Some attributes are required and others are optional:

AttributeRequiredDescription
data-keytrueIdentifier for the placement, uniquely identifies a placement type and size.
data-localetrueThe language and the billing country of the ad.
data-purchase-amounttrueThe amount of money in micro units ($120.00 = 12000), used for amount based credit promotions. Not required for some placements such as the info-page.
data-theme="default"falseSet a theme to override the default or customized content.

Example use of the attributes in placements:

MARKUP
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-small"
    data-locale="en-SE"
    data-purchase-amount="12000"
></klarna-placement>
<!-- end Placement -->

How does the purchase amount work?

Amount based placements include the data-purchase-amount attribute. This will deliver messaging with an offering for the specific price provided in micro units, where available. The placements can be used in various places across the website, such as cart view, product details page, product list page, etc. Example:

MARKUP
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-standard"
    data-locale="en-SE"
    data-purchase-amount="122500"
></klarna-placement>
<!-- end Placement -->

Here price would equal to $1,225.00 if merchant currency is dollars.

How can I populate the data-purchase amount?

  • If it is a static value, you can just use the value instead of empty string data-purchase-amount=“12350”. NB! It is in minor units, so 12350 is 123,50 EUR.
  • If it is a dynamic value that you need to add with JS, you can do something like document.querySelector(‘klarna-placement’).dataset.purchaseAmount = 9999. NB! If you have multiple placements in one page, you will need to use a more specific query selector. After updating the values, remember to “refresh-placements”.

Important note:We do not provide the currency in data-purchase-amount value, currency is based on the merchant configuration for the country and MID.

What sizes are available?

Placements labeled with (auto)x(auto) will adjust to 100% of the width and height of the container element. All placements are responsive.

What are themes?

Some placements and content support multiple different themes. What themes are available are shown in the preview in merchant portal. Set themes using the ‘data-theme’ attribute in the placement tag.

MARKUP
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-standard"
    data-locale="en-SE"
    data-purchase-amount="122500"
    data-theme="default"
></klarna-placement>
<!-- end Placement -->

What is refreshing placements?

There are use cases where we need to refresh the content of the placement on demand. The most popular ones are:

  • Load new content without page refresh (i.e. Ajax) and this new content contains a placement tag
  • Change the purchase amount for placements dynamically without page refresh
  • Infinity scroll on the page with dynamically loaded content on scroll

In those use cases the JavaScript Library needs to be informed that something has been changed in order to trigger messaging delivery for those placements or update the existing content to reflect changes. This is where refreshing placements comes into play.

In order to refresh placements we need to push an event into the data layer to inform the JavaScript Library the placements on the page have been altered. This should be triggered in the code after a change. Example:

JAVASCRIPT
window.KlarnaOnsiteService = window.KlarnaOnsiteService || []
window.KlarnaOnsiteService.push({ eventName: 'refresh-placements' })

Can I decide on the content of the messaging?

The content is dynamically populated by Klarna. We take into consideration several parameters such as the payment options you are offering your users in Klarna Payments (KP) or in the Klarna Checkout (KCOv3) - so in that sense you control the offer. Due to our dynamic algorithm we are able to choose the best performing content for your customers.

What does On-site messaging cost?

On-site messaging is an additional service provided with Klarna Payments (KP) and Klarna Checkout (KCOv3). There are no extra charges.

What do I need to do to be compliant with regulators?

Messaging credit is heavily regulated. Klarna keeps all messaging provided through the On-site messaging compliant and up to date with regulations in each market.

I am not satisfied with the loading time. Can I do something?

Definitely! Please take a look at our Best Practices.

Can I use On-site messaging via shopsystems or other partners?

Yes! Our partner directory can be found in the main menu under the “Partners” section. Just choose your country, select the partner you are looking for and there you will find information about the supported products like On-Site Messaging.

On-site messaging is not being loaded on my page. What can I do?

  • Check that your <klarna-placement> and script tags are valid html. Make sure you are only loading one instance of our javascript library.
  • On-Site Messaging is connected to your payment methods so make sure everything is enabled and that Klarna Payments or Klarna Checkout is loaded in your checkout page.
  • A typical issue can be that the purchase amount is not correct. Make sure you are sending the correct purchase amount (in micro units format)!
  • If all the above is working, check the network requests to klarnaservices.com. Look for errors and 204s, you can detect small mistakes easily.