Skip to main content

Installation

This library includes built-in support for the React Native New Architecture. While not strictly required, we strongly recommend using Expo alongside the New Architecture for the best experience. For a limited transition period, the classic bridge for the React Native Old Architecture will continue to be supported.

1. Install the library​

The easiest way to integrate Ometria is using Expo with the config plugin. This automatically handles all native configuration.

1. Install the package​

pnpm add react-native-ometria

2. Configure the plugin​

Add to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      ["react-native-ometria"],
      "@react-native-firebase/app",
      "@react-native-firebase/messaging",
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "static",
            "forceStaticLinking": ["RNFBApp", "RNFBMessaging"]
          }
        }
      ]
    ]
  }
}
info

forceStaticLinking is required for iOS — without it, RNFBApp and RNFBMessaging are compiled as framework modules, causing a build error when they import React Native headers.

Plugin Options​

OptionRequiredDescription
customAppGroupIdentifierNoOverride the auto-generated iOS App Group identifier. The plugin automatically generates the appGroupIdentifier from your ios.bundleIdentifier as group.{bundleIdentifier}.
skipNSENoSkip the Notification Service Extension setup. When true, rich push notification content (images, etc.) will not work on iOS. Defaults to false.

3. Run prebuild​

npx expo prebuild

2. Initialize the SDK​

After installation, initialize the SDK in your app:

import Ometria from 'react-native-ometria';

await Ometria.initializeWithApiToken('YOUR_API_KEY', {
  // optional params
});
Ometria needs to be initialized first

Any other Ometria methods must be called after initialization.

Optional Parameters​

ParameterPlatformDescription
notificationChannelNameAndroidCustom name for the notification channel. Default is blank.
appGroupIdentifieriOSSpecifies the App Group identifier used by the Notification Service Extension.

Expo projects: by default, this value is set to group.{bundleIdentifier}. You may override it if a different identifier is needed.

Bare React Native: this value must match the App Group configured in Xcode. Refer to iOS Push Setup for configuration details.

3. Start Tracking Events​

After initialization, you can start tracking customer behaviour:

// Identify the user
Ometria.trackProfileIdentifiedByEmailEvent('user@example.com');

// Track a product view
Ometria.trackProductViewedEvent('product-123');

// Track adding to basket
Ometria.trackBasketUpdatedEvent({
  totalPrice: 29.99,
  id: 'basket-456',
  currency: 'USD',
  items: [{ productId: 'product-123', quantity: 1, sku: 'SKU123' }],
});

See Event Tracking for the complete list of available events.

4. Using multiple API tokens​

There are cases where different flows of an application should log events under different tokens (think of different regions in your ecommerce setup, or other similar scenarios). To address this, we offer the possibility of reinitializing the Ometria SDK. Although we currently do not keep references to multiple instances of the SDK, we ensure that on reinitialization there will be a flush attempt for all the events that have been logged up to that point on the old instance.

Reinitializing the SDK requires the exact steps as a normal initialization. Please consult Initialize the SDK in order to make sure everything is set up properly.