React-Native SDK (Legacy)
- Initial Implementation of the SDK in Your Project
- iOS
- Android
- Additional Features
- Sessions
- Session Identifier
- Event
- Custom Events
- Specify the default attributes for user
- Track Revenue
- Device Identifier
- Signature
- Uninstall Tracking
- Get User Attribution
- Deep Linking
- Standard deep linking scenario
- Deferred deep linking scenario
- Deferred deep linking callback
- Reattribution via deeplinks
- SDK Configuration
- Enable location listening
- Limitation in number of events to upload
- Limitation in number of events to send per request
- Limitation in number of events to buffer on the device
- The time interval for sending events
- The session timeout
- Pre-installed trackers
- SDK Signature
- Separation based on app stores
- Metrix device identifier
- Metrix Session Identifier
1.In order to add Metrix Plugin Execute the following commands in your react-native project directory to add the metrix library:
npm install @metrixorg/react-native-metrix --save
react-native link @metrixorg/react-native-metrix
In case of using CocoaPods, if the command react-native link
is not working, add the following line to your Podfile
execute the command pod install
:
pod 'react-native-metrix', :path => '../node_modules/@metrixorg/react-native-metrix'
If you are not using CocoaPods, follow the steps below:
- Right-click on
Libraries
inproject navigator
in the XCode section and chooseAdd files to [your project's name]
. - Go to
node_modules
and add the@metrixorg/react-native-metrix/ios/RCTMetrixReactNative.xcodeproj
file. - Copy the
node_modules/@metrixorg/react-native-metrix/ios/MetrixSdk.framework
file to[your projct's path]/ios
. - Choose your project in
project navigatior
section. InBuild Phases
tab,Link Binary with Libraries
section, addlibRCTMetrixReactNative.a
andadd other ➜ [your projct's path]/MetrixSdk.framewrok
. - Add
MetrixSdk.framework
inGeneral
tab ->Embeded Binaries
->+
.
Initialize Metrix library in your main React.Component
class.
- Import Metrix module in your code:
import { Metrix, MetrixConfig } from '@metrixorg/react-native-metrix';
- In
constructor
of your mainReact.Component
class, create an instance ofMetrixConfig
and initialize Metrix by callingonCreate
method:
Note: Before calling the onCreate
method, you can configure Metrix in the MetrixConfig
instance according to your requirements.
Check out the SDK Configuration section for more info.
let metrixConfig = new MetrixConfig('APP_ID');
// set your configuration (optional)
Metrix.onCreate(metrixConfig); // initialize the SDK
Replace APP_ID
with your application id. You can find that in your Metrix dashboard.
In Metrix, a session is a specific timeframe during which the user interacts with the app. These sessions and the data related to them are captured by the Metrix SDK and provided to you as events.
For each session, our SDK generates a unique Metrix session identifier (knowns as an mxsid). You can obtain this identifier by introducing a listener in your configuration. Check out the SDK Configuration section for more info.
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 four types of events in Metrix:
- Session Start: The time at which a session starts.
- Session Stop: The time at which a session ends.
- 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 event in your app. Suppose you want to track every tap on a button. You would have to create a new event slug in the Events Management section of your dashboard. Let's say that event slug is abc123
. In your button's onClick method you could then add the following lines to track the click.
You can call this function in two ways:
1. Make a custom event that has only one specified name:
Metrix.newEvent('my_event_slug');
2. Create a custom event with a specific number of attributes, for example, suppose you want to create a custom event in an online purchase program:
var attributes = {};
attributes['first_name'] = 'Ali';
attributes['last_name'] = 'Bagheri';
attributes['manufacturer'metrics] = 'Nike';
attributes['product_name'] = 'shirt';
attributes['type'] = 'sport';
attributes['size'] = 'large';
Metrix.newEvent('purchase_event_slug', attributes);
The parameters for the newEvent
method are as follows:
- First variable: The event slug which is a String you receive from the Metrix dashboard.
- Second variable: A
Map<String, String>
that specifies the attributes of an event.
Note: Every event can have up to 50 attributes unique to that event with each attribute having a limit of 512 bytes in key and 512 bytes in value.
Using this function, you can add arbitrary Attributes
to all events of the user:
var attributes = {};
attributes['manufacturer'] = 'Nike';
Metrix.addUserAttributes(attributes);
Note: Every event can have up to 50 attributes unique to that event 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 too with events. You can also add an optional order ID to avoid tracking duplicate revenues. By doing so, the last ten order IDs will be remembered and revenue events with duplicate order IDs are skipped. This is especially useful for tracking in-app purchases. You can see an example below where a tap is worth 12,000 IRR:
Metrix.newRevenue('my_event_slug', 12000, 0, '2');
- 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
(Rial),1
(Dollar), or2
(Euro). Rial is considered as the default value. - The fourth parameter is your order number (optional).
For each device with your app installed on, our backend generates a unique Metrix device identifier (known as an mxuid). You can obtain this identifier by introducing a listener in your configuration. Check out the SDK Configuration section for more info.
An account manager must activate the Metrix SDK Signature.
If the SDK signature has already been enabled on your account and you have access to App Secrets in your Metrix Dashboard, you should set the secrets in your application. Check out the SDK Configuration section for more info.
Metrix’s app uninstall tracking relies on silent push notifications to determine if an app is installed on a device.
Note: You must configure your app for push notifications through Firebase Cloud Messaging (FCM). Google Cloud Messaging (GCM) is not supported.
Developer instructions for configuring your app for uninstall tracking can be found below.
- Find your FCM server key
In your Firebase console, select the settings (gear) icon > Project settings. Select CLOUD MESSAGING and locate your Server key
and sender id
token.
- Add your FCM server key and sender id to your Metrix account
In the Metrix dashboard, navigate to your app and select your app settings. Select Push configuration and enter or paste your FCM server key into the Server Key field and FCM sender id into Sender Id field. Select Save.
- Configure the Metrix SDK to receive your app's push notification token
metrixConfig.setFirebaseId('firebase app id', 'firebase project id', 'firebase api key');
Note: Please check out the SDK Configuration section for further considerations on configuring the SDK.
- Add this dependency to your
app/build.gradle
file:
implementation 'com.google.firebase:firebase-messaging:18.0.0'
In case you want to access info about your user's current attribution when ever you need it, you can make a call to the following method of the Metrix instance:
metrixConfig.setOnAttributionChangedListener(attributionModel => {
//TODO
});
Here is a quick summary of AttributionModel
properties:
attributionModel.getAcquisitionAd()
: The creative/ad grouping level of the current attribution.
attributionModel.getAcquisitionAdSet()
: The adGroup/adSet grouping level of the current attribution.
attributionModel.getAcquisitionCampaign()
: The campaign grouping level of the current attribution.
attributionModel.getAcquisitionSource()
: The network/source grouping level of the current attribution.
attributionModel.getAttributionStatus()
: Specifies the status of the user in the campaign.
AttributionStatus
has one of the values below:
ATTRIBUTED
NOT_ATTRIBUTED_YET
ATTRIBUTION_NOT_NEEDED
UNKNOWN
Note: Please check out the SDK Configuration section for further considerations on configuring the SDK.
If you are using Metrix tracker URLs with deeplinking enabled, it is possible to receive information about the deeplink 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.
You can use this library to implement the standard deep linking scenario.
Deferred deeplinking scenario occurs when a user clicks on a Metrix tracker URL with a deep_link
parameter contained in it, 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 Play Store to download and install your app. After opening it for the first time, deep_link
parameter 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 it with a callback method in the config object.
metrixConfig.setShouldLaunchDeeplink(true);
metrixConfig.setOnDeeplinkResponseListener(deeplink => {
//TODO
});
After the Metrix SDK receives the deep link information from our backend, the SDK will deliver you its content via the listener and expect the boolean
return value from you. This return 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 deeplink (like in the standard deeplinking scenario).
If you return 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, return false
from the listener, and (based on the deep link content) decide on your own what to do next in your app.
Note: Please check out the SDK Configuration section for further considerations on configuring the SDK.
Metrix enables you to run re-engagement campaigns with deeplinks.
If you are using this feature, you need to make one additional call to the Metrix SDK in your app for us to properly reattribute your users.
Once you have received the deeplink content in your app, add a call to the Metrix.appWillOpenUrl(deeplink)
method. By making this call, the Metrix SDK will send information to the Metrix backend to check if there is any new attribution information inside of the deeplink. If your user is reattributed due to a click on the Metrix tracker URL with deeplink content.
Here's how the call to Metrix.appWillOpenUrl(deeplink)
should look:
onDeeplink(deeplink) {
Metrix.appWillOpenUrl(deeplink);
}
In your main React.Component
class, before calling onCreate
method to initialize Metrix, you can configure Metrix SDK by introducing different configurations to your MetrixConfig
instance, calling available methods in the class. See the sample below:
let metrixConfig = new MetrixConfig('APP_ID');
// Setting your configuration
Metrix.onCreate(metrixConfig); // initializing the SDK
Available configurations can be found below:
Using the following method, you can inform Metrix that you wish to send information about the location of the user.
metrixConfig.setLocationListening(isLocationListeningEnable);
Note: In order for these methods to work properly, your app must be granted location permissions by the user.
Add one of the following permissions to your AndroidManifest.xml
file.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
You should be informed that as of Android 6.0 (API level 23), permissions should be asked and granted at runtime as well.
Using the following method, you can specify that each time the number of your buffered events reaches the threshold, the Metrix SDK should send them to the server:
metrixConfig.setEventUploadThreshold(50);
The default value is 30 events.
Using this method, you can specify the maximum number of out-going events per request:
metrixConfig.setEventUploadMaxBatchSize(100);
The default value is 100 events.
Using the following method, you can specify the maximum number of events that are buffered in the SDK (for example, if the user's device loses internet connection, the events will be buffered in the library until there is a chance to send the events and empty the buffer) and if the number of buffered events in the library passes this amount, old events are destroyed by SDK to make space for new events:
metrixConfig.setEventMaxCount(1000);
The default value is 1000 events.
By using this method, you can specify the timeout period of requests for sending events:
metrixConfig.setEventUploadPeriodMillis(30000);
The default value is 30 seconds.
Using this function, you can specify the limit of session length in your application in unit of milliseconds. For example, if this value is 10,000 and the user interacts with the application for 70 seconds, Metrix calculates this interaction as seven sessions.
metrixConfig.setSessionTimeoutMillis(1800000);
The default value is 30 minutes.
If you want to use the Metrix SDK to recognize users whose installation has not been triggered by an ad click, set the default tracker in your config using the method below. Replace trackerToken
with the tracker token you created in the dashboard.
metrixConfig.setDefaultTrackerToken(trackerToken);
If the SDK signature has already been enabled on your account and you have access to App Secrets in your Metrix Dashboard, please use the method below to integrate the SDK signature into your app.
An App Secret is set by calling setAppSecret on your config instance:
metrixConfig.setAppSecret(secretId, info1, info2, info3, info4);
If you want to publish your app in different stores such as Cafe Bazaar, Google Play, etc, and split the organic users by their store's source, you can use the following method:
metrixConfig.setStore('store name');
For each device with your app installed on, our backend generates a unique Metrix device identifier (known as an mxuid). You can obtain this identifier using the following method.
metrixConfig.setOnReceiveUserIdListener(metrixUserId => {
//TODO
});
Note: Information about the adId is only available after our backend tracks the app installation. It is not possible to access the adId value before the SDK has been initialized and the installation of your app has been successfully tracked.
For each session, our sdk generates a unique Metrix session identifier (knowns as an mxsid). In order to obtain this identifier, call the following method on the MetrixConfig
instance:
metrixConfig.setOnSessionIdListener(metrixSessionId => {
//TODO
});