This document describes the steps to be followed to integrate FirstHive Analytics SDK in your iOS application

─

Prerequisite

A ‘site ID’ need to be created for your APP in your FirstHive account to map the tracking to your account. Contact your FirstHive rep for the Site ID if not already provided

Steps to Integrate FirstHive iOS SDK

Installation

CocoaPods

Use the following in your Podfile.

pod 'MatomoTracker', '~> 6'

Then run pod install. In every file you want to use the FH Tracker (FirstHive iOS SDK Class), don’t forget to import the framework with import MatomoTracker.

Carthage

Carthage is a non-intrusive way to install FH Tracker to your project. It makes no changes to your Xcode project and workspace. 

Add the following to your Cartfile:

github "matomo-org/matomo-sdk-ios"

Usage

FirstHive Tracking Instance

The FirstHive iOS SDK doesn’t provide an instance of the FirstHive Tracker. In order to be able to track data, you have to create an instance first:

let matomoTracker = MatomoTracker(siteId: "<Site-Id>", baseURL: URL(string: "https://www.firsthive.com/engage/piwik/piwik.php")!)

You can either pass around this instance or add an extension to the MatomoTracker class and add a shared instance property.

static let shared: MatomoTracker = MatomoTracker(siteId: "<Site-Id>", baseURL: URL(string: "https://www.firsthive.com/engage/piwik/piwik.php")!)}

Opting Out

The FirstHive IOS app tracking SDK supports opting out of tracking. Please use the isOptedOut property of the MatomoTracker to define if the user opted out of tracking.

matomoTracker.isOptedOut = true

Tracking Page Views

The FirstHive IOS app tracking can track hierarchical screen names, e.g. screen/settings/register. Use this to create a hierarchical and logical grouping of screen views in the Matomo web interface.

matomoTracker.track(view: ["path","to","your","page"])

You can also set the url of the page.

let url = URL(string: "https://<your website/page>.com/") matomoTracker.track(view: ["community","get-involved"], url: url)

Events (Recommended)

Tracking Events is a very useful way to measure interactions your users make with your app content. Typically events are used to track clicks on elements in your screen such as the menu, widgets, Flash elements, AJAX actions, or even actions within games or media content.

Anatomy of FH Events

An Event has four components. These values will be tracked and displayed in your Site/App Analytics reports accordingly:

• Category
• Event Action
• Event Name
• Property (optional)

Refer to Miscellaneous section 6,  for the  full list of standard events supported by FirstHive 

Event Category: Category of an event

For example, “Viewed” is an event Category for all “Viewed” related events.

Event Action: Action that user may perform under a category like “CategoryViewed”, “ProductViewed” etc. for the category “Viewed” 

Event Name: To differentiate your event action, you can give a name to that action

For example, for category LoginOps you have action SignUp but say you want to track separate actions performed by the user under the signup process 

for eg., you want to track users starting registration and users completing registration as two separate events then, in that case, you can tag or name that event action as Registeration_start and Registration_Complete in the event code for those actions of the user.

Event Properties/dimension (dimension6 to dimension10): Events have details that describe the action taking place called properties.

For example, while recording the “Product viewed” event, you could also store event properties like product name, category, and price. Recording event properties will help you answer questions like which category of products are more popular and help you segment users based on which categories or price points they’ve viewed.

Example:

Sample event:

This will log that the user slide the volume slider on the player to 35.1%.

matomoTracker.track(eventWithCategory: “player”, action: “slide”, name: “volume”, value: 35.1)

Custom Dimension

The FirstHive IOS app tracking SDK currently supports Custom Dimensions for the Visit Scope. Using Custom Dimensions you can add properties to the whole visit, such as “Did the user finish the tutorial?”, “Is the user a paying user?” or “Which version of the Application is being used?” and such. Before sending custom dimensions. You will need the ID of your configured Dimension.

After that you can set a new Dimension,

matomoTracker.set(value: “ProductSKU001”, forIndex: 6)

matomoTracker.set(value: “ProductName”, forIndex: 7)

Dimensions in the Visit Scope will be sent along every Page View or Event. Custom Dimensions are not persisted by the SDK and have to be re-configured upon application startup.

Reserved Dimension:

matomoTracker.set(value: “<Email>", forIndex: 1)

matomoTracker.set(value: "<Mobile>", forIndex: 2)

matomoTracker.set(value: "<Name>", forIndex: 3)

matomoTracker.set(value: "<ID_1>", forIndex: 4)

matomoTracker.set(value: "<ID_2>", forIndex: 5)

Custom User ID (optional)

To add a custom User ID, simply set the value you’d like to use on the userId field of the tracker:

matomoTracker.userId = "coolUsername123"

All future events being tracked by the SDK will be associated with this userID, as opposed to the default UUID created for each Visitor.

Campaign Tracking (optional)

The FirstHive IOS app tracking SDK supports campaign tracking.

matomoTracker.trackCampaign(name: @“campaign_name”, keyword: @“campaign_keyword”)

Content Tracking (optional)

The FirstHive IOS app tracking SDK supports content tracking.

matomoTracker.trackContentImpression(name: "preview-liveaboard", piece: "Malaysia", target: "https://dummy.test.org/liveaboard/malaysia")

matomoTracker.trackContentInteraction(name: "preview-liveaboard", interaction: "tap", piece: "Malaysia", target: "https://dummy.test.org/liveaboard/malaysia")

Goal Tracking (optional)

The FirstHive IOS app tracking SDK supports goal tracking.

matomoTracker.trackGoal(id: 1, revenue: 99.99)

Order Tracking (optional)

The FirstHive IOS app tracking SDK supports order tracking.

let items = [

  OrderItem(sku: "product_sku_1", name: "iPhone Xs", category: "phone", price: 999.99, quantity: 1),

  OrderItem(sku: "product_sku_2", name: "iPhone Xs Max", category: "phone", price: 1199.99, quantity: 1)

]

matomoTracker.trackOrder(id: "order_id_1234", items: items, revenue: 2199.98, subTotal: 2000, tax: 190.98, shippingCost: 9)

Advance Usage

Session Management (optional)

The FirstHive IOS app tracking SDK starts a new session whenever the application starts. If you want to start a new session manually, you can use the startNewSession() function. You can, for example, start a new session whenever the user enters the application.

func applicationWillEnterForeground(_ application: UIApplication) {

  matomoTracker.startNewSession()

}

Activate Mobile Push (Recommended)

Prerequisite: 

Set up a Firebase Cloud Messaging client app in your Android APP

https://firebase.google.com/docs/cloud-messaging/ios/client

How to send app notifications via FirstHive ?

To send the notification to your app users, you need to integrate FCM with FirstHive,

Implement the below API to push the required details, for each user

URL: https://firsthive.com/engage/mobile/doAppUserSubscription

Method: POST

Parameter: 

Example: 

"projectId":"85"

"data":{"mobileNo":"1234567890","email":"[email protected]"}

"regId":"c3MyLdaDD7I:APA91bH-TO2aDrg6_-gl-MzEKrMfoAehnCpsnwmxc3TOv4MlUrIKRobRma5rVQvKaf1B3iR3xadzTDPxrO5yjlqsig1GGlzx00TUTnSJCTRfPyZjyWKcEpC1ilAclMccFJZH5oLoZvpg"

"visitId":"dd49680dc9ab2c53"

"browser":"iOShybrid"

How to Fetch Visitor Id?

Step 1: Define below after the firsthive sdk is executed

var visitor_id;    

    _paq.push([ function () { visitor_id = this.getVisitorId(); }]);

Step 2: Share the Legacy server key with FirstHive

Follow the steps mentioned below:

https://console.firebase.google.com/project/

Path to key in Firebase >> Project >> Project Settings >> Cloud Messaging >> Legacy server key

Steps to enable tracking of ‘Opens’ for App Push Notifications.

When a user tap on the app push notification sent from FirstHive, it will pass a Message ID to the app in the data payload in the following key.

messageId : <Unique value to identify the user and campaign>

Example below,

{

"to" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

"collapse_key" : "YYYYYYYYYYYYYYYYYYYYYYYYYY",

"notification" : {

 "body" : "Test notification content",

 "title": "Title of the message",

 "image": "<Image URL>"

},

"data" : {

"url":"<URL>",

"customPayload": {

  "screen":"HomePage",

 "messageId":"123456"

}

}

}

Whenever the app receives a value in the data payload for the above key, it should trigger following API and pass the tracking ID back to FirstHive

URL: https://firsthive.com/engage/mobile/trackNotification

Method: POST

Parameter: 

 :