Installation
Add the marfeel_sdk package to your pubspec.yaml:
dependencies:
marfeel_sdk: ^0.1.0
Then run:
flutter pub get
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
No additional setup 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 'package:marfeel_sdk/marfeel_sdk.dart';
CompassTracking.initialize('/* AccountId */');
/* AccountId */ placeholder with your Marfeel Account ID.
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 */', pageTechnology: 105);
Usage
To utilize the library, import the marfeel_sdk package.
import 'package:marfeel_sdk/marfeel_sdk.dart';
All tracking features are available as static methods on the CompassTracking class.
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 widget that wraps SingleChildScrollView and automatically tracks scroll depth:
CompassScrollView(
child: Column(
children: [
// Your scrollable content
],
),
)
CompassScrollView supports the same properties as SingleChildScrollView:
CompassScrollView(
controller: myScrollController,
padding: EdgeInsets.all(16),
physics: BouncingScrollPhysics(),
scrollDirection: Axis.vertical,
child: Column(
children: [
// Your scrollable content
],
),
)
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()
final 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.
CompassTracking.setUserType(UserType.anonymous);
CompassTracking.setUserType(UserType.logged);
CompassTracking.setUserType(UserType.paid);
CompassTracking.setUserType(UserType.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.
final rfv = await CompassTracking.getRFV();
if (rfv != null) {
// RFV object containing:
// - rfv (double): The composite RFV score representing overall user engagement.
// - r (double): Recency — how recently the user has visited.
// - f (double): Frequency — how often the user visits.
// - v (double): 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
CompassTracking.trackConversion(
'purchase',
options: ConversionOptions(
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',
options: ConversionOptions(
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',
options: ConversionOptions(
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 class.
Exposed interfaces
class MultimediaTracking {
static void initializeItem({
required String id,
required String provider,
required String providerId,
required MultimediaType type,
MultimediaMetadata? metadata,
});
static void registerEvent({
required String id,
required MultimediaEvent event,
required int eventTime,
});
}
enum MultimediaType {
audio,
video,
}
enum MultimediaEvent {
play,
pause,
end,
updateCurrentTime,
adPlay,
mute,
unmute,
fullScreen,
backScreen,
enterViewport,
leaveViewport,
}
class MultimediaMetadata {
final bool? isLive;
final String? title;
final String? description;
final String? url;
final String? thumbnail;
final String? authors;
final int? publishTime;
final int? duration;
}
To initialize a new media
MultimediaTracking.initializeItem(
id: 'videoId',
provider: 'youtube',
providerId: 'youtube-video-id',
type: MultimediaType.video,
metadata: MultimediaMetadata(
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
MultimediaTracking.registerEvent(
id: 'videoId',
event: MultimediaEvent.updateCurrentTime,
eventTime: 150,
);