On-site messaging for Flutter

Add On-site messaging to a Flutter app with Klarna's core and messaging packages.

5 min read

Add On-site messaging to your Flutter app

Use Klarna's core and messaging packages to add credit promotion placements to your Flutter app on iOS and Android.

Prerequisites

Before you start:

1.
Make sure you have Klarna enabled and access to the Klarna Partner Portal.
2.
In the Klarna Partner Portal, generate a client identifier with your domain URL allowlisted.
3.
Use Flutter 3.22 or later and Dart 3.6 or later.
4.
Set the minimum deployment target to iOS 13 or Android API 24.
5.
Decide where the placement should appear and provide the purchase amount in minor units and its ISO 4217 currency code.

Integration overview

sequenceDiagram participant Consumer participant Merchant App participant Flutter SDK participant Klarna Merchant App->>Flutter SDK: Klarna.initialize(configuration) Flutter SDK->>Klarna: Initialize session Merchant App->>Flutter SDK: Render KlarnaMessagingPlacementView Flutter SDK->>Klarna: Request placement content Klarna-->>Flutter SDK: Return localized messaging Flutter SDK-->>Consumer: Display placement

1.
Install the Core and Messaging packages.
2.
Initialize a shared Klarna instance.
3.
Add KlarnaMessagingPlacementView to your widget tree.
4.
Update its configuration when the amount, currency, placement type, or theme changes.
5.
Handle placement errors and dispose the shared Klarna session when it is no longer needed.

Install packages

Add both packages to your Flutter app:

BASH

1 2 3

flutter pub add klarna_network_core
flutter pub add klarna_network_messaging

Android

Klarna Mobile SDK artifacts are hosted in Klarna's Maven repository. Add the repository to your app's dependency resolution repositories:

GROOVY

1 2 3 4

maven {
    url 'https://x.klarnacdn.net/mobile-sdk/'
}

On-site Messaging is view-only and does not require FlutterFragmentActivity.

iOS

The appReturnUrl passed during SDK initialization must use a scheme registered in your app's Info.plist:

XML

1 2 3 4 5 6 7 8 9 10

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER).returnurl</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>your-app</string>
    </array>
  </dict>

Use a matching return URL, for example your-app://klarna-return.

Initialize the SDK

Import the Core and Messaging packages and initialize a shared Klarna session:

DART

1 2 3 4 5 6 7 8 9 10

import 'package:flutter/foundation.dart';
import 'package:klarna_network_core/klarna_network_core.dart';
import 'package:klarna_network_messaging/klarna_network_messaging.dart';

final klarna = await Klarna.initialize(
  KlarnaConfiguration(
    clientId: 'your-client-id',
    appReturnUrl: 'your-app://klarna-return',
    accountId: 'your-account-id',
    locale: 'en-US',

Keep the Klarna instance for as long as Klarna features in your app need to share the same native session. Calling Klarna.initialize again with an equivalent configuration reuses the same instance until it is disposed.

Handle return URLs

Return URLs are not used by On-site Messaging placements directly. They are required by the shared Dart configuration and support other Klarna features that can open external flows.

When a URL returns to your app, offer it to the Core SDK:

DART

1 2

final handled = await Klarna.handleReturnUrl(url);

On iOS, this dispatches the URL to the native Klarna SDK. On Android, it currently returns false.

Render a messaging placement

Add KlarnaMessagingPlacementView to your widget tree:

DART

1 2 3 4 5 6 7 8 9 10

KlarnaMessagingPlacementView(
  instance: klarna,
  configuration:
      const KlarnaMessagingPlacementConfiguration.creditPromotionAutoSize(
    amount: 19900,
    currency: 'EUR',
    theme: KlarnaTheme.automatic,
  ),
  onError: (error) {
    debugPrint('${error.name}: ${error.message}');

The amount is expressed in minor units. For example, 19900 represents EUR 199.00.

The placement starts with a fallback height, adopts the height reported by the native SDK, and collapses when no content is available. You do not need to set an explicit height.

To render a compact badge, use the badge configuration:

DART

1 2 3 4 5 6 7 8 9 10

KlarnaMessagingPlacementView(
  instance: klarna,
  configuration:
      const KlarnaMessagingPlacementConfiguration.creditPromotionBadge(
    amount: 19900,
    currency: 'EUR',
    theme: KlarnaTheme.automatic,
  ),
  onError: (error) {
    debugPrint('${error.name}: ${error.message}');

When checkout values change, rebuild the widget with a new configuration. The SDK updates the native placement when its amount, currency, placement type, theme, or Klarna instance changes.

Error handling

Initialization can throw KlarnaSDKError. Placement errors are delivered through onError:

DART

1 2 3 4 5 6 7

try {
  final klarna = await Klarna.initialize(configuration);
  // Render the placement with this instance.
} on KlarnaSDKError catch (error) {
  debugPrint('${error.name}: ${error.message}');
}

KlarnaSDKError provides name, message, and an optional cause.

The placement widget unregisters its native callbacks automatically when removed from the widget tree. Dispose the shared session when it is no longer needed:

DART

1 2

await klarna.dispose();

Parameters

`KlarnaConfiguration`

Parameter	Type	Required	Description
`clientId`	String	Yes	The client identifier from the Klarna Partner Portal. If the integration is done by a PSP/distribution partner, use the distribution partner's own client ID.
`appReturnUrl`	String	Yes	URL used to return to the app from external flows. On iOS, its scheme must be registered in `Info.plist`.
`accountId`	String?	No	Optional Klarna account identifier.
`locale`	String?	No	Session locale, for example `en-US`.

Placement configuration

Parameter	Type	Required	Description
`instance`	Klarna	Yes	Shared session returned by `Klarna.initialize`.
`configuration`	KlarnaMessagingPlacementConfiguration	Yes	Placement type, amount, currency, and optional theme.
`onError`	`ValueChanged<KlarnaSDKError>?`	No	Called when the placement reports an asynchronous error.

Placement types

Constructor	Description
`KlarnaMessagingPlacementConfiguration.creditPromotionAutoSize`	An automatically sized credit promotion banner.
`KlarnaMessagingPlacementConfiguration.creditPromotionBadge`	A compact credit promotion badge.

Both constructors require:

Parameter	Type	Description
`amount`	int	Purchase amount in minor units.
`currency`	String	ISO 4217 currency code, for example `EUR` or `USD`.
`theme`	KlarnaTheme?	Optional visual theme. The native SDK default is used when omitted.

Themes

Value	Description
`KlarnaTheme.light`	Light theme.
`KlarnaTheme.dark`	Dark theme.
`KlarnaTheme.automatic`	Follow the platform appearance.

Jump to section...