شروع

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

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

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

۱. در فایل build.gradle اپلیکیشن خود، اطمینان حاصل کنید که compileSdkVersion بزرگ‌تر یا مساوی ۳۱ باشد.

android {
    compileSdkVersion 32 // >= 31
    // ...
}

۲. مخزن mavenCentral را در فایل build.gradle مربوط به پروژه خود در قسمت allprojects اضافه کنید:

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

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

 implementation 'ir.metrix.attribution:metrix:2.6.7'
 implementation 'ir.metrix.analytics:metrix:2.6.7'
 implementation 'ir.metrix.notification:metrix:2.6.7' //(Optional)

۴. شناسه اپلیکیشن ( app id ) و کلید ای‌پی‌آی ( 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: شناسه اپلیکیشن شما که از پنل متریکس دریافت می‌کنید. YOUR_API_KEY: کلید ای‌پی‌آی شما که از پنل متریکس دریافت می‌کنید.

توجه: از بودن این پرمیشن در مانیفست نهایی (merged manifest) پروژه اطمینان حاصل کنید

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

توجه: اگر از نسخه گردل ۸ یا بالاتر استفاده میکنید به فایل پروگارد خود کد زیر را اضافه کنید:

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

مراحل اختیاری

افزایش امنیت کتابخانه

شما باید با فعال‌سازی قابلیت sdk signature در پنل خود و دریافت شناسه‌ مخصوص خود، امنیت ارتباط و انتقال اطلاعات را افزایش داده و از سلامت آمار اپلیکیشن خود اطمینان بیشتری حاصل کنید.

پس از فعال‌سازی sdk signature در پنل خود، از ستون Encoded شناسه مربوط به signature را دریافت و به شکل زیر در برنامه خود قرار دهید:

    MetrixAttribution.setSignature("YOUR_SIGNATURE");

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

برای کم کردن حجم apk تگ ‘packaging’ را به فایل build.gradle در پوشه app اضافه کنید

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

غیرفعال‌کردن کتابخانه در هنگام توسعه

شما ‌می‌توانید کتابخانه متریکس را در زمان توسعه و تست‌، و به طور کلی بسته به نیاز خود در build‌های خاصی از اپلیکیشن، غیرفعال کنید. به این ترتیب آماری از نصب‌ها و ایونت‌های احتمالی اپلیکیشن شما در این buildها در متریکس به ثبت نخواهد رسید.

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

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

همچنین با استفاده از manifestPlaceholders  در اندروید، می‌توانید این مقدار را در فایل gradle اپلیکیشن خود، برای build varientهای مختلف مدیریت کنید.

در مثال زیر، کتابخانه متریکس در حالت develop غیرفعال و در حالت release فعال خواهد بود:

<manifest>
 
  ...
 
  <application>
 
    ...
 
    <meta-data
        android:name="metrix_developer_mode"
        android:value="${metrixDisabled}" />
 
  </application>
</manifest>

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

پیاده‌سازی در Webview

پیاده‌سازی متریکس در Webview بر پایه SDK اندروید متریکس میباشد. تمام فعالیت های متریکس در سطح native صورت میگیرد و محتوای وب از طریق پل(Bridge) با SDK اندروید در ارتباط است.

پس از انجام مراحل اولیه:

• متد webView.getSettings().setJavaScriptEnabled(true) را جهت فعال‌سازی javascript در webview فراخوانی کنید.
• متد MetrixBridge.registerAndGetInstance(webview) را جهت فعال‌سازی واسط متریکس میان کتابخانه و webview فراخوانی کنید.
• در صورت نیاز به تغییر webview می‌توانید متد MetrixBridge.setWebView(newWebview) را فراخوانی کنید.
• جهت غیرفعال کردن واسط، متد MetrixBridge.unregister() را فراخوانی کنید.

با انجام این مراحل، کلاس Activity شما مشابه قطعه کد زیر خواهد بود:

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

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

جهت ارتباط با کتابخانه متریکس و استفاده از امکانات آن مانند ارسال رویداد، در فایل HTML خود، فایل Javascript متریکس را که در پوشه assets نمونه پیاده‌سازی شده  قرار دارد به صورت زیر import کنید:

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

به این ترتیب می‌توانید در فایل HTML خود متدهای MetrixAnalytics یا MetrixAttribution را فراخوانی کنید.