Troubleshooting

1. Verifying Successful Android SDK Integration

To verify that the Metrix SDK has been successfully integrated:

1. In Android Studio, select the connected device
2. Open Logcat (View → Tool Windows → Logcat)
3. Set the tag filter to Metrix

Expected log messages:

• Metrix initialization complete — SDK initialized successfully
• New custom event received — Event was received from the SDK
• Parcel successfully sent — SDK synchronized data with server
• Starting Metrix initialization — Initialization started

If you see error messages:

• Check that APPLICATION_ID and API_KEY are correctly set in AndroidManifest.xml
• Verify SDK is not in developer mode (metrix_developer_mode=false)
• Check network connectivity
• Verify ProGuard configuration includes -keep class ir.metrix.** { *; }

2. SDK Initialization Issues

Issue: “Unable to find appId in application manifest”

Cause: Missing or invalid ir.metrix.APPLICATION_ID metadata

Solution:

<manifest>
  <application>
    <meta-data
        android:name="ir.metrix.APPLICATION_ID"
        android:value="YOUR_APP_ID" />
  </application>
</manifest>

Issue: “Unable to find apiKey in application manifest”

Cause: Missing or invalid ir.metrix.API_KEY metadata

Solution:

<manifest>
  <application>
    <meta-data
        android:name="ir.metrix.API_KEY"
        android:value="YOUR_API_KEY" />
  </application>
</manifest>

Issue: “Running in developer-mode; Metrix won’t function”

Cause: Developer mode is enabled

Solution: Set metrix_developer_mode=false in manifest or remove it entirely:

<meta-data
    android:name="metrix_developer_mode"
    android:value="false" />

Issue: “Unable to retrieve FCM initialization values”

Cause: google-services.json not found or not applied

Solution:

1. Download google-services.json from Firebase Console
2. Place in app/ directory (not app/src/)
3. Ensure com.google.gms.google-services plugin is applied in build.gradle

3. Events Not Appearing in Dashboard

Issue: Events not showing up

Possible causes:

• Event not registered in Metrix panel
• Offline/no network connection
• SDK disabled (sdkEnabled: false)
• Event attributes exceed size limits

Solutions:

1. Register events in Event Management section of Metrix panel
2. Or use newEventByName() to auto-create events
3. Check network connectivity (adb logcat for “offline”)
4. Verify each attribute key/value is ≤ 512 bytes
5. Verify maximum 50 attributes per event

Issue: Revenue events showing zero amount

Cause: Incorrect data type or currency

Solution:

• Ensure revenue is Double (not String or Integer)
• Specify correct currency: RevenueCurrency.IRR, USD, or EUR
• Verify amount > 0

4. User Tracking Issues

Issue: User ID not being saved

Cause: Called before analytics module initialized

Solution:

• Verify analytics module included: implementation 'ir.metrix.analytics:metrix:2.8.1'
• Set user ID after app fully starts, not in Application.onCreate()
• Use CPU executor for timing issues:

    MetrixAnalytics.User.setUserCustomId("userId");

Issue: Custom attributes not appearing

Cause: Exceeding size limits or invalid types

Solution:

• Maximum 50 custom attributes per user
• Each key ≤ 512 bytes, each value ≤ 512 bytes
• Use supported types: String, Number, Boolean
• Use ISO 8601 for dates: "2024-11-20T11:24:03.000Z"

5. Push Notifications Not Received

Issue: Notifications not appearing

Possible causes:

• google-services.json not configured
• FCM credentials not in Metrix panel
• User ID not set
• Notifications disabled
• Device token not sent to Metrix

Solutions:

1. Verify google-services.json:

app/google-services.json (not src/)

2. Check Firebase credentials in Metrix panel:

   • Go to Workspace → Settings → Channel Integration → App Push
   • Upload Firebase credentials

3. Set user ID:

MetrixAnalytics.User.setUserCustomId("userId");

4. Verify notifications enabled:

boolean enabled = MetrixNotification.isNotificationEnable();

Issue: Firebase service not found

Cause: Service not declared or plugin not applied

Solution:

1. Add to AndroidManifest.xml:

<application>
    <service
        android:name="ir.metrix.notification.receivers.MetrixFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
</application>

2. Verify plugin in build.gradle:

plugins {
    id 'com.google.gms.google-services'
}

6. In-App Messages Not Showing

Issue: In-app messages not displaying

Possible causes:

• Auto-loading disabled without manual loading
• Messaging paused
• Module not initialized

Solutions:

1. If auto-loading disabled, call manually:

MetrixNotification.loadInAppMessages();

2. Check if paused:

if (MetrixNotification.isInAppMessagingPaused()) {
    MetrixNotification.pauseInAppMessages(false);
}

3. Verify initialization:

if (MetrixNotification.isInitialized()) {
    MetrixNotification.loadInAppMessages();
}

7. Deep Link Issues

Issue: Deep links not working

Possible causes:

• Intent filter not configured
• Scheme name mismatch
• Listener not set

Solutions:

1. Verify intent filter in manifest:

<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="metrixExample" />
    </intent-filter>
</activity>

2. Set deeplink listener:

MetrixAttribution.setOnDeeplinkResponseListener(deeplink -> {
    handleDeeplink(deeplink);
    return false; // Handle yourself
});

3. Handle in onCreate and onNewIntent:

@Override
protected void onCreate(Bundle savedInstanceState) {
    Intent intent = getIntent();
    Uri data = intent.getData();
    if (data != null) handleDeeplink(data);
}
 
@Override
protected void onNewIntent(Intent intent) {
    Uri data = intent.getData();
    if (data != null) handleDeeplink(data);
}

Issue: Deferred deeplinks not working

Cause: App not installed via Google Play or Cafe Bazaar

Solution:

• Deferred deeplinks only work with Google Play and Cafe Bazaar
• Install app from store before testing deferred deeplinks
• Set listener before clicking deeplink:

MetrixAttribution.setOnDeeplinkResponseListener(deeplink -> {
    return true; // Let Metrix handle
});

8. WebView Integration Issues

Issue: WebView not syncing data

Cause: Bridge not registered or already unregistered

Solution:

1. Register bridge in onCreate():

MetrixAnalyticsBridge.registerAndGetInstance(webView);

2. Enable JavaScript:

webView.getSettings().setJavaScriptEnabled(true);

3. Unregister only in onDestroy():

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

Issue: JavaScript methods not available

Cause: Bridge not initialized before loading URL

Solution:

// Register bridge BEFORE loading URL
MetrixAnalyticsBridge.registerAndGetInstance(webView);
 
// THEN load URL
webView.loadUrl("file:///android_asset/page.html");

9. ProGuard/R8 Obfuscation Issues

Issue: ClassNotFoundException or NoSuchMethodError at runtime

Cause: Classes being obfuscated by ProGuard/R8

Solution:

Add to proguard-rules.pro:

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

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

For Gradle 8+:

Add to app build.gradle:

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 
                         proguard.common, 
                         'proguard-rules.pro'
        }
    }
}

10. Session Tracking Issues

Issue: Session listeners not called

Cause: Analytics module not initialized

Solution:

• Verify analytics included: implementation 'ir.metrix.analytics:metrix:2.8.1'
• Set listeners early in activity lifecycle
• Check that app is not in developer mode

Issue: Session ID not available immediately

Cause: Timing issue during initialization

Solution:

• Session ID available by end of onCreate()
• Set listener before any events
• Use setSessionIdListener() in main activity

11. Attribution Issues

Issue: Attribution data not received

Possible causes:

• Attribution module not initialized
• Network connectivity issues
• User is organic (no campaign)

Solutions:

1. Verify module included: implementation 'ir.metrix.attribution:metrix:2.8.1'
2. Check network connectivity
3. Wait 24-48 hours for server-side attribution
4. Check Metrix panel for tracker configuration

Issue: Default tracker not working

Cause: App installed from official store

Solution:

• Never use default tracker on Google Play or Cafe Bazaar
• Default tracker only for direct distribution (website, side-load)
• Remove before publishing to stores

12. FCM Token Management

When do FCM tokens expire?

FCM registration tokens don’t have a fixed expiration time. They remain valid until:

• App is uninstalled/reinstalled
• App data is cleared
• Device is factory reset
• Google rotates tokens (security update)
• User logs out
• Device OS or Play Services major update

Best practices:

• Refresh token periodically (monthly)
• Request new token on app update
• Handle token refresh in onNewToken()

13. Network and Offline Issues

Issue: “Parcel successfully sent” not appearing

Cause: Offline or network blocked

Solutions:

1. Check internet connectivity
2. Verify device has active network
3. Check firewall isn’t blocking Metrix servers
4. Verify API firewall allows outbound HTTPS
5. SDK queues events offline, sends when online

14. Common Error Messages

15. Getting Help

Debug logs:

adb logcat | grep Metrix

Check manifest:

• ir.metrix.APPLICATION_ID set
• ir.metrix.API_KEY set
• metrix_developer_mode not true
• All required services/receivers declared

Verify dependencies:

implementation 'ir.metrix.analytics:metrix:2.8.1'
implementation 'ir.metrix.attribution:metrix:2.8.1'
implementation 'ir.metrix.notification:metrix:2.8.1'

16. Performance Issues

Issue: App startup delay

Cause: Heavy initialization on main thread

Solution:

• SDK uses background threads for heavy operations
• Pre-initialization happens on main thread (~10ms)
• Post-initialization on CPU thread
• Use developer mode to test without network

Issue: High memory usage

Cause: Large event queues or uncleared listeners

Solution:

• Remove listeners when not needed
• Clear event queue periodically
• Check for memory leaks in listeners
• Use Android Profiler to monitor