Flutter SDK integration and tracking setup

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

Installation

https://pub.dev/packages/marfeel_sdk

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 */');

Simply replace the /* 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);

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

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));

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.

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);

Only integer values are accepted

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;
}

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

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,
);