Flutter SDK
- Installing Metrix Dependency
- Android Configuration
- iOS Configuration
- Additional Features
- Sessions
- Session Identifier
- Current Session Number
- Events
- Custom Events
- Specify the Default Attributes for a User
- Track Revenue
- Device Identifier
- SDK Signature
- Enabling SDK Signature for Android Application
- Enabling SDK Signature for iOS Application
- Uninstall Tracking for Android Applications
- Get User Attribution Information
- Deep Linking for Android Applications
- Standard Deep Linking Scenario
- Deferred Deep Linking Scenario
- Pre-Installed Trackers
- Configuring for Android
- Configuring for iOS
- Separating Organic Installations Based on Stores
- Configuring for Android
- Configuring for iOS
You can find a sample application for implementing Metrix Flutter SDK here.
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
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
.
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.
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 String by calling the following method:
Metrix.setSessionIdListener().listen((id) => {
// TODO
});
Using the following method, you can obtain the current session number:
Metrix.setSessionNumberListener().listen((sessionNum) => {
// TODO
});
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 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.
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.
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)
, or2 (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:
Metrix.getUserId().then((id) => {
// TODO
});
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 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>
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);
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.
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.
- 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.
- 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);
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
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.
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 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.
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.
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>
Invoke the following method replacing TOKEN
with the tracker token you created in the dashboard:
Metrix.setDefaultTracker("TOKEN");
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.
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>
Invoke the following method replacing STORE_NAME
with corresponding store name in each build:
Metrix.setStore("STORE_NAME");