Troubleshooting | متریکس Metrix

عیب‌یابی

1. بررسی موفقیت‌آمیز بودن یکپارچه‌سازی Android SDK

برای بررسی اینکه Metrix SDK با موفقیت یکپارچه شده است:

در Android Studio، دستگاه متصل را انتخاب کنید.
Logcat را باز کنید (View → Tool Windows → Logcat).
فیلتر تگ (tag filter) را روی Metrix تنظیم کنید.

پیام‌های لاگ مورد انتظار:

Metrix initialization complete — SDK با موفقیت مقداردهی اولیه شد.
New custom event received — ایونت از SDK دریافت شد.
Parcel successfully sent — SDK داده‌ها را با سرور همگام‌سازی کرد.
Starting Metrix initialization — مقداردهی اولیه آغاز شد.

اگر پیام‌های خطا مشاهده می‌کنید:

بررسی کنید که APPLICATION_ID و API_KEY در AndroidManifest.xml به درستی تنظیم شده باشند.
بررسی کنید که SDK در حالت توسعه‌دهنده (developer mode) نباشد (metrix_developer_mode=false).
اتصال شبکه را بررسی کنید.
پیکربندی ProGuard را بررسی کنید که شامل -keep class ir.metrix.** { *; } باشد.

2. مشکلات مقداردهی اولیه SDK

مشکل: “Unable to find appId in application manifest”

علت: ir.metrix.APPLICATION_ID metadata گم شده یا نامعتبر است.

راه‌حل:


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

مشکل: “Unable to find apiKey in application manifest”

علت: ir.metrix.API_KEY metadata گم شده یا نامعتبر است.

راه‌حل:


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

مشکل: “Running in developer-mode; Metrix won’t function”

علت: حالت توسعه‌دهنده فعال است.

راه‌حل: metrix_developer_mode=false را در مانیفست تنظیم کنید یا آن را به‌طور کامل حذف کنید:


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

مشکل: “Unable to retrieve FCM initialization values”

علت: google-services.json پیدا نشد یا اعمال نشده است.

راه‌حل:

google-services.json را از Firebase Console دانلود کنید.
آن را در دایرکتوری app/ قرار دهید (نه app/src/).
اطمینان حاصل کنید که پلاگین com.google.gms.google-services در build.gradle اعمال شده است.

3. ایونت ها در داشبورد ظاهر نمی‌شوند

مشکل: ایونت ها نمایش داده نمی‌شوند.

دلایل احتمالی:

ایونت در پنل Metrix ثبت نشده است.
عدم اتصال به اینترنت/آفلاین بودن.
SDK غیرفعال است (sdkEnabled: false).
ویژگی‌های ایونت از محدودیت‌های اندازه فراتر رفته‌اند.

راه‌حل‌ها:

ایونت ها را در بخش Event Management پنل Metrix ثبت کنید.
یا از newEventByName() برای ایجاد خودکار ایونت ها استفاده کنید.
اتصال شبکه را بررسی کنید (در adb logcat به دنبال “offline” بگردید).
بررسی کنید که هر کلید/مقدار ویژگی ≤ 512 بایت باشد.
بررسی کنید که حداکثر 50 ویژگی در هر ایونت وجود داشته باشد.

مشکل: ایونت های درآمدی با مبلغ صفر نمایش داده می‌شوند.

علت: نوع داده یا واحد پول نادرست است.

راه‌حل:

اطمینان حاصل کنید که درآمد Double است (نه String یا Integer).
واحد پول صحیح را مشخص کنید: RevenueCurrency.IRR, USD, یا EUR.
بررسی کنید که مقدار > 0 باشد.

4. مشکلات ردیابی کاربر

مشکل: شناسه کاربری ذخیره نمی‌شود.

علت: قبل از مقداردهی اولیه ماژول analytics فراخوانی شده است.

راه‌حل:

بررسی کنید که ماژول analytics گنجانده شده باشد: implementation 'ir.metrix.analytics:metrix:2.8.1'.
شناسه کاربری را پس از راه‌اندازی کامل اپلیکیشن تنظیم کنید، نه در Application.onCreate().
برای مشکلات زمان‌بندی از CPU executor استفاده کنید:


    MetrixAnalytics.User.setUserCustomId("userId");

مشکل: ویژگی‌های سفارشی ظاهر نمی‌شوند.

علت: از محدودیت‌های اندازه فراتر رفته یا انواع نامعتبر هستند.

راه‌حل:

حداکثر 50 ویژگی سفارشی برای هر کاربر.
هر کلید ≤ 512 بایت، هر مقدار ≤ 512 بایت باشد.
از انواع پشتیبانی شده استفاده کنید: String, Number, Boolean.
برای تاریخ‌ها از ISO 8601 استفاده کنید: "2024-11-20T11:24:03.000Z".

5. پوش نوتیفیکیشن‌ها دریافت نمی‌شوند

مشکل: نوتیفیکیشن‌ها نمایش داده نمی‌شوند.

دلایل احتمالی:

google-services.json پیکربندی نشده است.
اعتبارسنجی FCM در پنل Metrix وارد نشده است.
شناسه کاربری تنظیم نشده است.
نوتیفیکیشن‌ها غیرفعال شده‌اند.
توکن دستگاه به Metrix ارسال نشده است.

راه‌حل‌ها:

google-services.json را بررسی کنید:


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

اعتبارسنجی Firebase را در پنل Metrix بررسی کنید:
- به Workspace → Settings → Channel Integration → App Push بروید.
- اعتبارسنجی Firebase را آپلود کنید.
شناسه کاربری را تنظیم کنید:


MetrixAnalytics.User.setUserCustomId("userId");

بررسی کنید که نوتیفیکیشن‌ها فعال باشند:


boolean enabled = MetrixNotification.isNotificationEnable();

مشکل: سرویس Firebase پیدا نشد.

علت: سرویس اعلام نشده یا پلاگین اعمال نشده است.

راه‌حل:

به 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>

پلاگین را در build.gradle بررسی کنید:


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

6. پیام‌های درون برنامه‌ای نمایش داده نمی‌شوند

مشکل: پیام‌های درون برنامه‌ای نمایش داده نمی‌شوند.

دلایل احتمالی:

بارگذاری خودکار بدون بارگذاری دستی غیرفعال شده است.
پیام‌رسانی متوقف شده است.
ماژول مقداردهی اولیه نشده است.

راه‌حل‌ها:

اگر بارگذاری خودکار غیرفعال است، به‌صورت دستی فراخوانی کنید:


MetrixNotification.loadInAppMessages();

بررسی کنید که متوقف نشده باشد:


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

مقداردهی اولیه را بررسی کنید:


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

7. مشکلات دیپ لینک

مشکل: دیپ لینک‌ها کار نمی‌کنند.

دلایل احتمالی:

فیلتر intent پیکربندی نشده است.
نام scheme مطابقت ندارد.
(listener) تنظیم نشده است.

راه‌حل‌ها:

فیلتر intent را در مانیفست بررسی کنید:


<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>

listener دیپ لینک را تنظیم کنید:


MetrixAttribution.setOnDeeplinkResponseListener(deeplink -> {
    handleDeeplink(deeplink);
    return false; // خودتان مدیریت کنید
});

در onCreate و 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);
}

مشکل: دیپ لینک‌های deferred کار نمی‌کنند.

علت: اپلیکیشن از طریق Google Play یا کافه بازار نصب نشده است.

راه‌حل:

دیپ لینک‌های deferred فقط با Google Play و کافه بازار کار می‌کنند.
اپلیکیشن را قبل از تست دیپ لینک‌های deferred از فروشگاه نصب کنید.
listener را قبل از کلیک روی دیپ لینک تنظیم کنید:


MetrixAttribution.setOnDeeplinkResponseListener(deeplink -> {
    return true; // اجازه دهید Metrix مدیریت کند
});

8. مشکلات یکپارچه‌سازی WebView

مشکل: WebView داده‌ها را همگام‌سازی نمی‌کند.

علت: bridge ثبت نشده یا از قبل ثبت نشده است.

راه‌حل:

bridge را در onCreate() ثبت کنید:


MetrixAnalyticsBridge.registerAndGetInstance(webView);

جاوااسکریپت را فعال کنید:


webView.getSettings().setJavaScriptEnabled(true);

فقط در onDestroy() ثبت (unregister) را انجام دهید:


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

مشکل: متدهای جاوااسکریپت در دسترس نیستند.

علت: bridge قبل از بارگذاری URL مقداردهی اولیه نشده است.

راه‌حل:


// bridge را قبل از بارگذاری URL ثبت کنید
MetrixAnalyticsBridge.registerAndGetInstance(webView);
 
// سپس URL را بارگذاری کنید
webView.loadUrl("file:///android_asset/page.html");

9. مشکلات ابهام‌زدایی ProGuard/R8

مشکل: ClassNotFoundException یا NoSuchMethodError در زمان اجرا.

علت: کلاس‌ها توسط ProGuard/R8 مبهم شده‌اند.

راه‌حل:

به proguard-rules.pro اضافه کنید:


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

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

برای Gradle 8 به بالا:

به build.gradle اپلیکیشن اضافه کنید:


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

10. مشکلات ردیابی نشست (Session Tracking)

مشکل: listeners نشست فراخوانی نمی‌شوند.

علت: ماژول analytics مقداردهی اولیه نشده است.

راه‌حل:

بررسی کنید که analytics گنجانده شده باشد: implementation 'ir.metrix.analytics:metrix:2.8.1'.
listeners را در اوایل چرخه حیات اکتیویتی تنظیم کنید.
بررسی کنید که اپلیکیشن در حالت توسعه‌دهنده نباشد.

مشکل: شناسه نشست بلافاصله در دسترس نیست.

علت: مشکل زمان‌بندی در طول مقداردهی اولیه.

راه‌حل:

شناسه نشست در پایان onCreate() در دسترس است.
listener را قبل از هر ایونت ی تنظیم کنید.
از setSessionIdListener() در main activity استفاده کنید.

11. مشکلات اتریبیوشن (Attribution)

مشکل: داده‌های اتریبیوشن دریافت نمی‌شوند.

دلایل احتمالی:

ماژول اتریبیوشن مقداردهی اولیه نشده است.
مشکلات اتصال شبکه.
کاربر ارگانیک است (بدون کمپین).

راه‌حل‌ها:

بررسی کنید که ماژول گنجانده شده باشد: implementation 'ir.metrix.attribution:metrix:2.8.1'.
اتصال شبکه را بررسی کنید.
24-48 ساعت برای اتریبیوشن سمت سرور منتظر بمانید.
پنل Metrix را برای پیکربندی ترکر بررسی کنید.

مشکل: ترکر پیش‌فرض کار نمی‌کند.

علت: اپلیکیشن از فروشگاه رسمی نصب شده است.

راه‌حل:

هرگز از ترکر پیش‌فرض در Google Play یا کافه بازار استفاده نکنید.
ترکر پیش‌فرض فقط برای توزیع مستقیم (وب‌سایت، نصب جانبی) است.
قبل از انتشار در فروشگاه‌ها آن را حذف کنید.

12. مدیریت توکن FCM

توکن‌های FCM چه زمانی منقضی می‌شوند؟

توکن‌های ثبت FCM زمان انقضای ثابتی ندارند. آنها تا زمانی که موارد زیر اتفاق بیفتد معتبر باقی می‌مانند:

اپلیکیشن حذف/دوباره نصب شود.
داده‌های اپلیکیشن پاک شوند.
دستگاه به تنظیمات کارخانه بازگردانده شود.
گوگل توکن‌ها را چرخش دهد (به‌روزرسانی امنیتی).
کاربر از سیستم خارج شود.
به‌روزرسانی عمده سیستم عامل دستگاه یا Play Services.

بهترین شیوه‌ها:

توکن را به صورت دوره‌ای (ماهانه) به‌روز کنید.
با به‌روزرسانی اپلیکیشن، توکن جدید درخواست کنید.
بازخوانی توکن را در onNewToken() مدیریت کنید.

13. مشکلات شبکه و آفلاین

مشکل: “Parcel successfully sent” ظاهر نمی‌شود.

علت: آفلاین بودن یا مسدود شدن شبکه.

راه‌حل‌ها:

اتصال اینترنت را بررسی کنید.
بررسی کنید که دستگاه دارای شبکه فعال باشد.
بررسی کنید که فایروال سرورهای Metrix را مسدود نمی‌کند.
بررسی کنید که فایروال API به HTTPS خروجی اجازه می‌دهد.
SDK ایونت ها را در حالت آفلاین صف‌بندی می‌کند و در حالت آنلاین ارسال می‌کند.

14. پیام‌های خطای رایج

خطا	علت	راه‌حل
`Unable to find Metrix core component`	ماژول هسته گم شده یا در مقداردهی اولیه شکست خورده است	وابستگی هسته را اضافه کنید، مقداردهی اولیه را بررسی کنید
`Metrix component not available`	مقداردهی اولیه ماژول شکست خورده است	لاگ‌ها را برای خطای خاص بررسی کنید، مانیفست را تأیید کنید
`WorkManager is needed but not initialized`	نوتیفیکیشن بدون WorkManager	WorkManager را اضافه کنید یا بارگذاری خودکار را فعال کنید
`Unable to obtain the Metrix component`	SDK مقداردهی اولیه نشده است	تمام وابستگی‌ها را بررسی کنید، مانیفست را تأیید کنید
`Initialization will not proceed`	مؤلفه اصلی در دسترس نیست	قوانین ProGuard را بررسی کنید، وابستگی‌ها را تأیید کنید

15. Getting Help

لاگ‌های اشکال‌زدایی:


adb logcat | grep Metrix

مانیفست را بررسی کنید:

ir.metrix.APPLICATION_ID تنظیم شده باشد.
ir.metrix.API_KEY تنظیم شده باشد.
metrix_developer_mode true نباشد.
تمام سرویس‌ها/گیرنده‌های مورد نیاز اعلام شده باشند.

وابستگی‌ها را تأیید کنید:


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. مشکلات عملکرد

مشکل: تأخیر در راه‌اندازی اپلیکیشن.

علت: مقداردهی اولیه سنگین در رشته اصلی (main thread).

راه‌حل:

SDK از رشته‌های پس‌زمینه (background threads) برای عملیات سنگین استفاده می‌کند.
پیش-مقداردهی اولیه در رشته اصلی (~10ms) اتفاق می‌افتد.
پس-مقداردهی اولیه در رشته CPU.
از حالت توسعه‌دهنده برای تست بدون شبکه استفاده کنید.

مشکل: استفاده زیاد از حافظه.

علت: صف‌های ایونت بزرگ یا listener پاک نشده.

راه‌حل:

listener را در صورت عدم نیاز حذف کنید.
صف ایونت را به‌طور دوره‌ای پاک کنید.
به دنبال نشت حافظه (memory leaks) در listener باشید.
از Android Profiler برای نظارت استفاده کنید.