Tealium Prism React Native
    Preparing search index...

    Tealium Prism React Native

    @tealium/prism-react-native

    Tealium Prism is the Tealium SDK for iOS and Android. This package wraps the native Prism SDKs for React Native apps. You call a typed TypeScript API, and the native SDKs run the tracking pipeline. The wrapper adds no tracking logic of its own, so settings and behavior match the native platforms.

    The package has the following requirements:

    • Android API level 24 or later.
    • iOS 15.1 or later.
    • React Native 0.85. This is the version that the example app tests.
    • The New Architecture (TurboModules). The package does not support the legacy architecture.

    Install the core package with npm:

    npm install @tealium/prism-react-native

    Or install it with Yarn:

    yarn add @tealium/prism-react-native

    Add the optional packages that your app needs:

    • @tealium/prism-react-native-extensions adds the SetDataValues, Lowercase, and PersistDataValue transformers.
    • @tealium/prism-react-native-js-transformer transforms dispatches with JavaScript defined in your Tealium settings.
    • @tealium/prism-react-native-lifecycle tracks app launch, wake, and sleep events.

    The optional packages register themselves with the core package. Your Tealium settings decide which modules run.

    Install the native iOS dependencies:

    cd ios && pod install

    Android needs no extra steps because autolinking adds the native dependencies.

    To check the native Prism SDK version, call getSdkVersion:

    import { getSdkVersion } from "@tealium/prism-react-native";

    const version = await getSdkVersion();

    Create a single instance when the app starts, and share it across your app. Tealium.create has the following signature:

    Tealium.create(
      account: string,
      profile: string,
      environment: string,
      settingsFile?: string,
      settingsUrl?: string,
      logLevel?: LogLevel
    ): Tealium

    The following example passes all arguments:

    import { Tealium, Environment } from "@tealium/prism-react-native";

    const tealium = Tealium.create(
      "my_account",
      "my_profile",
      Environment.prod,
      "my_settings.json",
      "https://tags.tiqcdn.com/dle/my_account/my_profile/mobile_settings_prod.json",
      "debug"
    );

    The optional arguments configure the settings sources and logging:

    • settingsFile is the name of a JSON settings file bundled with the app. Include the .json extension. On iOS, add the file to your app target so that it ships in the main bundle. On Android, put the file in android/app/src/main/assets/. These local settings have the lowest priority.
    • settingsUrl is the URL of a remote JSON settings resource. Remote settings override local settings.
    • logLevel sets the log verbosity of the native SDK: trace, debug, info, warn, error, or silent. It overrides both settings sources.

    Important: If an instance already exists for the same account and profile, Tealium.create returns it and ignores environment, settingsFile, settingsUrl, and logLevel. To change the configuration, call await tealium.shutdown() on the existing instance first.

    To shut down an instance, call shutdown. Calls on a shut-down instance reject with an error:

    await tealium.shutdown();

    Call track with an event name, an optional type, and optional data. The type is "event" by default. Use "view" for screen views:

    // Track an event with the default type.
    await tealium.track("homepage");

    // Track an event with data.
    await tealium.track("user_login", "event", { customer_id: "1234567890" });

    // Track a view.
    await tealium.track("homepage", "view");

    The data must be a plain object with JSON-serializable values.

    track returns a Promise with a result. The result has a status of "accepted" or "dropped", an info string, and the dispatch payload:

    const result = await tealium.track("user_login");
    console.log(result.status, result.info, result.payload);

    The SDK queues tracked events and sends them according to your Tealium settings, for example in batches. Call flushEventQueue to send the queued events now. The Promise resolves when the SDK accepts the request, not when the events are sent. Some barriers still hold the events, such as the connectivity barrier while the device is offline. The flush still happens once those barriers open.

    await tealium.track("checkout_completed");

    // Send the queued events now instead of waiting for a full batch.
    await tealium.flushEventQueue();

    Read and write data layer values through tealium.dataLayer. Every method returns a Promise.

    To get a value, call get with the key. The Promise resolves with undefined if the key is absent:

    const customerId = await tealium.dataLayer.get("customer_id");

    To set a value, call put:

    await tealium.dataLayer.put("my_string", "my_string_value");

    To set several values in one call, pass a plain object to putAll:

    await tealium.dataLayer.putAll({
      customer_id: "12345",
      is_logged_in: true,
      consent_status: "consented",
      product_category: ["electronics", "headphones"],
    });

    Values must be JSON-serializable: strings, numbers, booleans, null, arrays, and plain objects.

    To set an expiration, pass an expiry as the last argument of put or putAll. The expiry is "session", "untilRestart", "forever", or a Date. Without an expiry, the value never expires:

    await tealium.dataLayer.put("currency", "USD", "untilRestart");

    const sevenDays = 7 * 24 * 60 * 60 * 1000;
    await tealium.dataLayer.put("order_total", 249.95, new Date(Date.now() + sevenDays));

    To get every value as one object, call getAll:

    const data = await tealium.dataLayer.getAll();

    To remove values, call remove with a key or an array of keys. To remove every value, call clear:

    await tealium.dataLayer.remove("customer_id");
    await tealium.dataLayer.remove(["is_logged_in", "consent_status"]);
    await tealium.dataLayer.clear();

    Set the log level with the sixth argument of Tealium.create. The available levels are "trace", "debug", "info", "warn", "error", and "silent". The level applies to the native Prism SDK.

    Pass undefined for the settings arguments that you do not use:

    const tealium = Tealium.create(
      "my_account",
      "my_profile",
      Environment.dev,
      undefined,
      undefined,
      "debug"
    );

    Join a trace to validate your data. The SDK adds the trace ID to every later dispatch. This continues until you leave the trace or the session expires. Your Tealium settings must configure the Trace module. Without it, these calls reject.

    // Join a trace.
    await tealium.trace.join("12345");

    // Track an event. The dispatch payload contains the trace ID.
    await tealium.track("trace_demo_event");

    // End the current visit. This call rejects if no trace is joined.
    const result = await tealium.trace.forceEndOfVisit();

    // Leave the trace.
    await tealium.trace.leave();

    The trace stays active after forceEndOfVisit until you call leave.

    Read and manage the visitor ID through tealium.visitorId. The VisitorId module is registered and enabled by default. If your Tealium settings disable it, every call rejects.

    // The visitor ID at the time of the call.
    const visitorId = await tealium.visitorId.current();

    // Generate a new anonymous visitor ID. An identity present in the data layer takes ownership of it.
    const regeneratedId = await tealium.visitorId.regenerate();

    // Erase every identity association stored on this device, then generate a new visitor ID.
    const newId = await tealium.visitorId.eraseLocalHistory();

    On logout, remove the identity key from the data layer before calling regenerate(). Calling it while the identity is still present rebinds that identity to the new ID. eraseLocalHistory() is device-only: it doesn't remove the identity from the data layer or change server-side visitor profiles.

    Configure visitor switching through the module's visitor_identity_key in your local/remote settings JSON.

    Tealium.create throws synchronously only if the native module is missing. All other failures reject the returned Promise. Methods that take data, such as track and dataLayer.put, serialize it to JSON. They reject if a value cannot be serialized, for example a BigInt or a circular reference. They silently drop object properties whose values are functions, symbols, or undefined. Methods that take an expiry reject if it is an invalid Date. These input errors are plain Error objects without a code. All other errors from the package and the native module carry a code property. Compare the code against ErrorCode:

    import { ErrorCode, type TealiumError } from "@tealium/prism-react-native";

    try {
      await tealium.track("checkout_started");
    } catch (error) {
      if ((error as TealiumError).code === ErrorCode.INSTANCE_SHUT_DOWN) {
        // Create a new instance before you track again.
      }
    }

    The error codes are:

    • DATA_PARSE_ERROR: A JSON string that crossed the bridge could not be parsed.
    • INSTANCE_NOT_FOUND: The native module has no instance for the given instance ID.
    • INSTANCE_SHUT_DOWN: The instance was shut down. Call Tealium.create to get a new instance.
    • NATIVE_MODULE_NOT_REGISTERED: The native module is not available in the running app. Rebuild the native app after installing the package.
    • PRISM_NATIVE_ERROR: The native Prism SDK reported a failure. The error message comes from the native SDK.
    • TEALIUM_CANCELLED: The native operation completed without producing a result.

    Jest tests run without the native SDKs, so they can't use this package directly. Importing it in a Jest test fails with SyntaxError: Cannot use import statement outside a module, because the package ships ES modules and the React Native Jest preset doesn't transform them.

    In Jest tests, mock the package with jest.mock. Mock only the parts that your code calls:

    import { Environment, Tealium } from "@tealium/prism-react-native";

    const mockTrack = jest.fn(() => Promise.resolve({ status: "accepted" }));

    jest.mock("@tealium/prism-react-native", () => ({
      Environment: { prod: "prod" },
      Tealium: {
        create: jest.fn(() => ({ track: mockTrack })),
      },
    }));

    test("tracks a login", async () => {
      const tealium = Tealium.create("my_account", "my_profile", Environment.prod);
      await tealium.track("user_login");
      expect(mockTrack).toHaveBeenCalledWith("user_login");
    });

    To run the package's JavaScript in Jest instead, for example to test how your app handles a missing native module, let Jest transform the package. Add it to the exceptions in transformIgnorePatterns in your Jest config:

    transformIgnorePatterns: [
      "node_modules/(?!((jest-)?react-native|@react-native(-community)?|@tealium/prism-react-native)/)",
    ],

    Jest has no native module, so Tealium.create then throws a TealiumError with the NATIVE_MODULE_NOT_REGISTERED code synchronously, and getSdkVersion rejects with the same code. You can't get an instance this way, so to test code that uses an instance, mock the package as shown above.

    The optional packages contain only native code, so they don't need mocks.

    To test tracking end to end, run the app on a simulator or a device.

    Read the API reference at tealium.github.io/tealium-prism-react-native.

    Commercial. See the license.

    Settings
    Member Visibility

    On This Page
    @tealium/prism-react-native
    • Tealium Prism React Native SDK Reference