npm version



You can find a sample application for implementing Metrix React-Native SDK here.



Installing Metrix Package

Execute the following command in your project's directory to install Metrix package:

npm install @metrixorg/react-native-plugin

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.

Android Configuration

1. 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="ir.metrix.APPLICATION_ID"
        android:value="YOUR_APP_ID" />

  </application>
</manifest>

Replace YOUR_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.

2. 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="ir.metrix.SIGNATURE"
        android:value="YOUR_SIGNATURE" />

  </application>
</manifest>

iOS Configuration

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

cd ios
pod install

2. In constructor method of your main React.Component class, initialize Metrix by invoking the following method:

Metrix.initialize("YOUR_APP_ID");

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

3. 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);


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(sessionId => {
  // TODO
});

Current Session Number

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

Metrix.setSessionNumberListener(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
var attributes = {};
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:

var attributes = {};
attributes["manufacturer"] = "Nike";

Metrix.setUserAttributes(attributes);

and with the following methods, you can add specific attributes:

Metrix.setUserCustomId("yourCustomUserId"); // call when user tries to login in your system and set userId value that user already knows in your system
Metrix.deleteUserCustomId(); // call when your user goes to logout in your system
Metrix.setUserFirstName("userFirstName");
Metrix.setUserLastName("userLastName");
Metrix.setUserPhoneNumber("phoneNumber");
Metrix.setUserHashedPhoneNumber("hashedPhoneNumber");
Metrix.setUserEmail("email");
Metrix.setUserHashedEmail("hashedEmail");
Metrix.setUserCountry("country");
Metrix.setUserCity("city");
Metrix.setUserRegion("region");
Metrix.setUserLocality("locality");
Metrix.setUserGender(gender); // gender value could be "MALE" , "FEMALE" or "OTHER"
Metrix.setUserBirthday(birthday); // birthday value type should be 'Long' timestamp
Metrix.setUserFcmToken("fcmToken");
Metrix.userChannelEnabled(channel); // channel value could be "SMS", "PUSH" or "EMAIL"
Metrix.userChannelDisabled(channel); // channel value could be "SMS", "PUSH" or "EMAIL"

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);
  • 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).

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.setUserIdListener(metrixUserId => {
  //TODO
});

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


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 Firebase push credentials to Metrix panel.

In the Metrix dashboard, navigate to your application and select your application settings. Select Push configuration. In this page, Push configuration is divided into two sections. Legacy mode and New mode. we recommend to use both modes. enter credentials and click save.

New mode

You can get Service Account Date from project settings in Service Accounts by clicking generate new private key.

push configuration

Legacy mode

You can get server key and sender id from project settings in Cloud Messaging tab of your Firebase console.

push configuration



  • Enable uninstall tracking

After providing credentials 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.setOnAttributionChangedListener(attributionData => {
  //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

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.setOnDeeplinkResponseListener(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 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");

Implement Push Notification

  • For start add google-services.json from firebase console to your project.

  • Also you need to add Firebase push credentials to Metrix panel.

In the Metrix dashboard, navigate to your application and select your application settings. Select Push configuration. In this page, Push configuration is divided into two sections. Legacy mode and New mode. we recommend to use both modes. enter credentials and click save.

New mode

You can get Service Account Date from project settings in Service Accounts by clicking generate new private key.

push configuration

Legacy mode

You can get server key and sender id from project settings in Cloud Messaging tab of your Firebase console.

push configuration

And Then:

1. Add Metrix push enable flag in your android app-level gradle.properties file:

  metrix.notitifcation.enable=true

2. Add metrix notification receive method in your android Custom FirebaseMessagingService class:

    class CustomFirebaseMessagingService: FirebaseMessagingService() {

        override fun onMessageReceived(message: RemoteMessage) {
            if (MetrixNotification.onMessageReceived(message)) return

            // here you can process your own fcm messages
        }
}

Note: For now we only send notification to your known user, so user should have customUserId to be able to receive push

3. Set customUserId on user login and delete it when user logged out:

  Metrix.setUserCustomId("yourCustomUserId");
  Metrix.deleteUserCustomId();