Getting Started

You can view the sample Metrix implementation project here .

Installation and Setup

By following the steps below, the Metrix library will be activated and ready for use in your application:

1. Check Android SDK and Compile Version

Ensure that your application’s build.gradle file has the appropriate Android SDK versions configured:

android {
    compileSdkVersion 34      // Required: >= 31 (actual build uses 34)
    targetSdkVersion 34       // Recommended
 
    defaultConfig {
        minSdkVersion 21      // Minimum supported API level
        // ...
    }
}

2. Configure Maven Repository

Add the mavenCentral repository to your project’s build.gradle file in the allprojects section:

allprojects {
    repositories {
        // ...
 
        mavenCentral()
    }
}

3. Add Metrix Library Dependencies

Add the Metrix library dependency to the dependencies section of your application’s build.gradle file (add the appropriate library based on whether you’re using analytics or attribution features):

// For analytics and marketing automation
implementation 'ir.metrix.analytics:metrix:2.8.2'
 
// For attribution tracking
implementation 'ir.metrix.attribution:metrix:2.8.2'
 
// For push notifications (optional)
implementation 'ir.metrix.notification:metrix:2.8.2'

4. Configure App ID and API Key in AndroidManifest.xml

Place the Metrix application ID (app id) and API key (api key) in your application’s AndroidManifest.xml file:

<manifest>
  <application>
    <!-- Replace YOUR_APP_ID with your actual app ID -->
    <meta-data
        android:name="ir.metrix.APPLICATION_ID"
        android:value="YOUR_APP_ID" />
 
    <!-- Replace YOUR_API_KEY with your actual API key -->
    <meta-data
        android:name="ir.metrix.API_KEY"
        android:value="YOUR_API_KEY" />
  </application>
</manifest>

Where to find these values:

• YOUR_APP_ID: Your application ID obtained from the Metrix panel
• YOUR_API_KEY: Your API key obtained from the Metrix panel

5. Verify Required Permissions

Ensure the following permissions are included in your application’s manifest. The core module includes these automatically, but verify they’re in your final merged manifest:

<manifest>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
</manifest>

Additional permissions for specific modules:

If using Notification module:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission
    android:name="android.permission.BROADCAST_CLOSE_SYSTEM_DIALOGS"
    tools:ignore="ProtectedPermissions" />

6. Configure ProGuard/R8 (For Gradle 8+)

If you are using Gradle version 8 or higher, add the following to your ProGuard configuration file (proguard-rules.pro):

-keep class ir.metrix.** { *; }

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }

The core module already includes consumer ProGuard rules via proguard-consumer-common.pro, so these are often automatically merged into your build.

Optional Configuration

Enable SDK Signature Verification

To enhance library security, enable SDK Signature verification:

1. Enable SDK Signature in your Metrix panel
2. Retrieve the signature identifier from the Encoded column in your panel
3. Add the signature to your application’s manifest:

Metrix.setSignature("YOUR_SIGNATURE");

Reduce Library Size

To reduce the APK size by excluding native libraries, add the following to your app’s build.gradle:

android {
    packaging {
        jniLibs {
            excludes += "/lib/**/libconscrypt_jni.so"
        }
    }
}

Enable Developer Mode

You can disable the Metrix library during development and testing, preventing statistics and events from being recorded.

Add the following metadata to your application’s AndroidManifest.xml file:

<manifest>
  <application>
 
    ...
 
    <!-- Add the following lines -->
    <meta-data
        android:name="metrix_developer_mode"
        android:value="true" />
  </application>
</manifest>

Using Build Variants: Additionally, using manifestPlaceholders  in Android, you can manage this value in your application’s gradle file for different build variants. In the following example, the Metrix library will be disabled in the “develop” variant and enabled in the “release” variant:

<!-- AndroidManifest.xml -->
<manifest>
  <application>
    <meta-data
        android:name="metrix_developer_mode"
        android:value="${metrixDeveloperMode}" />
  </application>
</manifest>

// build.gradle
android {
    buildTypes {
        debug {
            manifestPlaceholders = [metrixDeveloperMode: "true"]
        }
 
        release {
            manifestPlaceholders = [metrixDeveloperMode: "false"]
        }
    }
}

Core API Usage

After initialization, you can use the following public APIs from the Metrix class:

// Set SDK signature for authentication
Metrix.setSignature(String signature);
 
// Set a listener to be notified of user ID changes
Metrix.setUserIdListener(UserIdListener listener);
 
// Set a custom user ID for your user
Metrix.setUserCustomId(String id);
 
// Clear the custom user ID
Metrix.deleteUserCustomId();

WebView Integration

The Metrix SDK supports JavaScript integration in WebView environments. All Metrix activities are performed at the native level, with web content communicating through a bridge.

Setup Steps

1. Enable JavaScript in your WebView:

webView.getSettings().setJavaScriptEnabled(true);

2. Register the Metrix bridge for the modules you’re using:

MetrixAnalyticsBridge.registerAndGetInstance(webView);
MetrixAttributionBridge.registerAndGetInstance(webView);

3. If you need to change the WebView, update the bridge:

MetrixBridge.setWebView(newWebView);

4. When destroying the WebView or activity, unregister:

@Override
protected void onDestroy() {
    MetrixAnalyticsBridge.unregister();
    MetrixAttributionBridge.unregister();
    super.onDestroy();
}

Complete WebView Example

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
 
        WebView webView = findViewById(R.id.webView);
        webView.getSettings().setJavaScriptEnabled(true);
        webView.setWebChromeClient(new WebChromeClient());
        webView.setWebViewClient(new WebViewClient());
 
        // Register Metrix bridges
        MetrixAnalyticsBridge.registerAndGetInstance(webView);
        MetrixAttributionBridge.registerAndGetInstance(webView);
 
        try {
            webView.loadUrl("file:///android_asset/your_page.html");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
 
    @Override
    protected void onDestroy() {
        MetrixAnalyticsBridge.unregister();
        MetrixAttributionBridge.unregister();
        super.onDestroy();
    }
}

JavaScript Integration

This way, the Metrix library has been successfully activated in your application, and the Metrix Javascript interface will serve as the communication bridge between the Metrix library and your loaded pages in the webview.

To interact with the Metrix library and use its features, such as sending events, import the Metrix Javascript file in your HTML file. The file is located in the assets folder and can be viewed in the sample implementation . Import it as follows:

<script type="text/javascript" src="metrix_analytics.js"></script>
<script type="text/javascript" src="metrix_attribution.js"></script>

See the sample implementation  for JavaScript files and usage examples.

After importing, you can call MetrixAnalytics and MetrixAttribution methods directly from your JavaScript code.

Troubleshooting

SDK Initialization Fails

Symptoms: App crashes on startup or Metrix functionality is unavailable

Causes:

• Missing or invalid ir.metrix.APPLICATION_ID in manifest
• Missing or invalid ir.metrix.API_KEY in manifest
• ProGuard configuration issues (classes are obfuscated/removed)
• metrix_developer_mode is enabled

Solutions:

1. Verify APPLICATION_ID and API_KEY are correctly set in AndroidManifest.xml
2. Verify your ProGuard rules include: -keep class ir.metrix.** { *; }
3. Check logcat for specific error messages from tag Metrix or MetrixInit
4. Disable developer mode if you want the SDK to function

Missing AD_ID Permission

Symptoms: Build or runtime warnings about AD_ID permission

Solution: Ensure your manifest includes:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

See the sample implementation  for complete working examples.