Klarna Docs - On-site Messaging

On-site Messaging

Adding On-Site Messaging is as easy as it gets, to achieve this tailor made experience for the user you just have to;

  • Create the Native View
  • Set Parameters
  • Call Render

CREATING THE NATIVE VIEW

The On-Site Messaging native view in Android is called KlarnaOSMView. You can create KlarnaOSMView programmatically or inflate from a XML file. Additionally you can also set parameters from the XML.

Create Programmatically

You can create the native view programmatically and place it in your application with desired layout options.

Activity, Fragment or Custom View

JAVA
// Create an instance of OSM view
val osmView = KlarnaOSMView(context)

// Add it to your container with desired layout parameters
val osmLayoutParams = ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.WRAP_CONTENT)
containerViewGroup.addView(osmView, 0, osmLayoutParams)

Create from the XML

Optionally you can also create the native view in your XML and get the view instance programmatically either by findViewById or generated DataBinding instance of your layout.

XML File

MARKUP
<com.klarna.mobile.sdk.api.osm.KlarnaOSMView
    android:id="@+id/klarnaOsmView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    ... />

Activity, Fragment or Custom View

JAVA
val osmView = findViewById<KlarnaOSMView>(R.id.klarnaOsmView)

SETTING THE PARAMETERS

Parameters used for the KlarnaOSMView are set as variables of the View instance or as attributes in the XML declaration. These can be identifier string values, amount or enumeration values.

Available Parameters

ParamTypeDescription
clientIdString*On-Site Messaging Client Identifier gathered from Klarna Merchant Portal.
placementKeyString*Placement key identifier from Klarna Merchant Portal.
localeString*Locale string for the placement configuration, default value is en-US.
purchaseAmountLong?Amount for the placement. Set in micro units ($120.00 = 12000), used for amount based credit promotions.
environmentKlarnaOSMEnvironment*Enumerated environment value to specify merchant’s running environment. Default value isDEMOenvironment.
regionKlarnaOSMRegion*Enumerated region value to specify merchant’s running market region.
themeKlarnaOSMTheme*Enumerated theme value to specify how to stylize the view on light and dark configurations.
hostActivityActivity*Activityinstance to specify parent activity. Will be used for inner linking for informational pages. The reference will be kept as a weak reference.

Read more about Klarna On-Site Messaging activation and features here

KlarnaOSMEnvironment

Environment enumeration will be used to define whether to use a demo placement or fetch placement configurations from either playground or production.

NameDescription
DEMOThis environment ignores all other parameters and shows a demo placement config containing all On-Site Messaging features.
PLAYGROUNDThis environment is for placement configurations from playground Merchant Portal.
PRODUCTIONThis environment is for production builds of the app with placement configurations for production merchants.

KlarnaOSMRegion

Region enumeration will be used to define which endpoint to connect as a source for the placement configurations.

NameDescription
EURegion value for Europe.
NARegion value for North America.
OCRegion value for Oceania.

KlarnaOSMTheme

Theme enumeration will be used to define which style of OSM to be used, depending on either the app’s configuration or the system setting.

NameDescriptions
LIGHTLight style for placement view.
DARKDark style for placement view.
AUTOMATICAutomatic theme that will use the system’s user interface style.

Setting the Parameters

All of the parameters for On-Site Messaging are stored as variables on the KlarnaOSMView instance. The required ones need to be set before calling the render method, otherwise the RenderResult will return a validation error for the missing parameter.

The parameters can either be set programmatically or from the XML layout file(except the hostActivity parameter). In both cases, values will be stored in the instance but the render method needs to be called explicitly from the merchant application.

Setting Parameters Programmatically

JAVA
osmView.clientId = "<client-id>"
osmView.placementKey = "<placement-key>"
osmView.locale = "en-US"
osmView.purchaseAmount = 1000
osmView.environment = KlarnaOSMEnvironment.PRODUCTION
osmView.region = KlarnaOSMRegion.NA
osmView.theme = KlarnaOSMTheme.DARK
osmView.hostActivity = this

Setting Parameters from XML

MARKUP
<com.klarna.mobile.sdk.api.osm.KlarnaOSMView
    ...
    app:klarnaOsmClientId="<client-id>"
    app:klarnaOsmPlacementKey="<placement-key>"
    app:klarnaOsmLocale="en-US"
    app:klarnaOsmPurchaseAmount="1000"
    app:klarnaOsmEnvironment="production"
    app:klarnaOsmRegion="na"
    app:klarnaOsmTheme="dark"/>

XML

RENDERING THE PLACEMENT

Once you have set all the parameters to the KlarnaOSMView, you are ready to render the actual placement view. To do that, you need to call the render method of the view with the RenderResult callback parameter.

Then, once the render method is called, first the view will validate all the parameters. If there is a missing parameter the RenderResult callback will be invoked with corresponding error values. If parameters are valid then the view will try to fetch placement configuration from On-Site Messaging API. Any errors or failures from this network request will also invoke RenderResult callback if necessary. If the placement configuration is fetched and valid then the KlarnaOSMView will render it with native views and invoke the RenderResult callback with a null value.

Calling the Render Method

The RenderResult callback can be used for logging purposes or to make the KlarnaOSMView visible or not, according to the error.

JAVA
osmView.render(RenderResult { error ->
    ...
})

Identifying the Errors

Similar to other parts of the In-App SDK, On-Site Messaging also makes use of the KlarnaMobileSDKError class. To read more about the error handling and error object properties refer to the On-Site Messaging Error Handling guide.

Klarna On-Site Messaging Error Names

These are the predefined names for errors that can happen during the placement render flow. These names are available as static variables inside KlarnaOSMError class.

Error NameDescription
KlarnaOSMErrorMissingClientIdClient ID was not set. Set the clientId variable and invoke render again.
KlarnaOSMErrorMissingPlacementKeyPlacement key was not set. Set the placementKey variable and invoke render again.
KlarnaOSMErrorMissingRegionRegion was not set. Set the region variable and invoke render again.
KlarnaOSMErrorMissingHostHosting activity was not set. Set the hostActivity variable and invoke render again.
KlarnaOSMErrorInvalidPlacementConfigFetched configuration from the API can not be rendered by the native view.
KlarnaOSMErrorPlacementErrorOn-Site Messaging API has returned an error. Message of this error will contain information sent from the API.
KlarnaOSMErrorNetworkErrorA network error occurred and the placement will not be rendered.
KlarnaOSMErrorDisabledNative On-Site Messaging has been disabled by Klarna, the placement will not be rendered.