Skip to main content

​
Overview

The Nemu React Native SDK allows mobile applications developed in React Native to:
  • Capture UTMs received via deep links
  • Persist the user’s session origin
  • Associate a logged-in user’s UID with the session
  • Retrieve UTMs from the last session for event sending (e.g., sales)
The SDK is designed to work on Android and iOS, maintaining behavioral compatibility with Nemu’s native SDKs.

​
Requirements

  • React Native: 0.68 or higher
  • Node.js: 16 LTS

​
Android

  • minSdkVersion: 21 (Android 5.0)
  • targetSdkVersion: 34 (Android 14)

​
iOS

  • Deployment Target: 11.0+
The project must use Bare Workflow, containing the android/ and ios/ folders.
Projects in Expo Managed Workflow may require ejection or additional configurations.

​
Installation

​
1. Install the SDK

npm install @nemu/react-native-sdk
# or
yarn add @nemu/react-native-sdk
This step adds Nemu’s SDK to the React Native project.

​
2. iOS Installation

cd ios
pod install
cd ..
This command installs the native dependencies required for the SDK to work on iOS.

​
3. Android Installation

Add the dependency below in android/app/build.gradle: 
dependencies {
  implementation "com.android.installreferrer:installreferrer:2.2"
}

​
Credentials Configuration

To initialize the SDK, you will need:
  • Nemu PIXEL_ID
  • Nemu SDK_TOKEN
To obtain the PIXEL_ID and SDK_TOKEN, talk to your Nemu account manager.
For security, we recommend not hardcoding these credentials in the code.

​
Using environment variables (react-native-config)

  1. Install the dependency:
yarn add react-native-config
cd ios && pod install && cd ..
  1. Create a .env file at the project root:
NEMU_PIXEL_ID=<PIXEL_ID>
NEMU_SDK_TOKEN=<SDK_TOKEN>

​
SDK Initialization

The SDK should be initialized as early as possible, preferably in the root component of the application.

​
Example (App.tsx)

import React, { useEffect } from "react";
import { View, Text } from "react-native";
import Config from "react-native-config";
import { NemuTracking } from "@nemu/react-native-sdk";

export default function App() {
  useEffect(() => {
    NemuTracking.init({
      pixelId: Config.NEMU_PIXEL_ID,
      sdkToken: Config.NEMU_SDK_TOKEN,
      isDebugMode: true,
    });
  }, []);

  return (
    <View>
      <Text>My App</Text>
    </View>
  );
}
What this code does:
  • Connects the app to Nemu services
  • Activates debug logs for validation during development
  • Ensures UTMs captured via deep links are processed correctly

​
Registering User UID

Before starting the SDK installation and use in your application, you need to define what will be the UID (Unique Identifier) per user to be used. This identifier is defined by the team that will perform the integration. This identifier will be used to link web accesses with the app and vice versa, making tracking extremely precise and efficient. The UID must be a unique value per user in your application. We normally recommend using values already common and existing in your database as identifiers, with the most common option being the user’s email. After the user logs in to the app, register the user’s identifier in the SDK.
All user identifiers registered by the SDK are handled securely.

​
Example after login

import { NemuTracking } from "@nemu/react-native-sdk";

async function signIn(email: string, password: string) {
  const user = await authApi.login({ email, password });

  NemuTracking.setUserId(user.id);
}

​
Already logged-in users

If the app loads an already authenticated session, register the UID as soon as the user is available: 
import { NemuTracking } from "@nemu/react-native-sdk";

async function bootstrapSession() {
  const user = await sessionManager.loadUser();

  if (user?.id) {
    NemuTracking.setUserId(user.id);
  }
}

​
App Install Attribution

Install attribution allows identifying the user’s origin on first app access, even when there is no direct deep link at the moment of opening. Nemu’s SDK automatically collects origin information provided by the app store (Google Play or App Store) to associate the installation with a valid traffic source.

​
When install attribution is used

Install attribution occurs when:
  • The user installs the app for the first time
  • There is no active deep link at the moment of app opening
  • The origin is available through store mechanisms
This process ensures that users acquired through media campaigns are correctly attributed, even without direct interaction with a link at the first access.
Install attribution is applied only on the first app opening after installation.

​
What is attributed at installation

When available, the SDK associates the initial session with information such as:
  • Traffic source (utm_source)
  • Medium (utm_campaign)
  • Campaign (utm_campaign)
  • Other origin parameters provided by the platform
This data becomes the user’s initial origin and can be normally retrieved through the getLastSessionHistory() method. After installing and opening the app, the origin attributed to the installation will be automatically available for use in events and sales.
Deferred Deep Links allow the origin of a click to be preserved even when the user:
  1. Clicks on a link with UTMs that leads to the site
  2. Does not have the app installed yet
  3. Installs the app
  4. Opens the app for the first time
In this scenario, Nemu’s SDK retrieves the UTMs associated with the original click and applies them to the user’s first session. Deferred deep links are used when:
  • The app is installed after clicking on a link with UTMs
  • The app is opened for the first time after installation
  • There is no active deep link at the moment of opening
This behavior ensures that the user’s correct origin is maintained even in indirect installation flows.

​
Complete flow example

  1. User clicks on a campaign link:
https://mywebsite.com?utm_source=nemu&utm_medium=cpc&utm_campaign=campaign-test
  1. User is redirected to the app store (Play Store or App Store)
  2. User installs the app
  3. User opens the app for the first time
  4. SDK automatically retrieves UTMs from the original click
  5. The initial session now contains these UTMs
UTMs recovered via deferred deep link should be used in the same way as UTMs captured via direct deep links.

​
Expected behavior

  • Deferred deep links are applied only on the first session after installation
  • On subsequent accesses, new origins can overwrite the session if there are new deep links
  • If there is no attributable origin, the session can be recorded without UTMs
The Nemu React Native SDK already automatically consumes the React Native Linking API to capture:
  • The URL that opened the app
  • URLs received while the app is already running
No additional JavaScript code is needed to handle deep links. For this to work, native app configuration is required, as the SDK does not register deep links in the operating system.

​
What the SDK does

  • Captures URLs via Linking
  • Extracts UTMs and nemu_* parameters
  • Persists the session origin
  • Associates events sent with the captured origin

​
What needs to be configured in the app

​
Android

Configure an intent-filter in AndroidManifest.xml for the domain or scheme used by the app. 
<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="app.yourdomain.com" />
</intent-filter>

​
iOS

Configure Universal Links (Associated Domains) for the domain used by the app. 
applinks:app.yourdomain.com
The apple-app-site-association file must be available on the configured domain.

​
Retrieving UTMs from the last session

The getLastSessionHistory() method returns the UTMs from the last attributable user’s session.

​
Usage example

import { NemuTracking } from "@nemu/react-native-sdk";

async function getUtms() {
  const session = await NemuTracking.getLastSessionHistory();

  console.log("utm_source:", session?.utmSource);
  console.log("utm_medium:", session?.utmMedium);
  console.log("utm_campaign:", session?.utmCampaign);
  console.log("utm_content:", session?.utmContent);
  console.log("utm_term:", session?.utmTerm);
}

​
Sending custom events

In addition to automatic session and UTM capture, Nemu’s SDK allows the application to trigger custom events to map important user actions within the app. Initially, events are sent only with the event name, without additional properties.
Even so, all events are automatically associated with the session, UTMs, and user’s UID (when available).

​
sendEvent method

Event sending is done through the sendEvent method, informing only the event name. 
NemuTracking.sendEvent(eventName);
Below are examples of classic events used in funnel analysis, user journey, and campaign attribution.

​
Page View (screen view)

Fire whenever the user accesses a relevant screen in the app. 
import { NemuTracking } from "@nemu/react-native-sdk";

NemuTracking.sendEvent("page_view");
Screen examples:
  • Home
  • Category
  • Product
  • Checkout

​
View Item (product view)

Used when the user views a product screen. 
NemuTracking.sendEvent("view_item");

​
Add to Cart

Fire when the user adds an item to the cart. 
NemuTracking.sendEvent("add_to_cart");

​
Remove from Cart

NemuTracking.sendEvent("remove_from_cart");

​
Begin Checkout

Indicates that the user started the purchase process. 
NemuTracking.sendEvent("begin_checkout");

​
Best practices for events

We recommend using event names in snake_case, following known market standards (e.g., GA4).

​
Important recommendations

  • Fire events only after the SDK is initialized
  • Whenever possible, fire events after the UID is registered
  • Use consistent and standardized event names
  • Avoid creating multiple names for the same behavior

​
Automatic association with UTMs

All events sent via sendEvent are automatically associated by the SDK with:
  • Last attributable user’s session
  • UTMs captured (deep link, deferred deep link, or installation)
  • User’s UID (when registered)
This association occurs transparently, without needing to manually send UTMs along with events.
After implementation, events become part of the user’s journey in Nemu, allowing more complete behavior and attribution analysis, even without additional properties in the events.

​
Sending sale with UTMs

Use the UTMs returned by the SDK when sending sale events to Nemu’s API. 
import { NemuTracking } from "@nemu/react-native-sdk";

async function buildPurchasePayload() {
  const session = await NemuTracking.getLastSessionHistory();

  return {
    transactionId: "123",
    netValue: 99.9,
    status: "paid",
    utm_source: session?.utmSource ?? null,
    utm_medium: session?.utmMedium ?? null,
    utm_campaign: session?.utmCampaign ?? null,
    utm_content: session?.utmContent ?? null,
    utm_term: session?.utmTerm ?? null,
  };
}
UTMs must be sent exactly as returned by the SDK.

​
Testing the integration

​
1. Enable debug mode

NemuTracking.init({
  pixelId: Config.NEMU_PIXEL_ID,
  sdkToken: Config.NEMU_SDK_TOKEN,
  isDebugMode: true,
});
  1. Install the clean app
  2. Open the app via deep link with UTMs
  3. Check capture logs
  4. Log in and register the UID
  5. Retrieve UTMs with getLastSessionHistory()
  6. Send a sale containing these UTMs

​
3. Expected logs

[DEBUG] [NemuTracking] Application successfully initialized
[DEBUG] [NemuTracking] Deep link captured with UTMs
[DEBUG] [NemuTracking] UID registered successfully
[DEBUG] [NemuTracking] Last session history retrieved

​
SDK API

type NemuInitParams = {
  pixelId: string;
  sdkToken: string;
  isDebugMode?: boolean;
};

type SessionHistory = {
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  utmContent?: string;
  utmTerm?: string;
};

export const NemuTracking: {
  init(params: NemuInitParams): void;
  setUserId(userId: string): void;
  getLastSessionHistory(): Promise<SessionHistory | null>;
  captureDeepLink(url: string): void;
  sendEvent(eventName: string): Promise<void>;
};

​
Conclusion

After following all the steps above, Nemu’s React Native SDK will be correctly integrated with your application.