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.

The Old Architecture is deprecated and supported until 2.9.x

2.9.x is the last release line that supports React Native's Old Architecture. The next major version will require the New Architecture, so if your app still uses the Old Architecture, stay on react-native-ometria@~2.9.0.

react-native-ometria 2.x works with React Native Firebase 26.x or earlier. React Native Firebase 27 is not supported on 2.x.

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", { "ios": { "disableSPM": true } }],
      "@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.

"disableSPM": true is needed with React Native Firebase 26.2 to 26.x: it installs Firebase through CocoaPods, which static linking requires. React Native Firebase 26.1 needs it too but doesn't have this option, so use 26.2 or later. Versions before 26.1 don't need it. React Native Firebase 27 is not supported on 2.x.

Expo SDK 58

With React Native Firebase 26 or earlier, React Native Firebase's own plugin can't find where to add FirebaseApp.configure() in Expo SDK 58's AppDelegate.swift and prints "Skipping Firebase addition". From 2.9.0, the Ometria plugin adds the call for you. If you added FirebaseApp.configure() yourself as a workaround, remove it when you upgrade, so Firebase isn't configured twice.

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. Not supported for production apps: when true, rich push notification content (images, etc.) won't work on iOS and received notifications aren't tracked reliably. See Notification Service Extension. 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.