pub package


You can find a sample application for implementing Metrix Flutter SDK here.


Installing Metrix Dependency

Add Metrix plugin dependency to your project dependencies in pubspec.yaml file and execute the flutter pub get command.

dependencies:
  metrix_plugin: ^1.5.0

Android Configuration

Add your Metrix application id as an application meta-data inside AndroidManifest.xml file:

<manifest>

  ...

  <application>

    ...

    <!-- Add the following lines and replace your application id -->
    <meta-data
        android:name="metrix_appId"
        android:value="APP_ID" />

  </application>
</manifest>

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

AndroidManifest.xml file can be found under android -> app -> src -> main.


iOS Configuration

1. In iOS directory of your project, execute the Pod installation command to install Metrix native dependencies:

cd ios
pod install

2. Initialise Metrix SDK as soon as possible in your Flutter app (upon loading first widget in your app), by invoking the following method:

Metrix.initialize("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 String by calling the following method:

Metrix.setSessionIdListener().listen((id) => {
  // TODO
});

Current Session Number

Using the following method, you can obtain the current session number:

Metrix.setSessionNumberListener().listen((sessionNum) => {
  // TODO
});

Events

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 In your button's onClick method you could then invoke the Metrix newEvent method providing the event slug and optionally some attributes related to the event like the following:

// Send a simple event 
Metrix.newEvent("my_event_slug");

// Send an event with attributes
Map<String, String> attributes = new Map();
attributes["first_name"] =  "Ali";
attributes["last_name"] =  "Bagheri";

Metrix.newEvent("my_event_slug", attributes);

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 Map<String, String> 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:

Map<String, String> attributes = new Map();
attributes["manufacturer"] = "Nike";

Metrix.addUserAttributes(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:

Metrix.newRevenue("my_event_slug", 12000, 0, "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 0 (IRR) (Default), 1 (USD), or 2 (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:

Metrix.getUserId().then((id) => {
  // TODO
});

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.

Enabling SDK Signature for Android Application

For each created SDK signature, there is a secret string under the Encoded column. You should put that string as an application meta-data in the AndroidManifest.xml file like the following:

<manifest>

  ...

  <application>

    ...

    <!-- Add the following lines and replace the signature string -->
    <meta-data
        android:name="metrix_signature"
        android:value="YOUR_SIGNATURE" />

  </application>
</manifest>

Enabling SDK Signature for iOS 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:

Metrix.setAppSecret(secretId, info1, info2, info3, info4);

Uninstall Tracking for Android Applications

Metrix application uninstall tracking relies on silent push notifications to determine if your application is installed on a device.

You must configure your application for push notifications through Firebase Cloud Messaging (FCM).


Developer instructions for configuring your app for uninstall tracking can be found below.

  • Add your FCM server key and sender id to your Metrix app

In the Metrix dashboard, navigate to your application and select your application settings. Select Push configuration and enter or paste your FCM server key into the server key field and FCM sender id into the Sender Id field. Select save.

push configuration

You can find the FCM server key and sender id in your Firebase console. Select the settings (gear) icon > Project settings. Select CLOUD MESSAGING and locate the tokens.

firebase cloud messageing


  • Enable uninstall tracking

After providing FCM server key and sender id in application push configuration section, enable uninstall tracking by switching the following toggle in the same section.

enable uninstall measurement


  • Send FCM push token in application

After implementing FCM push notification service in your application, send FCM push token to Metrix SDK by invoking the following method whenever a new token is received:

Metrix.setPushToken(token);

Get User Attribution Information

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

Metrix.getAttributionData().listen((metrixAttribution) => {
// TODO
});

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

Here is a quick summary of MetrixAttribution class properties:

metrixAttribution.acquisitionAd // The creative/ad grouping level of the current attribution.
metrixAttribution.acquisitionAdSet // The adGroup/adSet grouping level of the current attribution.
metrixAttribution.acquisitionCampaign // The campaign grouping level of the current attribution.
metrixAttribution.acquisitionSource // The network/source grouping level of the current attribution.
metrixAttribution.acquisitionSubId // The subId level of the current attribution.
metrixAttribution.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

Deep Linking for Android Applications

If you are using Metrix tracker URLs with deep linking enabled, it is possible to receive information about the deep link URL and its content. Users may interact with the URL regardless of whether they have your app installed on their device (standard deep linking scenario) or not (deferred deep linking scenario). In the standard deep linking scenario, the Android platform natively offers the possibility for you to receive deep link content information. The Android platform does not automatically support deferred deep linking scenario; in this case, the Metrix SDK offers the mechanism you need to get the information about the deep link content.

Standard Deep Linking Scenario

If a user has your application installed and you want it to launch to a specific content after they engage with an Metrix tracker URL containing a deep link, enable deep linking in your app.

For implementing standard deep linking in your application, you can use this library.

Deferred Deep Linking Scenario

Deferred deep linking scenario occurs when a user clicks on a Metrix tracker URL containing a deep link, but does not have the app installed on the device at click time. When the user clicks the URL, he/she will be redirected to the Google Play Store to download and install your app. After opening it for the first time, the deep link content will be delivered to your app.

If you wish to control if the Metrix SDK will open the deferred deep link, you can do so by providing the following listener:

Metrix.shouldLaunchDeeplink = true;
Metrix.getDeeplinkResponse().then((deeplink) => {
// TODO
});

After the Metrix SDK receives the deep link information from our server, the SDK will deliver you its content via the listener. Also the SDK expects the shouldLaunchDeeplink boolean value from you. This value represents your decision on whether or not the Metrix SDK should launch the activity to which you have assigned the scheme name from the deep link (like in the standard deep linking scenario).

If you set the value to true, we will launch it, triggering the scenario described in the Standard deep linking scenario chapter. If you do not want the SDK to launch the activity, set the boolean value to false, and (based on the deep link content) decide on your own what to do next in your app.

Note: Deferred deep linking scenario is only available for users installing the application from Google Play Store.


Pre-Installed Trackers

If you want to use the Metrix SDK to recognize users whose installation has not been triggered by an ad click, you should set a default tracker in your application.

This feature is introduced to be used when you intend to track installations that has not been triggered by an ad click. In other words, if you want to publish an APK file of your application on some platform other than application stores to be downloaded and opened directly by users, to attribute these users to a tracker you should specify the tracker token in your application using this feature; otherwise, these installations will all be considered organic.

Note: You should never publish your application containing a pre-installed tracker in an application store; otherwise, all the installations from that store including the organic ones will be considered sourced from the specified tracker.


Configuring for Android

Add the following application meta-data in AndroidManifest.xml file. Replace TOKEN with the tracker token you created in the dashboard.

<manifest>

  ...

  <application>

    ...

    <!-- Add the following line and replace "TOKEN" with your tracker token -->
    <meta-data
        android:name="metrix_trackerToken"
        android:value="TOKEN" />

  </application>
</manifest>

Configuring for iOS

Invoke the following method replacing TOKEN with the tracker token you created in the dashboard:

Metrix.setDefaultTracker("TOKEN");

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 put the corresponding store name in your application for each build.

Configuring for Android

Add the following application meta-data in AndroidManifest.xml file replacing STORE_NAME with corresponding store name in each build:

<manifest>

  ...

  <application>

    ...

    <!-- Add these lines and replace "STORE_NAME" -->
    <meta-data
        android:name="metrix_storeName"
        android:value="STORE_NAME" />

  </application>
</manifest>

Configuring for iOS

Invoke the following method replacing STORE_NAME with corresponding store name in each build:

Metrix.setStore("STORE_NAME");