Android SDK native application instrumentation

The Android SDK for Marfeel allows tracking among others:

Setup

Add the following repository to your configuration(settings.gradle), for more info Declaring repositories

maven {
  url https://repositories.mrf.io/nexus/repository/mvn-marfeel-public/
}

and then add the following dependency in your build.gradle (dependencies section) if you’re using Jetpack Compose

dependencies {
  implementation ‘com.marfeel.compass:compose:1.4.1’
}

or include the following one if you’re using xml views

dependencies {
  implementation ‘com.marfeel.compass:views:1.4.1’
}

Initialization

Before starting to track pages the SDK needs to be initialized via it initialize method:

CompassTracking.initialize(context: Context, accountId: String)

The accountId parameter belong to your Marfeel organization account and can be found also on the Tracking code section.

Usage

All tracking features are made available through a CompassTracking instance:

val tracker = CompassTracking.getInstance()

Tracking pageviews

CompassTracker automatically tracks the time on page of a user. When a user starts reading a new page you must provide its url:

tracker.trackNewPage(url: String)

CompassTracker will track the reading time until the trackNewPage method is invoked again with a different url or if the the stopTracking() method is invoked explicitly by the developer.

tracker.stopTracking()
tracker.startTracking() has been deprecated in favor of tracker.trackNewPage()

Scroll depth control

If you want to track the scroll depth you can provide a view implementingScrollingView interface, like NestedScrollView, a ScrollView or a RecyclerView to trackNewPage method.​

tracker.trackNewPage(url: String, scrollView: ScrollingView)
tracker.trackNewPage(url: String, scrollView: ScrollView)
tracker.trackNewPage(url: String, scrollView: RecyclerView)

In case of using Jetpack Compose you must use startTracking(url: String) along with the composable function:

CompassScrollTrackerEffect(scrollState: ScrollState)

User Id

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

User Journey

You can provide the type of a user:

  • ANONYMOUS: for anonymous users
  • LOGGED: for registered users
  • PAID: for subscribers
  • CUSTOM. For custom types you must provide a numeric identifier declared on the Marfeel User Journey UI
tracker.setUserType(UserType.Anonymous)
tracker.setUserType(UserType.Logged)
tracker.setUserType(UserType.Paid)
tracker.setUserType(UserType.Custom(9))
TIP:
It's recommended that you first provide the user Id and the user journey before tracking the first pageview.​

Accessing RFV of user in session

If you want to use the RFV of the user in session you can get it through the getRFV method:

tracker.getRFV { rfv ->
    // callback
}

There’s a synchronous version of this fucntion. It should be called from a different thread.

Conversions tracking

You can track conversions calling the trackConversion(conversion: String) method:

tracker.trackConversion("subscription")

User page information

tracker.setPageVar("name", "value")

User session information

tracker.setSessionVar("name", "value")

User information

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 page technology

Overrides default page technology. By default, Android will be used for categorizing your tracking.

tracker.setPageType(101)
Only values greater than 100 are allowed for using as custom page technology.

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",
    "youtube",
    "abcaXala",
    Type.VIDEO,
    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)