iOS SDK
You can find a sample application for implementing Metrix iOS SDK in
Swift
here and inObjective-C
here.
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.1.0'
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.acquisitionSubId // The subId 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
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.