Placements

What are placement tags
Refreshing placements
Pre-loading placements

For previous integration versions, see the older documentation .

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:

AttribuiteRequiredDescription
Attribuite
data-key
Required
true
Description
Identifier for the placement, uniquely identifies a placement type and size.
Attribuite
data-locale
Required
false
Description
Locale of the ad. If not defined, uses default locale for country.
Attribuite
data-purchase-amount
Required
false
Description
The amount of money in micro units ($120.00 = 12000), used for amount based credit promotions.
Attribuite
data-inline="true"
Required
false
Description
The attribute will render placements inline in cases where content has been configured for this.
Attribuite
data-preloaded="true"
Required
false
Description
Set when a placement is preloaded. Read more about in Pre-loading placements .
Attribuite
data-theme="default"
Required
false
Description
Set a theme to override the default or customized content.

Example use of the attributes in placements:

1
2
3
4
5
6
7
8
9
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-small"
    data-locale="en-SE"
    data-purchase-amount="12000"
    data-inline="true"
    data-preloaded="true"
></klarna-placement>
<!-- end Placement -->

Amount based placements

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:

1
2
3
4
5
6
7
<!-- 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.

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.

Adaptive width placements

This type of placement will adjust to 100% of the width of the container element.

They are labeled with (auto) instead of a pixel width.

For best results, add this type of placement inside elements that span the whole width of the page and with high visibility for the user: page header, after navigation bar, etc.

Adaptive height placements

This type of placement will adjust depending on the length of the content.

They are labeled with (auto) instead of a pixel height.

This is to minimize the placement size. One-line content generally renders a default height of 40px. Two lines of content generally render 55px. Some credit promotions require additional legal disclosures and these will tend to have two or in some cases three lines of content.

All responsive placements have an adaptive height. This is to allow the content to display correctly when the placement is constrained by a parent element or through CSS.

For this type of placement it’s recommended to avoid adding a fixed height or overflow: hidden to their container element.

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.

1
2
3
4
5
6
7
8
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-standard"
    data-locale="en-SE"
    data-purchase-amount="122500"
    data-theme="default"
></klarna-placement>
<!-- end Placement -->

Inline placements

Another special type of placements are inline placements. These are placements with the attribute data-inline=“true”. This means that the placement will be rendering the content directly. No iframe will be rendered for that placement. The content will inherit all the styles from your website. Those placements should be used for in-text messaging. Example:

1
2
3
4
5
6
7
8
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-standard"
    data-locale="en-SE"
    data-purchase-amount="122500"
    data-inline="true"
></klarna-placement>
<!-- end Placement -->

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.

Refreshing placements

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:

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

You can read more about the data layer in JavaScript Library section.

Pre-loading placements

There are use cases when we would like to have content pre-loaded in the placement before we actually want to register the impression. An example of this use case may be loading the ad in a pop-up that is being triggered on a user action. If that is the case we want to have placement pre-loaded to deliver a fast experience, but we want to register the impression only if the content is actually displayed to the vistor.

In order to achieve this we need to make sure we do two things:

  • Configure the placement properly
  • Make sure to fire the impression once a visitor sees the messaging

Placement configuration

In order to configure placement as pre-loaded we have to add an attribute to the HTML tag called data-preloaded="true". Example:

Normal placement

1
2
3
4
5
6
7
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-standard"
    data-locale="en-SE"
    data-purchase-amount="122500"
></klarna-placement>
<!-- end Placement -->

The same placement set as pre-loaded

1
2
3
4
5
6
7
8
<!-- Placement v2 -->
<klarna-placement
    data-key="credit-promotion-standard"
    data-locale="en-SE"
    data-purchase-amount="122500"
    data-preloaded="true"
></klarna-placement>
<!-- end Placement -->

Fire impression

Once we will have placement configured correctly we have to fire the impression in the code. Example:

1
2
3
4
5
window.KlarnaOnsiteService = window.KlarnaOnsiteService || []
window.KlarnaOnsiteService.push({
  eventName: 'placement-impression',
  placementKey: 'credit-promotion-standard'
})

You can read more about the data layer in JavaScript Library section.