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

راه‌اندازی کتابخانه در اپلیکیشن اندروید

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

۱. در فایل 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'

۴. شناسه اپلیکیشن ( 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"]
        }
    }
}

امکانات و قابلیت‌ها

رویداد (event)

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

در کتابخانه متریکس دو نوع رویداد قابل تعریف است:

سفارشی (custom): وابسته به منطق اپلیکیشن شما و تعاملی که کاربر با اپلیکیشن شما دارد می‌توانید رویدادهای سفارشی خود را در قالبی که در ادامه شرح داده خواهد شد بسازید و ارسال کنید.
درآمدی (revenue): نوع خاصی از رویدادهای سفارشی قابل تعریف است که مربوط به میزان درآمد کسب شده در اپلیکیشن شما می‌باشد و دارای یک مقدار قابل اندازه‌گیری از جنس درآمد مالی است.

ساختن یک رویداد سفارشی

برای ساخت یک رویداد سفارشی در ابتدا در پنل خود از قسمت مدیریت رویدادها، رویداد موردنظر خود را ثبت کنید و نامک (slug) آن را به عنوان نام رویداد در اپلیکیشن استفاده کنید.

وقوع رویداد به دو صورت می‌تواند ثبت شود:

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


    MetrixAnalytics.newEvent("my_event_slug");

۲. ثبت رویداد با استفاده از نام دلخواه: (در این صورت ایونت با نامک (slug) منحصربه‌فرد به صورت اتوماتیک در پنل ساخته میشود)


    MetrixAnalytics.newEventByName("my_event_name");

توجه: ثبت رویداد میتواند به همراه تعداد دلخواه attribute مربوط به آن باشد:

به عنوان مثال فرض کنید در یک برنامه خرید آنلاین می‌خواهید یک رویداد سفارشی بسازید:


    Map<String, Object> attributes = new HashMap<>();
    attributes.put("first_name", "Ali");
    attributes.put("last_name", "Bagheri");
    attributes.put("manufacturer", "Nike");
    attributes.put("product_name", "shirt");
    attributes.put("type", "sport");
    attributes.put("size", "large");
    attributes.put("purchase_date", "2024-11-20T11:24:03.000Z"); // use ISO 8601 to consider this attribute as s a date
 
    MetrixAnalytics.newEvent("purchase_event_slug", attributes);
    MetrixAnalytics.newEventByName("purchase_event_name", attributes);

ورودی‌های متد newEvent در این حالت، بدین شرح هستند:

ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
ورودی دوم: یک Map<String, Object> که ویژگی‌های یک رویداد را مشخص می‌کند.

توجه: هر رویداد می‌تواند حداکثر ۵۰ attribute داشته باشد که طول key و value آن حداکثر ۵۱۲ بایت می‌باشد.

ساختن رویداد درآمدی

با استفاده از این تابع می‌توانید یک رویداد درآمدی بسازید. برای این کار در ابتدا در پنل خود از قسمت مدیریت رویدادها، رویداد موردنظر خود را ثبت کنید و نامک (slug) آن را به عنوان نام رویداد در اپلیکیشن استفاده کنید.


    MetrixAnalytics.newRevenue("my_event_slug", 12000, RevenueCurrency.IRR);

ورودی‌های متد newRevenue بدین شرح هستند:

ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
ورودی دوم: یک مقدار عددی است که همان میزان درآمد است.
ورودی سوم: واحد پول مورد استفاده است و می‌تواند سه مقدار RevenueCurrency.IRR (پیش‌فرض) یا RevenueCurrency.USD و یا RevenueCurrency.EUR را داشته باشد.

یا با استفاده از نام دلخواه رویداد درآمدی را فراخوانی کنید (در این صورت ایونت با نامک (slug) منحصربه‌فرد به صورت اتوماتیک در پنل ساخته میشود)


    MetrixAnalytics.newRevenueByName("my_event_name", 12000, RevenueCurrency.IRR);

شناساندن کاربر به متریکس و ساخت User (مختص سرویس اتومیشن)

برای شناساندن کاربری که در حال استفاده از وبسایت شماست به سرورهای متریکس با هدف اینکه متریکس تشخیص دهد کدام کاربری که در حال استفاده از وبسایت شماست اکشن‌های دریافتی را انجام می‌دهد باید متد زیر را قبل فراخوانی سایر متدها صدا بزنید. این متد یک User سمت سرورهای متریکس ساخته که از طریق پنل کاربری متریکس در قسمت User Lookup قابل دسترس است.


    MetrixAnalytics.User.setUserCustomId("userId"); // call when user tries to login in your system and set userId value that user already knows in your system
    MetrixAnalytics.User.deleteUserCustomId(); // call when your user goes to logout in your system

به‌روزرسانی اطلاعات User (مختص سرویس اتومیشن)

با استفاده از متدهای زیر می‌توانید اطلاعات User های موجود در User Lookup را به‌روز‌رسانی کنید.


    Map<String, Object> attributes = new HashMap<>();
    attributes.put("manufacturer", "Nike");
    attributes.put("birth_date", "2024-11-20T11:24:03.000Z"); // use ISO 8601 to consider this attribute as s a date
    MetrixAnalytics.User.setCustomAttribute(attributes);

با استفاده از توابع زیر میتوانید Attribute های از پیش تعیین شده را به کاربر اختصاص دهید:


MetrixAnalytics.User.setFirstName("userFirstName");
MetrixAnalytics.User.setLastName("userLastName");
MetrixAnalytics.User.setPhoneNumber("phoneNumber");
MetrixAnalytics.User.setHashedPhoneNumber("hashedPhoneNumber");
MetrixAnalytics.User.setEmail("email");
MetrixAnalytics.User.setHashedEmail("hashedEmail");
MetrixAnalytics.User.setCountry("country");
MetrixAnalytics.User.setCity("city");
MetrixAnalytics.User.setRegion("region");
MetrixAnalytics.User.setLocality("locality");
MetrixAnalytics.User.setGender(gender); // gender value could be "MALE" , "FEMALE" or "OTHER"
MetrixAnalytics.User.setBirthday(birthday); // birthday value type should be 'Long'
MetrixAnalytics.User.setChannelEnabled(channel);
MetrixAnalytics.User.setChannelDisabled(channel);

توجه: هر رویداد می‌تواند حداکثر ۵۰ attribute داشته باشد که طول key و value آن حداکثر ۵۱۲ بایت می‌باشد.

دریافت شناسه دستگاه‌های متریکس

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


    MetrixAnalytics.setUserIdListener(new UserIdListener() {
        @Override
        public void onUserIdReceived(String metrixUserId) {
            // your logic
        }
    });

یا


    MetrixAttribution.setUserIdListener(new UserIdListener() {
        @Override
        public void onUserIdReceived(String metrixUserId) {
            // your logic
        }
    });

نکته: شناسه متریکس زمانی در اختیار شما قرار می‌گیرید که دستگاه توسط سرویس متریکس شناسایی شده باشد.

نشست (session)

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

شناسه نشست

کتابخانه متریکس برای هر نشست یک شناسه منحصر به فرد تولید می‌کند که می‌توانید این شناسه را دریافت نمایید. برای دریافت این شناسه متد زیر را فراخوانی کنید.


    MetrixAnalytics.setSessionIdListener(new SessionIdListener() {
        @Override
        public void onSessionIdChanged(String sessionId) {
            // your logic
        }
    });

شماره نشست جاری

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


    MetrixAnalytics.setSessionNumberListener(new SessionNumberListener() {
        @Override
        public void onSessionNumberChanged(String sessionNumber) {
            // your logic
        }
    });

(Uninstall) شمارش پاک کردن اپلیکیشن

متریکس برای شمارش پاک شدن اپلیکشن شما از ارسال silent push استفاده می‌کند.

شما باید برای استفاده از این ابزار از Firebase Cloud Messaging (FCM) استفاده نمایید.

مراحل زیر را دنبال نمایید:

وارد کردن Push Credentials پروژه فایربیس در پنل متریکس

در پنل متریکس به تنظیمات اپلیکیشن خود رفته و سربرگ Uninstall Config را انتخاب کنید. تنظیمات پروژه فایربیس خود را در فیلد های مربوطه وارد کنید و با کلیک بر روی دکمه save مقادیر را ذخیره کنید.

برای دریافت فایل Service account Data می‌توانید از کنسول فایربیس خود در بخش project settings در سربرگ Service Accounts دکمه generate new private key را بزنید.

push configuration

فعال‌سازی شمارش حذف

پس از وارد کردن تنظیمات در پنل متریکس، با روشن کردن toggle مربوطه، شمارش حذف را فعال کنید.

ارسال توکن پوش در اپلیکیشن

پس از پیاده‌سازی FCM در اپلیکیشن خود، به هنگام دریافت توکن پوش‌نوتیفیکیشن، با فراخوانی متد زیر، این توکن را برای متریکس ارسال نمایید:


    MetrixAttribution.setPushToken("pushToken");

دریافت اطلاعات کمپین

با استفاده از متد زیر، می‌توانید اطلاعات کمپین تبلیغاتی که در ترکر خود در پنل قرار داده‌اید را دریافت کنید.


    MetrixAttribution.setOnAttributionChangedListener(new OnAttributionChangeListener() {
    @Override
        public void onAttributionChanged(AttributionData attributionData) {
            //TODO
        }
    });

مدل AttributionData اطلاعات زیر را در اختیار شما قرار می‌دهد.


attributionData.getAcquisitionAd() // نام تبلیغ
attributionData.getAcquisitionAdSet() // گروه تبلیغاتی
attributionData.getAcquisitionCampaign() // کمپین تبلیغاتی
attributionData.getAcquisitionSource() // شبکه تبلیغاتی
attributionData.getAcquisitionSubId() // زیرگروه تبلیغاتی
attributionData.getAttributionStatus() // وضعیت کاربر در کمپین را مشخص می‌کند

مقدار AttributionStatus شامل یکی از موارد زیر است:

ATTRIBUTED اتربیوت شده
NOT_ATTRIBUTED_YET هنوز اتربیوت نشده
ATTRIBUTION_NOT_NEEDED نیاز به اتربیوت ندارد
UNKNOWN حالت ناشناخته

Deep Linking

اگر شما از ترکر هایی که دیپ‌لینک در آنها فعال است استفاده کنید، می‌توانید اطلاعات url دیپ‌لینک و محتوای آن را دریافت کنید. دستگاه بر اساس نصب بودن اپلیکیشن (سناریو استاندارد) یا نصب نبودن اپلیکیشن (سناریو deferred) واکنش نشان می‌دهد. در صورت نصب بودن اپلیکیشن شما اطلاعات دیپ‌لینک به اپلیکیشن شما ارسال می‌شود.

پلتفرم اندروید به صورت اتوماتیک سناریو deferred را پشتیبانی نمی‌کند. در این صورت متریکس سناریو مخصوص به خود را دارد تا بتواند اطلاعات دیپ‌لینک را به اپلیکیشن ارسال کند.

سناریو استاندارد

اگر کاربران شما اپلیکیشن شما را نصب داشته باشند و شما بخواهید بعد از کلیک بر روی لینک دیپ‌لینک صفحه خاصی از اپلیکیشن شما باز شود ابتدا باید یک scheme name یکتا انتخاب کنید. سپس آن را باید به اکتیویتی که قصد دارید در صورت کلیک بر روی دیپ‌لینک اجرا شود نسبت دهید. برای این منظور به فایل AndroinManifest.xml رفته و بخش intent-filter را به اکتیویتی مورد نظر اضافه کنید همچنین scheme name مورد نظر خود را نیز قرار دهید. مانند زیر:


<activity
    android:name=".MainActivity"
    android:label="@string/app_name">
 
    <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>

اطلاعات دیپ‌لینک در اکتیویتی که آن را تعریف کردید توسط یک آبجکت Intent درمتد های onCreateو newIntent قابل دسترس است.


@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
 
    Intent intent = getIntent();
    Uri data = intent.getData();
}


@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
 
    Uri data = intent.getData();
}

سناریو deferred

این سناریو زمانی رخ می‌دهد که کاربر روی دیپ‌لینک کلیک می‌کند ولی اپلیکیشن شما را در زمان کلیک بر روی دستگاه خود نصب ندارد. در این حالت کاربر پس از کلیک، به Google Play هدایت می‌شود تا اپلیکیشن شما را نصب کند. با نصب اپلیکیشن، در اولین اجرا، اطلاعات دیپ‌لینک به اپلیکیشن داده می‌شود.

اگر شما قصد دارید که سناریو deferred را کنترل کنید می‌توانید از کالبک زیر استفاده نمایید:


    MetrixAttribution.setOnDeeplinkResponseListener(new OnDeeplinkResponseListener() {
        @Override
        public boolean launchReceivedDeeplink(Uri deeplink) {
            // ...
            if (shouldMetrixSdkLaunchTheDeeplink(deeplink)) {
                return true;
            } else {
                return false;
            }
        }
    });

بعد از این که متریکس اطلاعات دیپ‌لینک را از سرور خود دریافت کرد محتوای آن را به کالبک بالا پاس می‌دهد. اگر خروجی متد lunchReceivedDeeplink مقدار true باشد متریکس به صورت اتوماتیک سناریو استاندارد را اجرا می‌کند ولی اگر مقدار خروجی متد false باشد متریکس فقط اطلاعات را در این کالبک قرار می‌دهد تا شما بر اساس آن اکشن مورد نظر خود را انجام دهید.

توجه: سناریو deffered تنها در صورت نصب اپلیکیشن از طریق Google Play Store قابل اجرا می‌باشد.

مشخص کردن tracker پیش‌فرض

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

کاربرد این قابلیت برای زمانی است که قصد انتشار مستقیم فایل APK برنامه خود را دارید و می‌خواهید آمار نصب‌های برنامه از طریق این انتشار را در متریکس به تفکیک داشته باشید.

توجه: تحت هیچ شرایطی اپلیکیشن خود را با ترکر پیش‌فرض روی استور منتشر نکنید. در این صورت همه نصب‌های ارگانیک شما نیز در متریکس روی ترکر مذکور شمرده می‌شود.

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


<manifest>
 
  ...
 
  <application>
 
    ...
 
    <!-- خطوط زیر را اضافه کنید و شناسه را جایگزین نمایید -->
    <meta-data
        android:name="metrix_trackerToken"
        android:value="TOKEN" />
 
  </application>
</manifest>

تفکیک نصب‌های organic بر‌اساس استور‌های مختلف

اگر شما می‌خواهید اپلیکیشن خود را در استور های مختلف مانند کافه بازار، گوگل پلی و … منتشر کنید، می‌توانید مشاهده کنید که کاربر از کدام استور ( مثلا کافه بازار، گوگل پلی، مایکت، اول مارکت و وبسایت … ) اپلیکیشن را نصب کرده و منبع نصب‌های ارگانیک خود را شناسایی کنید.

برای این منظور، نیاز است که برای اپلیکیشن خود جهت انتشار در استورهای مختلف، بیلدهای جداگانه بسازید و در هر بیلد نام استور مربوط را تنظیم نمایید.

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


<manifest>
 
  ...
 
  <application>
 
    ...
 
    <!-- خطوط زیر را اضافه کنید و نام استور را جایگزین نمایید -->
    <meta-data
        android:name="metrix_storeName"
        android:value="YOUR_STORE_NAME" />
 
  </application>
</manifest>

پیاده‌سازی سرویس پوش نوتیفیکیشن

۱. برای شروع فایل google-services.json را از کنسول فایربیس دانلود کرده و در پروژه قرار دهید

همچنین نیاز به وارد کردن Push Credentials پروژه فایربیس در پنل متریکس می‌باشد

۲. وابستگی مربوط به کتابخانه متریکس را در قسمت dependencies فایل build.gradle اپلیکیشن خود اضافه کنید:


 implementation 'ir.metrix.notification:metrix:2.6.7'

توجه: در حال حاضر امکان دریافت نوتیفیکیشن صرفا برای کاربران شناخته شده در متریکس وجود دارد, برای این کار باید کاربر مورد نظر خصیصه customUserId را داشته باشد

۳. کلاس زیر را به اپلیکیشن خود اضافه کنید (به تغییرات مانیفست را هم اعمال کنید)


    class CustomFirebaseMessagingService: FirebaseMessagingService() {
        override fun onMessageReceived(message: RemoteMessage) {
            if (MetrixNotification.onMessageReceived(message)) return
            // here you can process your own fcm messages
        }
    }

۴. مقدار زیر را در فایل AndroidManifest.xml اپلیکیشن خود قرار دهید:


    <service
        android:name=".CustomFirebaseMessagingService"
        android:exported="false">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
      </intent-filter>
    </service>

۵. هنگام لاگین کاربر customUserId را مقدار دهی کرده و هنگام لاگ‌اوت آن را حذف کنید :


    MetrixAnalytics.User.setUserCustomId("yourId")


    MetrixAnalytics.User.deleteUserCustomId()

توجه: اگر میخواهید وابستگی firebase را در پروژه خود داشته باشید, مقادیر firebase-iid و firebase-messaging را exclude کنید مثال:


    implementation platform('com.google.firebase:firebase-bom:30.4.1') {
        exclude group: 'com.google.firebase', module: 'firebase-messaging'
        exclude group: 'com.google.firebase', module: 'firebase-iid'
    }

پیاده‌سازی پیام درون‌برنامه‌ای (in-app message)

در حالت پیش‌فرض اپلیکیشن با هربار باز شدن پیام‌ها را لود کرده و نشان میدهد

برای اینکه پیام‌ها را در صفحه دلخواه به کاربر نشان دهید:

۱. مقدار metrix_auto_load_in_app_messages را در فایل AndroidManifest.xml اپلیکیشن خود قرار دهید:


<manifest>
 
  ...
 
  <application>
 
    ...
 
    <meta-data
        android:name="metrix_auto_load_in_app_messages"
        android:value="false" />
 
  </application>
</manifest>

۲. سپس در جای مورد نظر متد زیر را فراخوانی کنید


Metrix.loadInAppMessages();

پیاده‌سازی متریکس در webview

پس از دریافت اشاره‌گر به Webview خود:

متد 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 را فراخوانی کنید.

امکانات و قابلیت‌ها

نشست (session)

شناسه نشست


MetrixAnalytics.setSessionIdListener(sessionId -> {
    //TODO
});

شماره نشست جاری


MetrixAnalytics.setSessionNumberListener(sessionNumber -> {
  //TODO
});

رویداد (event)

در کتابخانه متریکس دو نوع رویداد قابل تعریف است:

سفارشی (custom): وابسته به منطق اپلیکیشن شما و تعاملی که کاربر با اپلیکیشن شما دارد می‌توانید رویدادهای سفارشی خود را در قالبی که در ادامه شرح داده خواهد شد بسازید و ارسال کنید.
درآمدی (revenue): نوع خاصی از رویدادهای سفارشی قابل تعریف است که مربوط به میزان درآمد کسب شده در اپلیکیشن شما می‌باشد و دارای یک مقدار قابل اندازه‌گیری از جنس درآمد مالی است.

ساختن یک رویداد سفارشی

وقوع رویداد به دو صورت می‌تواند ثبت شود:

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


MetrixAnalytics.newEvent("my_event_slug");

۲. ثبت رویداد به همراه تعداد دلخواه attribute مربوط به آن:

به عنوان مثال فرض کنید در یک برنامه خرید آنلاین می‌خواهید یک رویداد سفارشی بسازید:


Map<String, Object> attributes = new HashMap<>();
attributes["first_name"] = "Ali";
attributes["last_name"] = "Bagheri";
attributes["manufacturer"] = "Nike";
attributes["product_name"] = "shirt";
attributes["type"] = "sport";
attributes["size"] = "large";
attributes["purchase_date"] = "2024-11-20T11:24:03.000Z"; // use ISO 8601 to consider this attribute as a date
 
MetrixAnalytics.newEvent("purchase_event_slug", attributes);

ورودی‌های متد newEvent در این حالت، بدین شرح هستند:

ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
ورودی دوم: یک Map<String, Object> که ویژگی‌های یک رویداد را مشخص می‌کند.

مشخص کردن Attribute‌های پیش‌فرض همه‌ی رویدادها

با استفاده از این تابع می‌توانید به تعداد دلخواه Attribute به همه‌ی رویدادهای خود اضافه کنید:


Map<String, Object> attributes = new HashMap<>();
attributes["manufacturer"] = "Nike";
attributes["purchase_date"] = "2024-11-20T11:24:03.000Z"; // use ISO 8601 to consider this attribute as a date
 
MetrixAnalytics.setUserAttributes(attributes);

با استفاده از توابع زیر میتوانید Attribute های از پیش تعیین شده را به کاربر اختصاص دهید:


MetrixAnalytics.User.setUserCustomId("userId"); // call when user tries to login in your system and set userId value that user already knows in your system
MetrixAnalytics.User.deleteUserCustomId(); // call when your user goes to logout in your system
MetrixAnalytics.User.setFirstName("userFirstName");
MetrixAnalytics.User.setLastName("userLastName");
MetrixAnalytics.User.setPhoneNumber("phoneNumber");
MetrixAnalytics.User.setHashedPhoneNumber("hashedPhoneNumber");
MetrixAnalytics.User.setEmail("email");
MetrixAnalytics.User.setHashedEmail("hashedEmail");
MetrixAnalytics.User.setCountry("country");
MetrixAnalytics.User.setCity("city");
MetrixAnalytics.User.setRegion("region");
MetrixAnalytics.User.setLocality("locality");
MetrixAnalytics.User.setGender(gender); // gender value could be "MALE" , "FEMALE" or "OTHER"
MetrixAnalytics.User.setBirthday(birthday); // birthday value type should be 'Long' timestamp
MetrixAnalytics.User.channelEnabled(channel); // channel value could be "SMS", "PUSH" or "EMAIL"
MetrixAnalytics.User.channelDisabled(channel); // channel value could be "SMS", "PUSH" or "EMAIL"

توجه: هر رویداد می‌تواند حداکثر ۵۰ attribute داشته باشد که طول key و value آن حداکثر ۵۱۲ بایت می‌باشد.

ساختن رویداد درآمدی


MetrixAnalytics.newRevenue("my_event_slug", 12000, "IRR");

ورودی‌های متد newRevenue بدین شرح هستند:

ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
ورودی دوم: یک مقدار عددی است که همان میزان درآمد است.
ورودی سوم: واحد پول مورد استفاده را تعیین می‌کند و می‌تواند سه مقدار IRR (پیش‌فرض) یا USD و یا EUR را داشته باشد.
ورودی چهارم: این ورودی دلخواه است و شناسه سفارش را تعیین می‌کند.

دریافت شناسه دستگاه‌های متریکس

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


MetrixAttribution.setUserIdListener(userId -> {
  //TODO
});

نکته: شناسه متریکس زمانی در اختیار شما قرار می‌گیرید که دستگاه توسط سرویس متریکس شناسایی شده باشد.

دریافت اطلاعات کمپین

با استفاده از متد زیر، می‌توانید اطلاعات کمپین تبلیغاتی که در ترکر خود در پنل قرار داده‌اید را دریافت کنید.


MetrixAttribution.setOnAttributionChangedListener(attributionData -> {
  //TODO
});

مدل attributionData اطلاعات زیر را در اختیار شما قرار می دهد.


attributionData.getAcquisitionAd(); // نام تبلیغ
attributionData.getAcquisitionAdSet(); // گروه تبلیغاتی
attributionData.getAcquisitionCampaign(); // کمپین تبلیغاتی
attributionData.getAcquisitionSource(); // شبکه تبلیغاتی
attributionData.getAcquisitionSubId(); // زیرگروه تبلیغاتی
attributionData.getAttributionStatus(); // وضعیت کاربر در کمپین را مشخص می‌کند

مقدار AttributionStatus شامل یکی از موارد زیر است:

ATTRIBUTED اتربیوت شده
NOT_ATTRIBUTED_YET هنوز اتربیوت نشده
ATTRIBUTION_NOT_NEEDED نیاز به اتربیوت ندارد
UNKNOWN حالت ناشناخته

Deep Linking

سناریو deferred

اگر شما قصد دارید که سناریو deferred را کنترل کنید می‌توانید از کالبک زیر استفاده نمایید:


MetrixAttribution.setOnDeeplinkResponseListener(deeplink -> {
  //TODO
});

بعد از این که متریکس اطلاعات دیپ‌لینک را از سرور خود دریافت کرد محتوای آن را به کالبک بالا پاس می‌دهد. اگر مقدار shouldLaunchDeeplink برابر true باشد متریکس به صورت اتوماتیک سناریو استاندارد را اجرا می‌کند و در غیر این صورت، متریکس فقط اطلاعات را در این کالبک قرار می‌دهد تا شما بر اساس آن اکشن مورد نظر خود را انجام دهید.

توجه: سناریو deffered تنها در صورت نصب اپلیکیشن از طریق Google Play Store و کافه بازار قابل اجرا می‌باشد.