Native iOS SDK instrumentation and tracking guide

Installation

The Marfeel SDK installation can be done via Swift Package Manager (SPM) or via Cocoapods.

Swift Package Manager

If you’re using XCode, Swift Package Manager (SPM) is part of it since version 11. Follow the official documentation using https://github.com/Marfeel/MarfeelSDK-iOS as the package repository.

If you’re using a Package.swift manifest file, include MarfeelSDK as one of your project dependencies:

import PackageDescription

let package = Package(
    name: "Sample",
    dependencies: [
        .Package(url: "https://github.com/Marfeel/MarfeelSDK-iOS", from: "2.18.8")
    ]
)

Cocoapods

Include the following line in your Podfile:

pod 'MarfeelSDK-iOS', '~> 2.18.8'

Setup

To use the library, we offer two diffrent options for defining the configuration.

Using Info.plist

add the following properties within the Info.plist file ensuring your unique account ID is correctly added before /* AccountId */:

<key>COMPASS_ACCOUNT_ID</key>
<integer>/* AccountId */</integer>
<key>COMPASS_ENDPOINT</key>
<string>https://events.newsroom.bi/</string>

Simply update the /* AccountId */ placeholder with your Marfeel Account ID, and keep the rest of the code unchanged.

Using CompassTracker static method

Call before any tracking the initialize method

func intialize(accountId: Int, pageTechnology: Int?, endpoint: String?)

For instance

import MarfeelSDK_iOS

CompassTracker.initialize([accountId: 0](https://hub.marfeel.com/compass/dashboard?accountId=0))  // just configuring accountId

// or

CompassTracker.initialize([accountId: 0](https://hub.marfeel.com/compass/dashboard?accountId=0), pageTechnology: 12345)  // use it instead if you want to use a custom page technology

We also offer a sample playground application to demonstrate how our SDKs can be used. You can access the GitHub repositories here: iOS Playground Application

Page Technology

The default value for the Page Technology dimension is set to iOS App represented by the value 3 . However, you can modify this default value adding the following property to Info.plist file:

<key>COMPASS_PAGE_TYPE</key>
<integer>$$COMPASS_PAGE_TYPE_VALUE_TO_BE_REPLACED$$</integer>

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

Usage

To utilize the library, import the MarfeelSDK_iOS module.

import MarfeelSDK_iOS

All tracking features are made available through a CompassTracking class. To access CompassTracker, use the shared variable from any part of the application

let tracker = CompassTracker.shared

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: {URL})
tracker.trackNewPage(url: {URL}, rs: {String?})

In cases where you can’t provide the canonical URL you can use the Editorial Metadata API.

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.startPageView() 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(name: {String})
tracker.trackScreen(name: {String}, rs: {String?})

Landing Page Tracking

If you want to inform about the landing page of the session, tracker provides for you the following method

tracker.setLandingPage(landingPage: {String})
tracker.setLandingPage(landingPage: {URL})

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 the UIScrollView to both the trackNewPage and trackScreen methods.

tracker.trackNewPage(url: {URL}, scrollView: {UIScrollView}, rs: {String?})

tracker.trackScreen(name: {String}, scrollView: {UIScrollView}, rs: {String?})

User identification

To associate the app user to the records generated by the library, use the method serUserId, indicating the user ID in your platform.

tracker.setSiteUserId({USER_ID})

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

tracker.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.

tracker.setUserType(.logged)
tracker.setUserType(.paid)
tracker.setUserType(.unknown)
tracker.setUserType(.anonymous)
tracker.setUserType(.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.

tracker.getRFV { rfv in
   // Rfv` struct containing:
   //  - `rfv` (`Float`): The composite RFV score representing overall user engagement.
   //  - `r` (`Int`): Recency — how recently the user has visited.
   //  - `f` (`Int`): Frequency — how often the user visits.
   //  - `v` (`Int`): Volume — how much content the user consumes.
}

Conversion tracking

You can track conversions calling the trackConversion() method:

tracker.trackConversion(conversion: "{CONVERSION}")

tracker.track(conversion: "{CONVERSION}") has been deprecated in favor of tracker.trackConversion(conversion: "{CONVERSION}")

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: ["key_1": "val_1", "key_2": "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: "name",  value: "value")

Session vars

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

User vars

tracker.setUserVar(name: "name", value: "value")

User segments

Adds a new persistent user segment

tracker.addUserSegment("segment")

Replaces existing user segments

tracker.setUserSegments(["segment1", "segment2"])

Removes existing user segment

tracker.removeUserSegment("segment")

Clears all user segments

tracker.clearUserSegments()

Custom metrics

Page metrics

tracker.setPageMetric(name: "name",  value: 123)

Only integer values are accepted

Multimedia Tracking

All multimedia tracking features are made available through a MultimediaTracking instance. To access MultimediaTracker, use the shared variable in any part of the application

let multimediaTracker =  CompassTrackerMultimedia.shared

Exposed interfaces

public protocol MultimediaTracking {
    func initializeItem(id: String, provider: String, providerId: String, type: Type, metadata: MultimediaMetadata)
    func registerEvent(id: String, event: Event, eventTime: Int)
}

public enum Event: String, Codable {
    case PLAY = "play"
    case PAUSE = "pause"
    case END = "end"
    case UPDATE_CURRENT_TIME = "updateCurrentTime"
    case AD_PLAY = "adPlay"
    case MUTE = "mute"
    case UNMUTE = "unmute"
    case FULL_SCREEN = "fullscreen"
    case BACK_SCREEN = "backscreen"
    case ENTER_VIEWPORT = "enterViewport"
    case LEAVE_VIEWPORT = "leaveViewport"
}

public enum Type: String, Codable {
    case VIDEO = "video"
    case AUDIO = "audio"
}

public struct MultimediaMetadata: Codable {
    var isLive = false
    var title: String?
    var description: String?
    var url: String?
    var thumbnail: String?
    var authors: String?
    var publishTime: Int64?
    var duration: Int?
}

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

To initialize a new media

CompassTrackerMultimedia.shared.initializeItem(
    id:"videoId",
    provider: "youtube",
    providerId: "youtube-video-id",
    type: .VIDEO,
    metadata: MultimediaMetadata.init(
        title: "title",
        description: "description",
        url: URL(string: "https://youtube.com/watch?v=youtube-vide-id"),
        authors: "authors",
        duration: 420
    )
)

To track a new event

CompassTrackerMultimedia.shared.registerEvent(id: "videoId", event: .UPDATE_CURRENT_TIME, eventTime: 150))

Privacy

Marfeel sdk is compliant with new Apple privacy policies, listing in the PrivacyInfo.xcprivacy how the tracker interacts with user data. Starting on May 1st 2024, all new apps or updates are required to list how the app interacts with user data, including third party sdks.