Guides
  1. React Native

Initialization & Usage

1) Initialize

Call initialize once at app startup, before any other SDK method.

environment — dev, test or prod. Use test during development to avoid creating
unnecessary transactions. Always set it explicitly: if omitted, iOS falls back to prod.

debugMode — skips the security scan process. Use it in your development environment only.
It also enables WebView inspection and, on Android, removes FLAG_SECURE. Always false in
production builds — this is a security switch, not a log level.

showDebugScreen — shows a small FAB button in the bottom-right corner. You can track all
logged events, API requests and SSE conditions with it.

theme (new) — system, light or dark. Sets the SDK's starting theme during
initialize, so you no longer need a setTheme call right after initialize just to make the
loyalty WebView open in your app's theme. Omit it to keep the native default (device theme).

language (new) — BCP-47 tag (tr, tr-TR). The setLanguage counterpart of theme.
Omit it to keep the host app's language. An empty or blank value counts as not provided
rather than as a reset.

theme and language set the starting value only. Keep calling setTheme /
setLanguage when the user changes either one later.

Once the SDK is initialized, setUser needs to be called if a user is logged in.

import { KLP } from "@kaizen-dev-team/rn-sdk";

await KLP.initialize({
  environment: __DEV__ ? "test" : "prod",
  debugMode: __DEV__,
  showDebugScreen: false,
  // Optional starting appearance
  theme: isDark ? "dark" : "light",
  language: "tr"
})
  .then(() => KLP.setUser("access-token"))
  .catch((error) => {
    console.error("[KLP] initialize failed:", error);
  });

An unknown theme or language value rejects the promise instead of being ignored —
silently skipping it would open the WebView in the wrong appearance with nothing to point at.

2) Set User After Login

After a successful login, pass the authentication token. Call it after initialize when the
user is already logged in at startup.

await KLP.setUser("access-token");

Changed: setUser takes a single argument. There is no user id parameter — the
backend resolves the user from the access token. If you are migrating from a two-argument
call, drop the first one.

setUser performs full session activation: it runs the challenge flow, drops the WebView
cache and starts real-time notifications.

Ending the session

await KLP.logout();

3) Refresh the Access Token

When your app refreshes the access token through its own refresh-token flow, call setToken.
Unlike setUser, this does not re-run session/challenge activation and does not restart
real-time notifications — it only swaps the stored token, so it is safe to call frequently.

const updated = await KLP.setToken(
  "new-access-token",
  undefined // optional expiry, epoch millis
);

Resolves to false (no-op) when there is no active session or accessToken is empty.

setToken refreshes a live session; it does not revive a dead one. If activation failed
(see error codes on the errors page), the stored session is already cleared and setToken
returns false. Run your own refresh flow and call setUser(newToken) instead.

4) Launch Loyalty Screen

Open the gamification screen directly. The optional parameter opens a specific screen.

await KLP.launch();
// or
await KLP.launch("rewards");

Valid path values are the routes of the loyalty web experience — confirm them with your
integration owner.

5) Log Business Events

Call logEvent to log an event from the frontend. The first parameter is the event name, the
second is an optional attributes object.

await KLP.logEvent("MoneyTransfer", {
  amount: 500,
  currency: "TRY"
});

Encrypted events

For events carrying sensitive values, use logEncryptedEvent. The event type and each
attribute value are encrypted natively (RSA-OAEP-SHA256, using the challenge public key)
before transmission. Attribute names stay in plain text.

await KLP.logEncryptedEvent("MoneyTransfer", {
  amount: 500,
  currency: "TRY"
});

6) Theme & Language

The SDK owns its own theme and language, and the loyalty WebView follows them. Set the
starting values in initialize, then keep them in sync as the user changes them.

await KLP.setTheme("dark");            // "system" | "light" | "dark"
await KLP.setLanguage("tr");           // null resets to the system locale

const appearance = await KLP.getAppearance();
// { theme: "system", resolvedTheme: "dark", languageTag: "tr" }

React to changes the SDK makes on its own (for example when the device theme changes while
theme is system):

const removeTheme = KLP.onThemeChanged(({ theme, resolvedTheme }) => {
  console.log("Theme:", theme, "resolved as", resolvedTheme);
});

const removeLanguage = KLP.onLanguageChanged(({ languageTag }) => {
  console.log("Language:", languageTag);
});

Pass the language without a region (tr, not tr-TR) unless you specifically need it —
a regional tag the web experience does not recognize falls back to the device language.

7) Redirecting on the host application

To redirect inside your app, attach a listener to onDeepLink. url is the screen name you
assign in the KLP Admin.

const removeDeepLink = KLP.onDeepLink(({ url, path, queryParameters }) => {
  console.log("Deep link:", url);
  // navigate in your app
});

// Later, when the screen unmounts
removeDeepLink.remove();

The SDK always hands deep links to the host and never navigates by itself. If no
listener is attached, the link is silently dropped — subscribe before the user can reach a
screen that emits one.

8) Campaign progress events / disabling the KLP progress popup

By default the SDK listens for campaign progress over SSE and presents it to the user with its
own popup. To show a custom design instead — or to show nothing at all — attach a listener to
onSSEEffects.

While at least one onSSEEffects listener is attached, the SDK's popup is not shown; your
listener owns the presentation. Removing the last listener hands presentation back to the SDK.

const removeEffects = KLP.onSSEEffects(({ effects }) => {
  // Present the effects with your own UI
  console.log("Effects:", effects);
});

// Later — the SDK popup becomes active again
removeEffects.remove();

onRewardEarned is a separate notification, for rewards earned inside the loyalty WebView.
It does not affect the progress popup:

const removeReward = KLP.onRewardEarned((reward) => {
  console.log("Reward earned:", reward.name);
});

removeReward.remove();

Suppression follows the subscription, not a per-event decision — the popup stays away for
as long as a listener is attached. An open loyalty WebView is notified of the effects either
way, so in-page content stays up to date whichever option you choose.

9) Status & security

const ready = await KLP.isInitialized();
const secure = await KLP.isDeviceSecure();
const result = await KLP.performSecurityChecks();
// { allPassed: false, checks: [{ name, passed, errorMessage }] }

await KLP.openDebugScreen(); // Android only — always resolves false on iOS

isInitialized() reflects whether the loyalty feature is enabled for this user, not just
whether initialize ran. If the backend reports the feature as not visible, it returns
false even after a successful initialize, and launch will not open anything.

Security failures can also arrive after initialize resolves. Subscribe to
onSecurityError rather than relying on the initialize result alone:

const removeSecurityError = KLP.onSecurityError(({ allPassed, checks }) => {
  console.warn("Security checks failed:", checks.filter((c) => !c.passed));
});

Notes

  • Call initialize before any other SDK method.
  • Set environment explicitly as one of dev, test, prod.
  • Call setUser with the access token after host app authentication — no user id.
  • Call setToken when your app refreshes the token, and logout when the user signs out.
  • Prefer debugMode: false and showDebugScreen: false in production builds.
  • Attach an onSSEEffects listener only if you intend to present campaign progress
    yourself — while one is attached, the SDK's own popup stays hidden.
  • The SDK exposes no UI components — it renders the loyalty experience in its own WebView.
    Place your own entry point (button, banner, card) in your app and call KLP.launch() from it.

Updated about 1 month ago

Did this page help you?