React Native SDK setup, tracking, and API reference

We also offer a sample playground application to demonstrate how our SDK can be used. You can access the GitHub repository here: React Native Example Application

Installation

Install the package from npm:

npm install @marfeel/react-native-sdk

Android setup

Add the following repository to your app-level android/build.gradle file:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://repositories.mrf.io/nexus/repository/mvn-marfeel-public/"
        }
    }
}

iOS setup

Install the CocoaPods dependencies:

cd ios && pod install

No additional configuration is required. The native SDK is installed automatically via CocoaPods.

Setup

To begin tracking, initialize the SDK using the initialize method and provide your unique Marfeel Account Id:

import { CompassTracking } from '@marfeel/react-native-sdk';

CompassTracking.initialize('/* AccountId */');

Simply replace the /* AccountId */ placeholder with your Marfeel Account ID.

All SDK initialization calls (initialize, setLandingPage, trackScreen) must happen in the same top-level useEffect. Child component effects fire before parent effects in React Native, so spreading these calls across components may cause them to execute before initialization completes.

import React, { useEffect } from 'react';
import { CompassTracking } from '@marfeel/react-native-sdk';

export default function App() {
  useEffect(() => {
    CompassTracking.initialize('/* AccountId */');
    CompassTracking.setLandingPage('https://example.com/');
    CompassTracking.trackScreen('home');
  }, []);

  return (/* your app */);
}

Page Technology

The default value for the Page Technology dimension depends on the underlying platform (iOS App or Android App). However, you can modify this default value using the pageTechnology parameter:

CompassTracking.initialize('/* AccountId */', 105);

Custom Page Technologies have IDs above 100 and must be declared on the Organization Settings

Usage

To utilize the library, import the CompassTracking class from the package.

import { CompassTracking } from '@marfeel/react-native-sdk';

All tracking features are available as static methods on the CompassTracking object.

Page Tracking

CompassTracking automatically monitors user time on a page. When a user begins reading a new page, you should provide the page’s canonical URL.

CompassTracking.trackNewPage('https://example.com/article');
CompassTracking.trackNewPage('https://example.com/article', { rs: 'homepage' });

In cases where you can’t provide the canonical URL you can use the Editorial Metadata API.

CompassTracking will continue tracking reading time until the trackNewPage method is called again with a different URL or until you explicitly invoke the stopTracking() method.

CompassTracking.stopTracking();

If you want to track a screen instead of a new page, particularly when your view doesn’t have a real URI, you can utilize the trackScreen method. This method accepts a raw name instead of an actual URI for tracking purposes.

CompassTracking.trackScreen('profile');
CompassTracking.trackScreen('profile', { rs: 'menu' });

Landing Page Tracking

If you want to inform about the landing page of the session, use the following method:

CompassTracking.setLandingPage('https://example.com/');

UTMs

If you want to include UTMs, you’ll need to add them to the landing page.

Scroll Tracking

The SDK provides CompassScrollView, a component that wraps React Native’s ScrollView and automatically tracks scroll depth:

import { CompassScrollView } from '@marfeel/react-native-sdk';

<CompassScrollView>
  {/* Your scrollable content */}
</CompassScrollView>

CompassScrollView supports the same props as ScrollView, and can also wrap FlatList or SectionList using the as prop:

<CompassScrollView
  padding={16}
  showsVerticalScrollIndicator={false}
>
  {/* Your scrollable content */}
</CompassScrollView>

import { FlatList } from 'react-native';

<CompassScrollView as={FlatList} data={items} renderItem={renderItem} />

import { SectionList } from 'react-native';

<CompassScrollView as={SectionList} sections={sections} renderItem={renderItem} />

You can also report scroll percentage manually:

CompassTracking.updateScrollPercentage(75);

User Identification

To associate the app user to the records generated by the library, use the setSiteUserId method, indicating the user ID in your platform.

CompassTracking.setSiteUserId('user_123');

On the other hand, if you need to retrieve marfeel user id for forwarding it to one of our apis, the method you need to use is getUserId()

const userId = await CompassTracking.getUserId();

User Journey

You can specify the type of user with the options below. By default, if not specified, the user will be tracked as Anonymous.

import { CompassTracking, UserType } from '@marfeel/react-native-sdk';

CompassTracking.setUserType(UserType.Anonymous);
CompassTracking.setUserType(UserType.Logged);
CompassTracking.setUserType(UserType.Paid);
CompassTracking.setUserType({ custom: 8 });

TIP:
It's recommended to first provide the user ID and the user journey information before initiating the tracking of the first pageview.

User RFV

If you want to access the RFV of the user within a session, you can retrieve it using the getRFV method.

const rfv = await CompassTracking.getRFV();
if (rfv) {
  // RFV object containing:
  // - rfv (number): The composite RFV score representing overall user engagement.
  // - r (number): Recency — how recently the user has visited.
  // - f (number): Frequency — how often the user visits.
  // - v (number): Volume — how much content the user consumes.
}

Conversion Tracking

You can track conversions calling the trackConversion() method:

CompassTracking.trackConversion('subscription');

Conversion parameters

Just like in web, Conversion parameters are available for Native

import { ConversionScope } from '@marfeel/react-native-sdk';

CompassTracking.trackConversion('purchase', {
  id: 'order_123',       // each pair {CONVERSION} and {ID} will only be tracked once
  value: '29.99',
  meta: { currency: 'EUR', plan: 'annual' },
  scope: ConversionScope.Page,  // Page | Session | User
});

Keep in mind that trackConversion with the same conversion and options.id will only be tracked once.

In the following example, if you send the first call:

CompassTracking.trackConversion('conv_1', {
  id: 'id_1',
  value: '3',
});

A second call won’t be tracked because conv_1:id_1 has already been tracked:

CompassTracking.trackConversion('conv_1', {
  id: 'id_1',
  value: '4',
});

Consent Tracking

In order to mark if the current visit has consent approved or not, sdk offers the following method to use:

CompassTracking.setConsent(true);

User data will be deleted each time the user closes the app if no consent is provided.

Custom Dimensions

Page vars

CompassTracking.setPageVar('category', 'technology');

Session vars

CompassTracking.setSessionVar('theme', 'dark');

User vars

CompassTracking.setUserVar('preferredLanguage', 'en');

User segments

Adds a new persistent user segment

CompassTracking.addUserSegment('premium');

Replaces existing user segments

CompassTracking.setUserSegments(['premium', 'newsletter']);

Removes existing user segment

CompassTracking.removeUserSegment('newsletter');

Clears all user segments

CompassTracking.clearUserSegments();

Custom Metrics

Page metrics

CompassTracking.setPageMetric('wordCount', 1200);

Only integer values are accepted

Multimedia Tracking

All multimedia tracking features are available as static methods on the MultimediaTracking object.

import { MultimediaTracking } from '@marfeel/react-native-sdk';

Exposed interfaces

import { MultimediaType, MultimediaEvent } from '@marfeel/react-native-sdk';
import type { MultimediaMetadata } from '@marfeel/react-native-sdk';

enum MultimediaType {
  Audio = 'audio',
  Video = 'video',
}

enum MultimediaEvent {
  Play = 'play',
  Pause = 'pause',
  End = 'end',
  UpdateCurrentTime = 'updateCurrentTime',
  AdPlay = 'adPlay',
  Mute = 'mute',
  Unmute = 'unmute',
  FullScreen = 'fullscreen',
  BackScreen = 'backscreen',
  EnterViewport = 'enterViewport',
  LeaveViewport = 'leaveViewport',
}

interface MultimediaMetadata {
  isLive?: boolean;
  title?: string;
  description?: string;
  url?: string;
  thumbnail?: string;
  authors?: string;
  publishTime?: number;
  duration?: number;
}

Note:
For the full list of available events (MultimediaEvent) and media types (MultimediaType), refer to the Multimedia tracking documentation.

To initialize a new media

import { MultimediaTracking, MultimediaType } from '@marfeel/react-native-sdk';

MultimediaTracking.initializeItem(
  'videoId',              // id (mandatory)
  'youtube',              // provider (mandatory)
  'youtube-video-id',     // providerId (mandatory)
  MultimediaType.Video,   // type (mandatory)
  {                       // metadata (optional)
    title: 'Video Title',
    description: 'Video description',
    url: 'https://youtube.com/watch?v=youtube-video-id',
    authors: 'John Doe',
    duration: 420,
  }
);

To track a new event

import { MultimediaTracking, MultimediaEvent } from '@marfeel/react-native-sdk';

MultimediaTracking.registerEvent('videoId', MultimediaEvent.UpdateCurrentTime, 150);