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:
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.createreturns it and ignoresenvironment,settingsFile,settingsUrl, andlogLevel. To change the configuration, callawait 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.
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.Read the API reference at tealium.github.io/tealium-prism-react-native.
Commercial. See the license.