Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.
مستندات فنیAndroidGetting Started

شروع به کار

می‌توانید نمونه پروژه پیاده‌سازی متریکس را اینجا  مشاهده کنید.

نصب و راه‌اندازی

با دنبال کردن مراحل زیر، کتابخانه متریکس در اپلیکیشن شما فعال و آماده استفاده خواهد شد:

1. بررسی نسخه‌های Android SDK و Compile

اطمینان حاصل کنید که فایل build.gradle اپلیکیشن شما نسخه‌های مناسب Android SDK را پیکربندی کرده است:

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

2. پیکربندی مخزن Maven

مخزن mavenCentral را به فایل build.gradle پروژه خود در بخش allprojects اضافه کنید:

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

3. اضافه کردن وابستگی‌های کتابخانه Metrix

وابستگی مربوط به کتابخانه متریکس را در قسمت dependencies فایل build.gradle اپلیکیشن خود اضافه کنید:(با توجه به استفاده هرکدام از کتابخانه‌های آنالیتیکس یا اتریبیوشن آنها را اضافه کنید)

// 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. پیکربندی App ID و API Key در AndroidManifest.xml

شناسه اپلیکیشن Metrix (app id) و کلید API (api key) را در فایل AndroidManifest.xml اپلیکیشن خود قرار دهید:

<manifest>
  <application>
 
    ...
 
    <!-- خطوط زیر را اضافه کنید و YOUR_APP_ID را جایگزین نمایید -->
    <meta-data
        android:name="ir.metrix.APPLICATION_ID"
        android:value="YOUR_APP_ID" />
 
    <!-- خطوط زیر را اضافه کنید و YOUR_API_KEY را جایگزین نمایید -->
    <meta-data
        android:name="ir.metrix.API_KEY"
        android:value="YOUR_API_KEY" />
  </application>
</manifest>

این مقادیر را کجا پیدا کنید:

  • YOUR_APP_ID: شناسه اپلیکیشن شما که از پنل Metrix دریافت کرده‌اید.
  • YOUR_API_KEY: کلید API شما که از پنل Metrix دریافت کرده‌اید.

5. بررسی مجوزهای لازم

اطمینان حاصل کنید که مجوزهای زیر در مانیفست اپلیکیشن شما گنجانده شده‌اند. ماژول اصلی این مجوزها را به‌طور خودکار شامل می‌شود، اما در مانیفست نهایی ادغام شده (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>

مجوزهای اضافی برای ماژول‌های خاص:

در صورت استفاده از ماژول Notification:

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

6. پیکربندی ProGuard/R8 (برای Gradle 8 به بالا)

اگر از Gradle نسخه 8 یا بالاتر استفاده می‌کنید، موارد زیر را به فایل پیکربندی ProGuard (proguard-rules.pro) خود اضافه کنید:

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

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

ماژول اصلی قبلاً از طریق proguard-consumer-common.pro شامل قوانین ProGuard مصرف‌کننده است، بنابراین اینها اغلب به‌طور خودکار در بیلد شما ادغام می‌شوند.

پیکربندی اختیاری

فعال کردن تایید امضای SDK

برای افزایش امنیت کتابخانه، تایید امضای SDK را فعال کنید:

  1. SDK Signature را در پنل Metrix خود فعال کنید.
  2. شناسه امضا را از ستون Encoded در پنل خود بازیابی کنید.
  3. امضا را به مانیفست اپلیکیشن خود اضافه کنید:
Metrix.setSignature("YOUR_SIGNATURE");

کاهش حجم کتابخانه

برای کاهش حجم APK با حذف کتابخانه‌های بومی (native libraries)، موارد زیر را به فایل build.gradle اپلیکیشن خود اضافه کنید:

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

فعال کردن حالت توسعه‌دهنده (Developer Mode)

می‌توانید کتابخانه Metrix را در طول توسعه و تست غیرفعال کنید تا آمار و ایونت ها ثبت نشوند.

متادیتای زیر را به فایل AndroidManifest.xml اپلیکیشن خود اضافه کنید:

<manifest>
  <application>
 
    ...
 
    <!-- خطوط زیر را اضافه کنید -->
    <meta-data
        android:name="metrix_developer_mode"
        android:value="true" />
  </application>
</manifest>

استفاده از Build Variants: علاوه بر این، با استفاده از manifestPlaceholders  در اندروید، می‌توانید این مقدار را در فایل gradle اپلیکیشن خود برای انواع بیلد (build variants) مختلف مدیریت کنید. در مثال زیر، کتابخانه Metrix در واریانت “develop” غیرفعال و در واریانت “release” فعال خواهد شد:

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

پس از مقداردهی اولیه، می‌توانید از APIهای عمومی زیر از کلاس Metrix استفاده کنید:

// تنظیم امضای SDK برای احراز هویت
Metrix.setSignature(String signature);
 
// تنظیم یک listener برای اطلاع از تغییرات user ID
Metrix.setUserIdListener(UserIdListener listener);
 
// تنظیم یک user ID سفارشی برای کاربر شما
Metrix.setUserCustomId(String id);
 
// حذف user ID سفارشی
Metrix.deleteUserCustomId();

یکپارچه‌سازی WebView

SDK متریکس از یکپارچه‌سازی جاوااسکریپت در محیط‌های WebView پشتیبانی می‌کند. تمام فعالیت‌های متریکس در سطح native انجام می‌شوند و محتوای وب از طریق یک bridge با آن ارتباط برقرار می‌کند.

مراحل راه‌اندازی

  1. جاوااسکریپت را در WebView خود فعال کنید:
webView.getSettings().setJavaScriptEnabled(true);
  1. bridge متریکس را برای ماژول‌هایی که استفاده می‌کنید ثبت کنید:
MetrixAnalyticsBridge.registerAndGetInstance(webView);
MetrixAttributionBridge.registerAndGetInstance(webView);
  1. اگر نیاز به تغییر WebView دارید، bridge را به‌روزرسانی کنید:
MetrixBridge.setWebView(newWebView);
  1. هنگام از بین بردن WebView یا activity، ثبت (unregister) را انجام دهید:
@Override
protected void onDestroy() {
    MetrixAnalyticsBridge.unregister();
    MetrixAttributionBridge.unregister();
    super.onDestroy();
}

مثال کامل WebView

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());
 
        // ثبت bridgeهای Metrix
        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();
    }
}

یکپارچه‌سازی جاوااسکریپت

به این ترتیب، کتابخانه Metrix با موفقیت در اپلیکیشن شما فعال شده است و رابط جاوااسکریپت Metrix به عنوان پل ارتباطی بین کتابخانه Metrix و صفحات بارگذاری شده شما در webview عمل خواهد کرد.

برای تعامل با کتابخانه Metrix و استفاده از ویژگی‌های آن، مانند ارسال ایونت ها، فایل جاوااسکریپت Metrix را در فایل HTML خود وارد کنید. این فایل در پوشه assets قرار دارد و می‌توانید آن را در نمونه پیاده‌سازی مشاهده کنید . آن را به صورت زیر وارد کنید:

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

برای فایل‌های جاوااسکریپت و مثال‌های استفاده، به نمونه پیاده‌سازی  مراجعه کنید.

پس از وارد کردن، می‌توانید متدهای MetrixAnalytics و MetrixAttribution را مستقیماً از کد جاوااسکریپت خود فراخوانی کنید.

عیب‌یابی

مقداردهی اولیه SDK با شکست مواجه می‌شود

علائم: اپلیکیشن هنگام راه‌اندازی کرش می‌کند یا قابلیت‌های Metrix در دسترس نیستند.

دلایل:

  • ir.metrix.APPLICATION_ID در مانیفست وجود ندارد یا نامعتبر است.
  • ir.metrix.API_KEY در مانیفست وجود ندارد یا نامعتبر است.
  • مشکلات پیکربندی ProGuard (کلاس‌ها مبهم شده‌اند/حذف شده‌اند).
  • metrix_developer_mode فعال است.

راه‌حل‌ها:

  1. بررسی کنید که APPLICATION_ID و API_KEY به درستی در AndroidManifest.xml تنظیم شده باشند.
  2. بررسی کنید که قوانین ProGuard شما شامل: -keep class ir.metrix.** { *; } باشد.
  3. لاگ‌کت (logcat) را برای پیام‌های خطای خاص از تگ Metrix یا MetrixInit بررسی کنید.
  4. اگر می‌خواهید SDK کار کند، حالت توسعه‌دهنده را غیرفعال کنید.

مجوز AD_ID گم شده است

علائم: هشدار بیلد یا زمان اجرا (runtime warnings) درباره مجوز AD_ID.

راه‌حل: اطمینان حاصل کنید که مانیفست شما شامل موارد زیر است:

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

برای مثال‌های کامل و کاربردی، به نمونه پیاده‌سازی  مراجعه کنید.

AndroidTracking Users