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 */');
/* AccountId */ placeholder with your Marfeel Account ID.
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);
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 });
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);
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;
}
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);