Klarna On-Site Messaging app on Shopify

 

Support Guide


Prerequisite        3

Install steps for Klarna On-Site Messaging on Shopify        3

Install the Klarna On-Site Messaging Shopify app        3

Connect your account        3

Add placements (for product & cart pages)        4

FAQs        6

What is Klarna On-Site Messaging?        6

How should I use Klarna On-Site Messaging?        6

How do I get Klarna Payments on my store?        6

How can I accept the required Legal Terms (for EU merchants)?        7

How can I see a product preview page instead of the store password page?        7

Can I use this app for a store using Klarna Payments within Shopify Payments?        7

Which placement should I pick?        7

Why don’t I see a pink box to drag and drop?        9

What does the “Risky Ad Position” error message mean?        9

How to resolve the “Failed to install global code snippet” error?        9

How do I add a placement to other pages, such as Home Page?        10

Where can I find the placement data on my store front end page?        10

Why isn’t the placement displayed on my product pages?        10

Why isn’t the placement displayed on my cart pages?        11

How can I get the placement in a specific location on a page?        11

Why isn’t the placement updating when I change the variant?        12

Why don’t I see On-Site Messaging after changing my theme?        12

Does the app support multi-currency?        12

Manual OSM integration (not using the SKOSM app)        13

Add the Klarna On-Site Messaging JavaScript library to the Shopify store        13

Add placement to the theme        13

Refresh placements when variants change        14

Removing the Klarna On-Site Messaging app        14

Helpful Links        15

Privacy Policy        15

Legal Compliance        15

Support        15


Prerequisite

Klarna has 2 apps available for Shopify merchants:

  1. Klarna On-Site Messaging (free, public app)
  2. Klarna Payments (free, private app, as required by Shopify)

Prerequisite: Prior to using the Klarna On-Site Messaging app, merchants should integrate the Klarna Payments app via the Klarna Payments install wizard.

If you don't yet have Klarna API credentials for Klarna Payments, you can sign up at US Signup or EU Signup.  Once you have received your Klarna API credentials, instructions to activate Klarna Payments in your Shopify store are available at the Klarna Payments on Shopify - Merchant Guide.

Install steps for Klarna On-Site Messaging on Shopify

  1. Install the Klarna On-Site Messaging Shopify app

The Klarna On-Site Messaging app is available on the Shopify App Store.

  1. Connect your account

When you first install the app, your Klarna API credentials will be automatically connected, as long as you have already completed the Klarna Payments for Shopify integration.    If you haven't yet integrated Klarna Payments for Shopify, see instructions, see Klarna Payments on Shopify - Merchant Guide to install.  If you do not yet have Klarna API credentials, you can sign up at klarna.com

You can confirm your Klarna API Credentials in the Settings menu option of the app.

  1. Add placements (for product & cart pages)

From the Dashboard, click the “New Ad Position” button

3a. Enter a name for your Shopify Ad Position

3b. If your country is not already defaulted, select the country that matches your Klarna API credentials.

3c. Select the appropriate placement; the Product Detail is recommended for Product and Cart pages.

Do not add padding or change the alignment, unless necessary.  Before adjusting these settings, check how the Shopify Ad displays on your store by viewing your store front end in a browser.  The Preview shows how the Ad may display but can not render the page exactly as shown in a regular browser session.

3d. Drag and drop the pink box to the desired placement on your page.  

3e. Check the box “I have checked the preview and moved the placeholder to the correct position.” and click the Save button.

3f. Review the placement display in your store front end.

3g. Repeat for your cart page.

Problems?  Email skosm@klarna.com for further help.

FAQs

What is Klarna On-Site Messaging?

For more info, see: https://developers.klarna.com/resources/on-site-messaging

How should I use Klarna On-Site Messaging?

Recommended guidelines: https://developers.klarna.com/resources/get-smoooth-handbook

How do I get Klarna Payments on my store?

See: Klarna Payments on Shopify - Merchant Guide

How can I accept the required Legal Terms (for EU merchants)?

If you get an error about Terms of Service, please log onto the Klarna Merchant portal to accept the Legal Terms.

US Merchant Portal

EU Merchant Portal

How can I see a product preview page instead of the store password page?

For preview page to fully display, the store must not be password protected.

Can I use this app for a store using Klarna Payments within Shopify Payments?

Currently Klarna Payments merchants integrated using Shopify Payments do not have access to the Klarna Merchant Portal and Klarna API credentials, which are currently required for Klarna On-Site Messaging, but this is on our roadmap to support in the near future.   This app supports stores with Klarna Payments integrated as an Alternative Payment Provider (under Shopify admin -> Settings -> Payment providers -> Alternative payments).

Which placement should I pick?

The “Product Detail - Price Detail” placement, as selected in the screen shot below, is recommended for both product and cart pages.  

This price detail type placement is dynamic, and showing dynamic custom price details, as shown in the screen shot below, will have the most impact on conversion.   In addition, the price detail placement is customizable in the Klarna Merchant Portal, so you can customize the font, layout, and other display details to best match your store user experience, see: https://developers.klarna.com/documentation/on-site-messaging/customization/  

(Static placement types can also work with the app though if desired).

Klarna On-Site Messaging can be configured from the “Custom design” button in the Klarna Merchant Portal, as shown below.

For more information about customizing your dynamic on-site messaging, see: https://developers.klarna.com/resources/on-site-messaging/customization/

Why don’t I see a pink box to drag and drop?

Sometimes the Shopify code to add the required On-Site Messaging JavaScript into a store doesn’t insert the JavaScript.  This is usually the root cause when the preview page doesn’t display the expected “Drop to place Ad” pink box.  Disconnecting the account (from the Settings tab) and reconnecting the account usually resolves this issue.

What does the “Risky Ad Position” error message mean?

If you get an error message when moving the position, such as the example error shown below:

try a different position on the page and you can also try a different preview product for the Shopify Ad.   The Ad position attaches to a CSS selector on the page, which should be a CSS option that is available on all product pages.  The chosen CSS selector can be viewed in the CSS section.  If dragging and dropping doesn’t find a good CSS selector, you can manually enter an appropriate CSS selector from your page, or if the Ad is already the desired position, review the front end store view and verify that it is working correctly across products.  

How to resolve the “Failed to install global code snippet” error?

If you receive the “Failed to install global code snippet in your theme.liquid file” error per screen shot below, verify that your theme.liquid file has an ending `</body>` tag. When attempting to inject theme globals, the app looks for this tag and inserts the script just before it. If this tag is not found this error is returned.  To resolve, the theme.liquid should be updated to include an ending `</body>` tag and then the Klarna account can be disconnected and reconnected to properly insert the required global code snippet.

How do I add a placement to other pages, such as Home Page?

This app currently only supports adding On-Site Messaging to the product and cart pages.  To update other pages, such as a Home page banner, you can customize your store theme (from Online store->Customize button), such as adding a new section with a slide show (either as a single image in the slide show or along with other images) or depending on your theme, with HTML.  Static Klarna marketing images are available at: https://guidelines.klarna.com/co-marketing

Where can I find the placement data on my store front end page?

Open browser’s developer tools and go to the 'Inspect' tab, you should be able to see all instances of klarna-placement; you will NOT see the klarna-placement directly in the HTML source of the page as the placements get injected into the DOM by Javascript when a user loads the page

Why isn’t the placement displayed on my product pages?

Please try using a few different preview products and a few different locations on the page.  If there is an error in the console, the Ad position may be attaching to something specific to a certain product.   Try choosing different preview products and also try alternate locations for the Ad Position on the page.

If the pink box displays on the app preview page, but not on the storefront, inspect the page to verify if the placement exists on the page but is hidden (style="display: none;").  Usually the cause for this is the product price does not fall within the min and max of supported covered prices applicable to Klarna Payments options.  If the placement does not exist on the page, verify in the HTML source of the page that the KlarnaThemeGlobals code exists on the page.  If not, check the theme.liquid to verify that the page has accurate, valid ending </body> tag and includes the KlarnaThemeGlobals prior to the ending body tag.

While we’ve worked hard to build the app to work with most and many themes, if it is not able to find correct anchor tags for your theme, you can either use the Auto-Install->Custom option to provide an appropriate anchor tag or fallback to manually editing your theme to insert the placement code & refresh script directly into your theme.  If you need further support, email skosm@klarna.com and we can request access to your store theme to review.

Why isn’t the placement displayed on my cart pages?

This app does not update mini-cart or pop-cart pages.  If you have an active cart placement, verify that on-site messaging is displayed on the full page cart, e.g. {store name}/cart

How can I get the placement in a specific location on a page?

If the placement doesn’t display in the desired location after dragging and dropping the pink box to attach to a CSS element already in your theme, you can add a custom CSS element to the specific, desired location in your theme page by updating your appropriate theme liquid file (e.g. product.liquid), e.g.:

<span id="ShopifyKlarnaOnSiteMessagingAppElement"></span>

Once the element exists in the theme page, go to the app and update the Ad Position (bottom right of page)-> CSS selector and specify the anchor element as your custom CSS element (#ShopifyKlarnaOnSiteMessagingAppElement ), as shown in screen shot below:

If the placement doesn’t display on the storefront, view the HTML source of the page and search for your custom element (“ShopifyKlarnaOnSiteMessagingAppElement”).  If it does not exist, edit the theme liquid files to put the custom CSS element in a  location that does exist for the page.

Why isn’t the placement updating when I change the variant?

The app will attempt to update the price attribute of the placement when variants are changed. The app will then call the refresh-placements event on the KlarnaOnsiteService data layer. For the app to detect changes in variant and to retrieve the price, the shop theme must be configured in a way that appends the variant id to the URL (e.g https://myshop.com/products/test-product?variant=1234567890123). The way that the app detects changes in variants is by listening to input/select elements. In cases where the theme is using a different/custom approach, the theme must be edited so that the following function is called when variants change:

window.KOSMApp.updatePurchaseAmount();

Why don’t I see On-Site Messaging after changing my theme?

Klarna On-Site Messaging for a Shopify store utilizes CSS data within a theme.  If the theme is changed for a store, all active Ad Positions are deactivated by the Klarna On-Site Messaging app by default.  After changing themes, merchants will need to reactivate, and possibly reposition, on-site messaging in the app using the new theme.

The app does have a configurable setting to enable merchants to deactivate the functionality that deactivates placements, see screen shot below, but as described, it is recommended that merchants test after theme changes.

Does the app support multi-currency?

As Klarna Payments can only accept orders in the store’s base currency (which is a Shopify restriction for all alternative payment providers as documented at https://x.klarnacdn.net/plugins/Klarna%20Payments%20on%20Shopify%20-%20Merchant%20Guide.pdf), the on-site messaging is hidden when the selected currency does not match the store’s base currency when using standard currency switcher functionality.

Manual OSM integration (not using the SKOSM app)

If the app is not compatible with your store (e.g. some app or code in your store blocks the app preview, JavaScript errors prevent the app code from running such as InstantClick), you can directly integrate Klarna On-Site Messaging manually instead of using the Shopify app use custom code for your store, or use a combination of the app (for the JavaScript and refresh placements) and custom code.

If directly inserting OSM into a Shopify theme without the SKOSM app, to be legally compliant with accurate on-site messaging,  make sure to code for refreshing the placements when variants change.  Note: If the app code is still active, the app will refresh both manual placements and app placements when variants change, but manual placements will only display if the app has one active placement (even if that doesn’t display on the front end).

  1. Add the Klarna On-Site Messaging JavaScript library to the Shopify store

To add the merchant-specific JavaScript library to the Shopify store, see documenatation at https://developers.klarna.com/resources/on-site-messaging/js-library. The merchant’s specific JavaScript library can be retrieved from the Klarna Merchant Portal.  Documentation about adding JavaScript to a Shopify store via a POST API call is available at: https://help.shopify.com/en/api/reference/online_store/scripttag

Below is an example BODY of the POST call to add a new script to a Shopify store, e.g. https://yourshopifystorename.myshopify.com/admin/script_tags.json:

{

        "script_tag": {

                "event": "onload",

                "src": "https:\/\/us-library.klarnaservices.com\/merchant.js?uci=12388ec-4565-7897-ba62-009ba1ad0ecb&country=US"

        }

}

  1. Add placement to the theme

The appropriate theme files to update with Klarna On-Site Marketing placement tags & refresh code are dependent upon the Shopify theme you are using. For an example, using the Brooklyn theme, both the klarna-placement tag and refresh code are put into product.liquid.   The appropriate liquid variable for the product price, which is also dependent on the store’s theme, must be used for the placement.  In the example below, current_variant.price the appropriate variable.  Depending on your store’s theme and section of code, you may use variant.price, current_variant.price, or another liquid variable.  

Below is an example of placement code for a Shopify theme, which is also available in the Klarna Merchant Portal:

<klarna-placement data-id="11111111-2222-4b99-aa19-a4e4f619ee5e" data-purchase_amount="{{ current_variant.price }}"></klarna-placement>

  1.  Refresh placements when variants change

If your store has products with variants, you will also need to add code to update the on-site messaging placement when the customer selects a different variant, as documented at: https://developers.klarna.com/resources/on-site-messaging/placements/#refreshing-placements.  

Below is an example of refresh code:

document.getElementsByTagName("klarna-placement")[0].setAttribute("data-purchase_amount", variant.price);

window.KlarnaOnsiteService = window.KlarnaOnsiteService || []

window.KlarnaOnsiteService.push({ eventName: 'refresh-placements' })

Removing the Klarna On-Site Messaging app

If you no longer want to use the Klarna On-Site Messaging app for Shopify in your store, in order to remove all inserted code for your store, first disconnect the account from the app Settings page.  (Do not go back to the app Dashboard or it will automatically reconnect your account.)  Then uninstall the app.  All code will thus be removed from your store.  

You can confirm this by viewing the HTML source of the page to check the JavaScript libraries loaded for your store (search for the ‘asyncLoad’ function).   To check for the placement code, inspect the code and search for ‘klarna-placement’ and ‘KlarnaThemeGlobals’.

Helpful Links

Privacy Policy

https://www.klarna.com/uk/privacy-policy/

Legal Compliance

Please verify that product prices are correctly reflected within the Klarna On-Site Messaging placement, specifically any products that have different prices for different variants.  The placement should be refreshed when the variant is updated by the customer.

Support

If additional support is needed, please email skosm@klarna.com (and please include your Shopify store name).