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

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

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

مستندات نصب و راه‌اندازی اولیه در بخش Getting Started آمده است.

اتصال bridge متریکس به 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 را فراخوانی کنید.

کاربر (user)

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

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

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

به‌روزرسانی اطلاعات User

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

var attributes = {};
attributes['type'] = 'Loyal';
attributes['signup_date'] = '2024-11-20T11:24:03.000Z'; // use ISO 8601 to consider this attribute as a date
 
MetrixAnalytics.setUserAttributes(attributes);

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

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

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

رویداد (event)

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

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

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

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

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

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

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

MetrixAnalytics.newEvent('my_event_slug');

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

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

var attributes = {};
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> که ویژگی‌های یک رویداد را مشخص می‌کند.

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

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

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

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

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

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

نشست (session)

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

شناسه نشست

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

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

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

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

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

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

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

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

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

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

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

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

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

attributionData.acquisitionAd; // نام تبلیغ
attributionData.acquisitionAdSet; // گروه تبلیغاتی
attributionData.acquisitionCampaign; // کمپین تبلیغاتی
attributionData.acquisitionSource; // شبکه تبلیغاتی
attributionData.acquisitionSubId; // زیرگروه تبلیغاتی
attributionData.attributionStatus; // وضعیت کاربر در کمپین را مشخص می‌کند

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

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

Deep Linking

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

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

سناریو deferred

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

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

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

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

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