Klarna Docs - FAQ

FAQ

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

  • Communication with On-Site Messaging to deliver messaging for placements
  • Optimising 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

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

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:

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
ku1-sidFirst party cookie containing session id used for caching purposes

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.

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.

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.

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 -->

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.

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

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 -->

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' })

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.

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

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.

Definitely! Please take a look at our Best Practices.

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.

  • 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.

OSM is rendered inside Shadow Dom to improve loading times. Using Fastclick library makes the elements unclickable inside Shadow Dom and has been documented as a known issue:  https://github.com/ftlabs/fastclick/issues/604 

Fixes that can be implemented are:

  • Removing the fastclick library (optimal solution)
  • Adding class "needsclick" to all shadowhost div. The problem here is that shadowhost divs of the OSM are appended dynamically by OSM script while processing the placements. So merchant would need to observe the change and add "needsclick" class only after shadowhost div is appended. Elements where "needsclick" class should be added can be queried like this: 
JAVASCRIPT
const elements = document.querySelectorAll('klarna-placement div')

Example of OSM code on your website

We simplified our integration so you can install On-site messaging across different markets faster, manage your placements easier and benefit from upcoming feature improvements.

You can find the migration guide in our Merchant Portal under On-site messaging -> Updates -> Update On-site messaging.

If you are using one of our platforms, you will find further information under the following links:

BigCommerce

WooCommerce

Shopify

Deprecation Timeline:

February 28, 2022 – We will no longer provide feature updates and the old integration is in deprecation mode. We will only fix potential bugs.

May 30, 2022 – We will stop displaying on-site messaging on your website.

Chrome, Firefox and Edge have 4-6 week release cycles and most users receive automatically the latest update. Safari has a new major version per year. We aim to provide support for at least for the last 3 major versions of these popular browsers covering at least 99.5% of the market share.

On-site messaging is getting rendered in a variety of environments (websites, webviews of mobile apps, inside email clients etc) and in a variety of contexts that Klarna does not have control. We have tried to offer a11y support but due to this diversity of environments, lack of control of surrounding html elements and changes introduces by Apple on the way it treats iframes that makes extremely difficult to support a11y on Safari, we took the deliberate decision to hide the OSM ads from users that use assistive technologies, while working to find a better more inclusive solution. Since the OSM placements are not essential for the functionality of the website and are considered a decorative content this should not affect the ADA compliance of any website.

More information can be found here:

We are rendering interstitials in an iframe. Apple introduced in Safari 13 a change affecting the accessibility of this functionality, preventing us from transferring focus to the opened interstitial. From the release notes:

Changed the behavior for third party iframes to prevent them automatically navigating the page.

Users on assistive technologies will not be able to see our ads and navigate to the related interstitial window. We believe that every user should be treated the same and we are exploring alternative approaches to solve the problem.