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.11.0")
]
)
Cocoapods
Include the following line in your Podfile:
pod 'MarfeelSDK-iOS', '~> 2.11.0'
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>
/* 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
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>
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})
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})
Scroll Tracking
To track scroll depth, you can provide the UIScrollView to both the trackNewPage and trackScreen methods.
tracker.trackNewPage(url: {URL}, scrollView: {UIScrollView}})
tracker.trackScreen(name: {String}, scrollView: {UIScrollView}})
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))
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
// Returned rfv management
}
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}")
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 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()
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?
}
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.
