klaviyo-react-native-sdk


Contents

- klaviyo-react-native-sdk
- Introduction
- Klaviyo Expo Plugin
- Requirements
- React Native
- Android
- iOS
- Installation
- Android
- iOS
- Initialization
- React Native Initialization
- Native Initialization
- Identifying a Profile
- Reset Profile
- Anonymous Tracking
- Event Tracking
- Push Notifications
- Prerequisites
- Setup
- Collecting Push Tokens
- React Native Token Collection
- Native Token Collection
- Receiving Push Notifications
- Rich Push
- Badge Count
- Tracking Open Events
- Deep Linking
- Silent Push Notifications
- Custom Data
- In-App Forms
- Prerequisites
- Setup
- In-App Forms Session Configuration
- Unregistering from In-App Forms

- Geofencing
- Prerequisites
- Setup
- Unregistering from Geofencing
- Troubleshooting
- Contributing
- License
- Code Documentation

Introduction

The Klaviyo React Native SDK allows developers to incorporate Klaviyo analytics and push notification functionality in
their React Native applications for Android and iOS. It is a Typescript wrapper (native module bridge) around the native
Klaviyo iOS and Android SDKs. For more information on the native SDKs, please see the
iOS and Android.
repositories. This repo also contains a basic React Native sample app to assist your integration.

The SDK assists in identifying users and tracking user events via the latest Klaviyo Client APIs.
To reduce performance overhead, API requests are queued and sent in batches. The queue is persisted to local storage
so that data is not lost if the device is offline or the app is terminated.

Once integrated, your marketing team will be able to better understand your app users' needs and send them timely
push notifications via FCM (Firebase Cloud Messaging) and APNs (Apple Push Notification Service).

Klaviyo Expo Plugin

If you have an Expo app, you can install our plugin to integrate the React Native SDK into your app.
See the Klaviyo Expo Plugin for more details.

Requirements

This SDK was developed and tested against React Native 0.78, as a new-architecture compatible native module.

$3

We support all maintained React Native versions, 0.70+.
We have successfully compiled this SDK on a bare React Native template app down to 0.68.7.

$3

- minSdkVersion of 23+
- compileSdkVersion of 34+

$3

- Minimum Deployment Target 13.0+

Installation

The Klaviyo React Native SDK is available via NPM. To add it to your project,
run the following from your project's root directory:

``sh


Using npm

npm install klaviyo-react-native-sdk

Using yarn

yarn add klaviyo-react-native-sdk
`

$3

We have included an example app in this repository for reference of how to integrate with our SDK.
It is primarily intended to give code samples such as how and where to initialize, implement notification
delegate methods on iOS, and handle an opened notification intent on Android. We've commented the sample app
code to call out key setup steps, search for iOS Installation Step and Android Installation Step.

To run the example app:

- Clone this repository
- From the root directory, run yarn example setup. This is an alias that will do the following:
- Run yarn install --immutable from the root directory
- Navigate to the example directory and run bundle install
- Navigate to the example/ios directory and run bundle exec pod install
- Android configuration:
- To initialize Klaviyo from the native layer, open example/android/gradle.properties and follow the
instructions to set your publicApiKey and verify initializeKlaviyoFromNative is enabled.
- If you wish to run the Android example app with push/firebase, you'll need to copy a google-services.json
file into example/android/app/src and update the applicationId in app/build.gradle to match your application ID.
Then, open example/android/gradle.properties and follow the instructions to enable useNativeFirebase.
This is disabled by default because the app will crash on launch without a google-services.json file.
- From the project's root directory, use the following commands start a metro server and run the example app.
- yarn example start - to start the metro server
- yarn example android - to run the example app on an Android emulator or device
- yarn example ios - to run the example app on an iOS simulator

$3

Android installation requirements may vary depending upon your project configuration and other dependencies.
The Klaviyo React Native SDK's build.gradle file exposes transitive dependencies upon the Klaviyo Android SDK,
so you can import Android Klaviyo SDK references from your Kotlin/Java files without modifying your gradle configuration.

#### React Native 0.74+

There are no additional installation requirements. Android support is fully tested and verified.

#### React Native 0.68.x - 0.72.x

We have successfully compiled the Klaviyo React Native SDK in a bare React Native template app for these versions
with the following modifications to the android/build.gradle file:

- Set minSdkVersion=23
- Set compileSdkVersion=34

See Android Troubleshooting for possible exceptions.

$3

After installing the npm package, run the following command in the ios directory of your React Native project.
Install Cocoapods if you have not already.

`sh
pod install
`

You may also need to run pod update or pod install --repo-update after updating your SDK version.

Initialization

The SDK must be initialized with the short alphanumeric public API key
for your Klaviyo account, also known as your Site ID.

Initialize _must_ be called prior to invoking any other SDK methods so that Klaviyo SDK can track profiles, events and
push tokens toward the correct Klaviyo account. Any SDK operations invoked before initialize will be dropped,
and result in a logged error.

You can call initialize from your app's React Native layer or from the platform-specific native code.
This decision is dependent on your app's architecture. It is not required to initialize the SDK in both places!
Note: It is safe to re-initialize, e.g. if your app needs to switch between more than one Klaviyo account.

$3

Below is an example of how to initialize the SDK from your React Native code:

`typescript
import { Klaviyo } from 'klaviyo-react-native-sdk';
Klaviyo.initialize('YOUR_KLAVIYO_PUBLIC_API_KEY');
`

$3

Follow the native SDK instructions for initialization, and refer to the
example app in this repository for guidance:

- Android SDK instructions, and
example app MainApplication.kt
- iOS SDK instructions, and
example app AppDelegate.mm

Identifying a Profile

The SDK provides methods to identify profiles via the
Create Client Profile API.
A profile can be identified by any combination of the following:

- External ID: A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system,
such as a point-of-sale system. Format varies based on the external system.
- Individual's email address
- Individual's phone number in E.164 format

Identifiers are persisted to local storage on each platform so that the SDK can keep track of the current profile.

Profile attributes can be set all at once:

`typescript
import { Klaviyo, Profile } from 'klaviyo-react-native-sdk';

const profile: Profile = {
email: 'kermit@klaviyo-demo.com',
phoneNumber: '+15555555555',
externalId: '12345',
firstName: 'Kermit',
lastName: 'The Frog',
title: 'CEO',
organization: 'Muppets, Inc.',
location: {
address1: '666 Fake St.',
address2: 'Apt 123',
city: 'Cityville',
country: 'Countryland',
region: 'Regionville',
zip: '11111',
},
};
Klaviyo.setProfile(profile);
`

or individually:

`typescript
import { ProfileProperty, Klaviyo } from 'klaviyo-react-native-sdk';

Klaviyo.setEmail('kermit@klaviyo-demo.com');
Klaviyo.setPhone('+15555555555');
Klaviyo.setExternalId('12345');
Klaviyo.setProfileAttribute(ProfileProperty.FIRST_NAME, 'Kermit');
`

Either way, the native SDKs will group and batch API calls to improve performance.

$3

To start a _new_ profile altogether (e.g. if a user logs out), either call Klaviyo.resetProfile()
to clear the currently tracked profile identifiers (e.g. on logout), or use Klaviyo.setProfile(profile)
to overwrite it with a new profile object.

`typescript
import { Klaviyo } from 'klaviyo-react-native-sdk';

Klaviyo.resetProfile();
`

$3

Klaviyo will track unidentified users with an autogenerated ID whenever a push token is set or an event is created.
That way, you can collect push tokens and track events prior to collecting profile identifiers such as email or
phone number. When an identifier is provided, Klaviyo will merge the anonymous user with an identified user.

Event Tracking

The SDK also provides tools for tracking analytics events via the
Create Client Event API.
A list of common Klaviyo-defined event metrics is provided in MetricName,
or you can just provide a string for a custom event name.

Below is an example using one of the Klaviyo-defined event names:

`typescript
import { Event, Klaviyo, EventName } from 'klaviyo-react-native-sdk';

const event: Event = {
name: EventName.STARTED_CHECKOUT_METRIC,
value: 99,
properties: { products: ['SKU1', 'SKU2'] },
};

Klaviyo.createEvent(event);
`

You can also create an event by providing a string for the event name as follows:

`typescript
import { Klaviyo } from 'klaviyo-react-native-sdk';

Klaviyo.createEvent({
name: 'My Custom Event',
});
`

Push Notifications

$3

Integrating push notifications is highly platform-specific. Begin by thoroughly reviewing the setup
instructions for Push Notifications in the README from each native Klaviyo SDK:

- Android
- iOS

$3

Refer to the following README sections on push setup:

- Android
- iOS

$3

Push tokens can be collected either from your app's react native code or in the native code.
Below sections discuss both approaches, and you are free to pick one that best suits your app's architecture.
Note that doing this in one location is sufficient.

#### React Native Token Collection

In order to collect the APNs push token in your React Native code you need to:

1. Import a library such as @react-native-firebase/messaging
to your react native project. The below instructions are specific for @react-native-firebase/messaging library.
2. Import Firebase iOS SDK to your iOS project. Setup instructions can be found here.
3. In order for the UNUserNotificationCenter delegate methods to be called in AppDelegate, method swizzling must be
disabled for the Firebase SDK. For more information on this, please refer to the Firebase documentation.
Disable method swizzling by adding the following to your Info.plist:
`xml
FirebaseAppDelegateProxyEnabled

`
4. In application:didRegisterForRemoteNotificationsWithDeviceToken: method in your AppDelegate.m file, you can add the following code to set the push token to the firebase SDK:
`objective-c
// since we disbaled swizzling, we have to manually set this
FIRMessaging.messaging.APNSToken = deviceToken;
`
5. Finally, in your React Native code, you can collect & set the push token as follows:

`typescript
import messaging from '@react-native-firebase/messaging';
import { Klaviyo } from 'klaviyo-react-native-sdk';
import { Platform } from 'react-native';

const fetchAndSetPushToken = async () => {
try {
let deviceToken: string | null = null;
if (Platform.OS === 'android') {
// For Android, Klaviyo requires the FCM token
deviceToken = await messaging().getToken();
console.log('FCM Token:', deviceToken);
} else if (Platform.OS === 'ios') {
// For iOS, Klaviyo requires the APNs token
deviceToken = await messaging().getAPNSToken();
console.log('APNs Token:', deviceToken);
}

if (deviceToken != null && deviceToken.length > 0) {
Klaviyo.setPushToken(deviceToken!);
}
} catch (error) {
console.error('Error in fetchAndSetPushToken:', error);
}
};
`

For Android token collection, there isn't any additional setup required on the native side. The above code should work as is.

#### Native Token Collection

Follow the platform-specific instructions below:

- Android
- iOS

#### Notification Permission

Requesting user permission to display notifications can be managed from the React Native code, or from platform-specific
native code. Note that either of these approaches is sufficient to inform the Klaviyo SDK of the permission change.

1. React Native Notification Permission:
You can leverage a third party library that provides cross-platform permissions APIs like firebase react-native-firebase/messaging.
If you opt for a cross-platform permission solution, call the Klaviyo React Native SDK's setToken method to refresh
the token's enablement status.

Below is an example of how to use @react-native-firebase/messaging to request permission and set the token:

`typescript
import messaging from '@react-native-firebase/messaging';

const requestUserPermission = async () => {
let isAuthorized = false;

if (Platform.OS === 'android') {
const androidAuthStatus = await PermissionsAndroid.request(
PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
);
isAuthorized = androidAuthStatus === 'granted';
} else if (Platform.OS === 'ios') {
const iOsAuthStatus = await messaging().requestPermission();
isAuthorized =
iOsAuthStatus === messaging.AuthorizationStatus.AUTHORIZED ||
iOsAuthStatus === messaging.AuthorizationStatus.PROVISIONAL;
}

// refer the fetchAndSetPushToken method from the previous section for how to get and set the push token

if (isAuthorized) {
console.log('User has notification permissions enabled.');
} else {
console.log('User has notification permissions disabled');
}
};
`

2. Native Notification Permission:
Follow instructions from our native SDK documentation to request permission from native code:
- Android
- iOS

If you requested permission using native code then continue using Klaviyo's native platform SDKs setToken
method to inform the SDK of permission change.

$3

You can send test notifications to a specific token using the
push notification preview
feature in order to test your integration.

#### Rich Push

Rich Push is the ability to add images to
push notification messages. On iOS, you will need to implement an extension service to attach images to notifications.
No additional setup is needed to support rich push on Android.

- Android
- iOS

#### Badge Count

Klaviyo supports setting or incrementing the badge count on iOS when you send a push notification.
To enable this functionality, you will need to implement a notification service extension and app group
as detailed in the Swift SDK installation instructions.
See the badge count documentation for more details and the example app for reference.
Android automatically handles badge counts, and no additional setup is needed.

#### Tracking Open Events

Klaviyo tracks push opens events with a specially formatted event Opened Push that includes message tracking
parameters in the event properties. To track push opens, you will need to follow platform-specific instructions.
Currently, tracking push open events must be done from the native code due to platform differences that prevent
us from bridging this functionality into the React Native SDK code.

- Android
- iOS

> Note: If you initialize Klaviyo from React Native code, be aware that on both platforms the timing of when
> an Opened Push event gets triggered can sometimes occur before your React Native code to initialize our SDK
> can execute. To mitigate this, our SDK holds the request in memory until initialization occurs.

#### Deep Linking

Klaviyo Deep Links allow you to navigate to a particular page within your app in response to the user opening a push notification, tapping on a link in an In-App Form, or by tapping on a Universal Link (aka Verified App Link on Android) from outside of the app. The Klaviyo Android SDK supports deep linking via custom URI schemes or Universal Links.

##### Setup

Familiarize yourself with the React Native Linking Guide, then follow
the platform-specific instructions for configuring both custom URL schemes and universal links:

- iOS Deep Linking Setup - Configure custom URL schemes, Associated Domains for Universal Links, and implement the appropriate delegate methods in your AppDelegate
- Android Deep Linking Setup - Configure intent filters for both custom schemes and App Links in your AndroidManifest.xml

##### React Native Code

In your React Native code, use the Linking API to handle both deep links and universal links. The example below
shows how to integrate with Klaviyo's universal tracking link handling:

`typescript
import { useEffect } from 'react';
import { Linking } from 'react-native';
import { Klaviyo } from 'klaviyo-react-native-sdk';

export default function App() {
useEffect(() => {
const handleUrl = (url: string) => {
// Check if this is a Klaviyo universal tracking link
if (Klaviyo.handleUniversalTrackingLink(url)) {
// Klaviyo SDK is handling the tracking link
console.log('Klaviyo tracking link:', url);
return;
}

// Handle other deep links in your app (both custom schemes and universal links)
console.log('Navigate to:', url);
// Add your navigation logic here
};

// Handle the initial URL if the app was opened with a link
Linking.getInitialURL().then((url) => {
if (url) {
handleUrl(url);
}
});

// Listen for deep link events while the app is running
const subscription = Linking.addEventListener('url', ({ url }) => {
handleUrl(url);
});

return () => {
subscription.remove();
};
}, []);

// Rest of your app code
}
`

The Klaviyo.handleUniversalTrackingLink() method will:

- Validate that the URL is a Klaviyo tracking link (format: https://domain/u/...)
- Track the click event
- Resolve the tracking link to its destination URL
- Return true if it handled the link, false otherwise

If the link is not a Klaviyo tracking link, you should handle it as a regular deep link in your app.

#### Silent Push Notifications

Silent push notifications (also known as background pushes) allow your app to receive payloads from Klaviyo without displaying a visible alert to the user. These are typically used to trigger background behavior, such as displaying content, personalizing the app interface, or downloading new information from a server. To receive silent push notifications, follow the platform-specific instructions below:

- Android
- iOS

#### Custom Data

Klaviyo messages can also include key-value pairs (custom data) for both standard and silent push notifications. To receive custom data, follow the platform-specific instructions below:

- Android
- iOS

In-App Forms

In-App Forms are messages displayed to mobile app users while they are actively using an app. You can create new In-App Forms in a drag-and-drop editor in the Sign-Up Forms tab in Klaviyo. Follow the instructions in this section to integrate forms with your app. The SDK will display forms according to their targeting and behavior settings and collect delivery and engagement analytics automatically.

In-App Forms supports advanced targeting and segmentation. In your Klaviyo account, you can configure forms to target or exclude specific segments of profiles and configure event-based triggers and delays. See the table below to understand available features by SDK version.

$3

- Import the Klaviyo module
- We strongly recommend using the latest version of the SDK to ensure compatibility with the latest In-App Forms features. The minimum SDK version supporting In-App Forms is 1.2.0, and a feature matrix is provided below. Forms that leverage unsupported features will not appear in your app until you update to a version that supports those features.
- Please read the migration guide if you are upgrading from 1.2.0 to understanding changes to In-App Forms behavior.

| Feature | Minimum SDK Version |
| ------------------ | ------------------- |
| Basic In-App Forms | 1.2.0+ |
| Time Delay | 2.0.0 |
| Audience Targeting | 2.0.0 |
| Event Triggers | 2.1.0 |

$3

To configure your app to display In-App Forms, call Klaviyo.registerForInAppForms() after initializing the SDK with your public API key. Once registered, the SDK may launch an overlay view at any time to present a form according to its targeting and behavior settings configured in your Klaviyo account.

For the best user experience, we recommend registering after any splash screen or loading animations have completed. Depending on your app's architecture, this might be in a particular Screen's useEffect.

`
import { Klaviyo } from "klaviyo-react-native-sdk";
...

// call this any time after initializing your public API key
Klaviyo.registerForInAppForms();
`

#### In-App Forms Session Configuration

A "session" is considered to be a logical unit of user engagement with the app, defined as a series of foreground interactions that occur within a continuous or near-continuous time window. This is an important concept for In-App Forms, as we want to ensure that a user will not see a form multiple times within a single session.

A session will time out after a specified period of inactivity. When a user launches the app, if the time between the previous interaction with the app and the current one exceeds the specified timeout, we will consider this a new session.

This timeout has a default value of 3600 seconds (1 hour), but it can be customized. To do so, pass an FormConfiguration object to the registerForInAppForms() method. For example, to set a session timeout of 30 minutes:

`
import { Klaviyo } from "klaviyo-react-native-sdk";

let config: FormConfiguration = { sessionTimeoutDuration: 1800 }
Klaviyo.registerForInAppForms(config);
`

$3

If at any point you need to prevent the SDK from displaying In-App Forms, e.g. when the user logs out, you may call:

`
import { Klaviyo } from "klaviyo-react-native-sdk";

Klaviyo.unregisterFromInAppForms(config);
`

Note that after unregistering, the next call to registerForInAppForms() will be considered a new session by the SDK.

Geofencing

> Geofencing support is available in SDK version 2.2.0 and higher.

Geofencing allows you to trigger events when users enter or exit geographic regions. The Klaviyo SDK monitors geofences configured in your Klaviyo account and automatically tracks geofence enter and exit events. The SDK automatically handles geofence synchronization with your Klaviyo account—when you add, update, or remove geofences in Klaviyo, the SDK will automatically sync these changes on the next app launch or when the API key changes.

$3

Integrating geofencing is highly platform-specific as it utilizes the native monitoring systems. Begin by thoroughly reviewing the setup
instructions for Geofencing in the README from each native Klaviyo SDK:

- Android
- iOS

$3

To enable geofencing in your app, you must:

1. Configure location permissions in your app's platform-specific configuration files
2. Call Klaviyo.registerGeofencing() after initializing the SDK

3. Register for geofencing after initializing the SDK:

`typescript
import { Klaviyo } from 'klaviyo-react-native-sdk';

// After initializing with your public API key
Klaviyo.registerGeofencing();
`

$3

If at any point you need to stop monitoring geofences, e.g. when the user logs out or opts out of location tracking, you may call:

`typescript
import { Klaviyo } from 'klaviyo-react-native-sdk';

Klaviyo.unregisterGeofencing();
`

After unregistering, the SDK will stop monitoring geofences and will no longer report geofence transition events. You can call registerGeofencing()` again to resume monitoring.

Troubleshooting

Use the troubleshooting guide to resolve common issues with the Klaviyo React Native SDK.
If the issues you are facing isn't in the troubleshooting guide, and you believe it's a bug in the SDK,
please file an issue in our repository.

Contributing

Refer to the contributing guide to learn how to contribute to the Klaviyo React Native SDK.
We welcome your feedback in the
issues section of our public GitHub repository.

License

The Klaviyo React Native SDK is available under the terms of the MIT license. See LICENSE for more info.

Code Documentation

Browse complete autogenerated code documentation here.