Configuring Your Project


By following the few steps below, Metrix library will be ready to use in your application:

1. Add Metrix pod to your project's Podfile and run the pod install command:

pod 'Metrix/native', '2.0.3'

In case you don't use CocoaPods in your project, you can download Metrix framework here and add it manually.

2. Initialize Metrix in your application.

  • Import Metrix like the following in your AppDelegate file:

Swift

import Metrix

Objective-C

@import Metrix;
  • Inside the didFinishLaunchingWithOptions method, initialize Metrix by invoking the following method:

Swift

MetrixClient.initialize(metrixAppId: "APP_ID")

Objective-C

[MetrixClient initializeWithMetrixAppId:@"APP_ID"];

Replace APP_ID with your application id. You can find the id in your Metrix dashboard under application settings.



Additional Features


Sessions

In Metrix, a session is a specific timeframe during which the user interacts with the application. These sessions and the data related to them are captured by the Metrix SDK and provided to you in your dashboard.

Session Identifier

For each session, our SDK generates a unique identifier. You can obtain this identifier by introducing a listener using the following method:

Swift

MetrixClient.setSessionIdListener { (sessionId: String) in
    // your logic
}

Objective-C

[MetrixClient setSessionIdListener:^(NSString *sessionId) {
    // your logic
}];

Whenever a new session is started, your listener will be called with the new session's identifier.

Current Session Number

Using the following method, you can provide a listener for current session number:

    Metrix.setSessionNumberListener(new SessionNumberListener() {
        @Override
        public void onSessionNumberChanged(String sessionNumber) {
            // your logic
        }
    });

Swift

MetrixClient.setSessionNumberListener { (sessionNum: Int) in
    // your logic
}

Objective-C

[MetrixClient setSessionNumberListener:^(NSInteger sessionNumber) {
    // your logic
}];

Whenever a new session is started, your listener will be called with the new session's number.


Each interaction that the user has with your application can be introduced as an event in your dashboard and application in order for Metrix to collect and present its statistics.

There are two types of events in Metrix:

  • Custom: Depending on your application logic and the interaction that the user has with your app, you can create and send custom events.
  • Revenue: A special type of custom events you can specify for tracking your application revenue.

Custom Events

You can use Metrix to track any events in your application. Suppose you want to track every tap on a button. You would have to create a new event in the Events Management section of your dashboard and retrieve the generated slug for the event. The slug is to be used in the application code to send the event to Metrix library. So whenever the button is clicked, you could invoke the Metrix newEvent method providing the event slug and optionally some attributes related to the event like the following:

Swift

// Send a simple event
MetrixClient.newEvent(slug: "event-slug")

// Send an event with attributes
let myAttributes = [
            "first_name": "Mohammad",
            "last_name": "Bagheri"]

MetrixClient.newEvent(slug: "my_event_slug", attributes: myAttributes)

Objective-C

// Send a simple event 
[MetrixClient newEventWithSlug: @"event-slug"];

// Send an event with attributes
NSMutableDictionary *myAttributes = [[NSMutableDictionary alloc] init];
myAttributes[@"first_name"] = @"Ali";
myAttributes[@"last_name"] = @"Bagheri";

[MetrixClient newEventWithSlug: @"my_event_slug" attributes:myAttributes];

The parameters for the newEvent method are as follows:

  • First parameter: The event slug which is a String you receive from the Metrix dashboard.
  • Second parameter (optional): A Dictionary with String keys and values that specifies the attributes of an event.

Note: Each event can have up to total 50 attributes with each attribute having a limit of 512 bytes in key and 512 bytes in value.


Specify the Default Attributes for a User

Using the following method, you can add arbitrary attributes to all events of the user:

Swift

let attributes = ["manufacturer": "Nike"]
MetrixClient.addUserAttributes(userAttrs: attributes)

Objective-C

NSMutableDictionary *attributes = [[NSMutableDictionary alloc] init];
attributes[@"manufacturer"] = @"Nike";

[MetrixClient addUserAttributesWithUserAttrs: attributes];

Note: Each event can have up to total 50 attributes with each attribute having a limit of 512 bytes in key and 512 bytes in value.


Track Revenue

If your users can generate revenue by tapping on advertisements or making in-app purchases, you can track those revenues with a special type of Metrix custom event. This is specially useful for tracking in-app purchases. Like any custom event, revenues must be defined in dashboard event management section to retrieve the slug. You can see an example below where a tap is worth 12,000 IRR:

Swift

MetrixClient.newRevenue(slug: "my_event_slug", revenue: 12000, currency: .IRR, orderId: "myOrderId")

Objective-C

[MetrixClient newRevenueWithSlug: @"my_event_slug" revenue: 12000 currency: RevenueCurrencyIRR orderId: @"myOrderId"];
  • The first parameter is the slug you get from the dashboard.
  • The second parameter is the amount of revenue.
  • The third parameter is the currency of this event which can be .IRR (Default), .USD, or .EUR.
  • The fourth parameter is your order identifier (optional).

Device Identifier

For each device with your app installed on, our service generates a unique identifier. You can obtain this identifier by introducing a listener using the following method:

Swift

MetrixClient.setUserIdListener { (userId: String) in
    // your logic
}

Objective-C

[MetrixClient setUserIdListener:^(NSString *userId) {
    // your logic
}];

The listener will be called once the identifier is fetched by our SDK.


SDK Signature

Metrix provides dedicated SDK signature for your application as an extra layer of security to prevent possible data frauds using SDK spoofing.

To use SDK signature you should first enable the feature in your dashboard under application settings and create a signature for your application. For each created SDK signature, there is a secret id and four info strings. Invoke the following method providing the info to set the signature:

Swift

MetrixClient.setAppSecret(secretId: secretId, info1: info1, info2: info2, info3: info3, info4: info4)

Objective-C

[MetrixClient setAppSecretWithSecretId:secretId info1:info1 info2:info2 info3:info3 info4:info4];

Note: The invocation must be placed in didFinishLaunchingWithOptions method of the project AppDelegate class.


Get User Attribution Information

You can obtain the information about the user's attribution by introducing a listener using the following method:

Swift

MetrixClient.setOnAttributionChangedListener { (data: AttributionData) in
    print("Attribution status: \(data.attributionStatus.rawValue)")
    // TODO
}

Objective-C

[MetrixClient setOnAttributionChangedListener:^(AttributionData *data) {
    printf("AttributionStatus: %s", [[data attributionStatusRaw] UTF8String]);
    // TODO
}];

The listener will be called once the attribution data is fetched by the SDK provided with an instance of AttributionData class.

Here is a quick summary of AttributionData class properties:

attributionData.acquisitionAd // The creative/ad grouping level of the current attribution.
attributionData.acquisitionAdSet // The adGroup/adSet grouping level of the current attribution.
attributionData.acquisitionCampaign // The campaign grouping level of the current attribution.
attributionData.acquisitionSource // The network/source grouping level of the current attribution.
attributionData.attributionStatus // An Enum Specifying the status of the user in the campaign.

AttributionStatus Enum has one of the values below:

  • ATTRIBUTED
  • NOT_ATTRIBUTED_YET
  • ATTRIBUTION_NOT_NEEDED
  • UNKNOWN

Separating Organic Installations Based on Stores

If you wish to publish your application in different application stores and intend to split the organic users by the store from which they have downloaded the application, you can have a separate build for each store and call the following method replacing STORE_NAME with corresponding store name in each build:

Swift

MetrixClient.setStore(storeName: "store name")

Objective-C

[MetrixClient setStoreWithStoreName:@"store name"];

Note: The invocation must be placed in didFinishLaunchingWithOptions method of the project AppDelegate class.