Installation
To configure your project, follow these steps:
Add the following repository to your settings.gradle file. Read more about declaring repositories:
maven {
url "https://repositories.mrf.io/nexus/repository/mvn-marfeel-public/"
}
Depending on your application’s use, include one of the following dependencies in your build.gradle within the dependencies section:
- If you are using Jetpack Compose
dependencies {
implementation ‘com.marfeel.compass:compose:1.16.6’
}
- If you are using XML views:
dependencies {
implementation ‘com.marfeel.compass:views:1.16.6’
}
Setup
To begin tracking pages, initialize the SDK using its initialize method and provide your unique Marfeel Account Id as follows:
CompassTracking.initialize(context: Context, /* AccountId */)
Page Technology
The default value for the Page Technology dimension is set to Android App , represented by the value 4 . However, you can modify this default value using the initialize method, which allows you to specify a different page technology as a parameter.
CompassTracking.initialize(context: Context, accountId: String, pageTechnology: Int)
Usage
All tracking features are made available through a CompassTracking instance:
val tracker = CompassTracking.getInstance()
Page Tracking
CompassTracker automatically monitors user time on a page. When a user begins reading a new page, you should provide the page’s canonical URL.
tracker.trackNewPage(url: String)
tracker.trackNewPage(url: String, recirculationSource: String?)
CompassTracker will continue tracking reading time until the trackNewPage method is called again with a different URL or until the developer explicitly invokes the stopTracking() method.
tracker.stopTracking()
tracker.startTracking() has been deprecated in favor of tracker.trackNewPage()
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.
tracker.trackScreen(screen: String)
tracker.trackScreen(screen: String, recirculationSource: String?)
Landing Page Tracking
If you’re interested in tracking the landing page of the current session, use the following method
tracker.setLandingPage(landingPage: String)
UTMs
If you want to include UTMs, you’ll need to add them to the landing page.
Scroll Tracking
To track scroll depth, you can provide a view that implements the ScrollingView interface, such as NestedScrollView, ScrollView, or RecyclerView, to both the trackNewPage and trackScreen methods.
tracker.trackNewPage(url: String, scrollView: ScrollingView, recirculationSource: String?)
tracker.trackNewPage(url: String, scrollView: ScrollView, recirculationSource: String?)
tracker.trackNewPage(url: String, scrollView: RecyclerView, recirculationSource: String?)
tracker.trackScreen(screen: String, scrollView: ScrollingView, recirculationSource: String?)
tracker.trackScreen(screen: String, scrollView: ScrollView, recirculationSource: String?)
tracker.trackScreen(screen: String, scrollView: RecyclerView, recirculationSource: String?)
When working with Jetpack Compose, you should use either trackNewPage(url: String) or trackNewScreen(screen: String) along with the composable function:
CompassScrollTrackerEffect(scrollState: ScrollState)
User Identification
To track a userId instead of the default Marfeel one you can use the method setSiteUserId.
setSiteUserId(userId: String)
tracker.setUserId() has been deprecated in favor of tracker.setSiteUserId()
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()
getUserId(): String
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.
- ANONYMOUS: for anonymous users
- LOGGED: for registered users
- PAID: for subscribers
- CUSTOM. For custom types you should provide a numeric identifier defined in the Marfeel User Journey UI
// kotlin syntax
tracker.setUserType(UserType.Anonymous)
tracker.setUserType(UserType.Logged)
tracker.setUserType(UserType.Paid)
tracker.setUserType(UserType.Custom(9))
// java syntax
tracker.setUserType(UserType.Anonymous.INSTANCE)
tracker.setUserType(UserType.Logged.INSTANCE)
tracker.setUserType(UserType.Paid.INSTANCE)
tracker.setUserType(new UserType.Custom(9))
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.
tracker.getRFV { rfv ->
// The rfv parameter is a JSON string containing the following fields:
// - rfv type:Float -> The combined RFV score
// - r type:Int -> Recency score
// - f type:Int -> Frequecny score
// - v type:Int -> Volume score
}
There’s also a synchronous version of this function available. It should be called from a separate thread.
Conversions tracking
You can track conversions calling the trackConversion(conversion: String) method:
tracker.trackConversion("subscription")
Conversion parameters
Just like in web, Conversion parameters are available for Native
tracker.trackConversion(
conversion = "{CONVERSION}",
options = ConversionOptions( // optional
id = "{ID}", // each pair {CONVERSION} and {ID} will only be tracked once
value = "{VALUE}",
meta = mapOf("key_1" to "val_1", "key_2" to "val_2"),
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:
tracker.trackConversion(
conversion = "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:
tracker.trackConversion(
conversion = "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:
tracker.setConsent(true)
User data will be deleted each time the user closes the app if no consent is provided.
Custom Dimensions
Page vars
tracker.setPageVar("name", "value")
Session vars
tracker.setSessionVar("name", "value")
User vars
tracker.setUserVar("name", "value")
User segments
Adds a new persistent user segment
tracker.addUserSegment("segment")
Replaces existing user segments
tracker.setUserSegments(listOf("segment1", "segment2"))
Removes existing user segment
tracker.removeUserSegment("segment")
Clears all user segments
tracker.clearUserSegments()
Custom Metrics
Page metrics
tracker.setPageMetric("metric", 1)
Multimedia tracking
All multimedia tracking features are made available through a MultimediaTracking instance:
val multimediaTracker = MultimediaTracking.getInstance()
Exposed interfaces
interface MultimediaTracking {
/**
* Registers multimedia item for tracking
* @param id The item identifier
* @param provider The multimedia provider
* @param providerId The multimedia provider identifier
* @param type The multimedia type
* @param metadata The multimedia metadata
*/
fun initializeItem(id: String, provider: String, providerId: String, type: Type, metadata: MultimediaMetadata)
/**
* Tracks an event for the item matching the provided id.
* @param id The item identifier
* @param event The event to track
* @param eventTime The time when the event has occurred
*/
fun registerEvent(id: String, event: Event, eventTime: Int)
companion object {
/**
*
* @return The singleton instance of the MultimediaTracking interface
*/
fun getInstance(): MultimediaTracking = MultimediaTracker
}
}
enum class Type(val id: String) {
AUDIO("audio"),
VIDEO("video")
}
enum class Event(val id: String) {
PLAY("play"),
PAUSE("pause"),
END("end"),
UPDATE_CURRENT_TIME("updateCurrentTime"),
AD_PLAY("adPlay"),
MUTE("mute"),
UNMUTE("unmute"),
FULL_SCREEN("fullscreen"),
BACK_SCREEN("backscreen"),
ENTER_VIEWPORT("enterViewport"),
LEAVE_VIEWPORT("leaveViewport")
}
data class MultimediaMetadata(
val isLive: Boolean? = false,
val title: String? = null,
val description: String? = null,
val url: String? = null,
val thumbnail: String? = null,
val authors: String? = null,
val publishTime: Long? = null,
val duration: Int? = null
)
To initialize a new media
multimediaTracker.initializeItem(
"videoId", // mandatory
"youtube", // mandatory
"abcaXala", // mandatory
Type.VIDEO, // mandatory
MultimediaMetadata(
false,
"video-title",
"video-description",
"http://url/to/video",
"http://url/to/thumbnail",
"John, Doe",
1683196435676, // timestamp
125 // time en seconds
)
)
To track a new event
multimediaTracker.registerEvent("videoId", Event.PAUSE, 25)