Placements

What are placement tags
Refreshing placements
Pre-loading placements

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-id
Required
true
Description
ID of the placement, this is auto-generated and always assigned on placement creation
Attribuite
data-purchase_amount
Required
false
Description
The amount of money in micro units ($12.00 = 1200), 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
<!-- Placement v1 -->
<klarna-placement
    data-id="88888888-4444-4444-aaaa-bbbbbbbbbbbb"
    data-purchase_amount="122500"
    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
<!-- Placement v1 -->
<klarna-placement
    data-id="88888888-4444-4444-aaaa-bbbbbbbbbbbb"
    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
<!-- Placement v1 -->
<klarna-placement
    data-id="88888888-4444-4444-aaaa-bbbbbbbbbbbb"
    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
<!-- Placement v1 -->
<klarna-placement
    data-id="88888888-4444-4444-aaaa-bbbbbbbbbbbb"
    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 || []  // Making sure that data layer exists in case JavaScript Library is loaded later for any reason
window.KlarnaOnsiteService.push({ eventName: 'refresh-placements' }) // Push the event to the data layer

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
<!-- Placement v1 -->
<klarna-placement
    data-id="88888888-4444-4444-aaaa-bbbbbbbbbbbb"
    data-purchase_amount="122500"
></klarna-placement>
<!-- end Placement -->

The same placement set as pre-loaded

1
2
3
4
5
6
7
<!-- Placement v1 -->
<klarna-placement
    data-id="88888888-4444-4444-aaaa-bbbbbbbbbbbb"
    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
window.KlarnaOnsiteService = window.KlarnaOnsiteService || []
window.KlarnaOnsiteService.push({ eventName: 'placement-impression', placementId: '88888888-4444-4444-aaaa-bbbbbbbbbbbb' })

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