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

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

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

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

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

    implementation 'ir.metrix:metrix:1.0.5'

۳. اضافه کردن app id متریکس در فایل AndroidManifest.xml اپلیکیشن:

<manifest>

  ...

  <application>

    ...

    <!-- خطوط زیر را اضافه کنید و کلید اپلیکیشن خود را جایگزین نمایید -->
    <meta-data
        android:name="metrix_appId"
        android:value="APP_ID" />

  </application>
</manifest>

APP_ID: کلید اپلیکیشن شما که از پنل متریکس دریافت می‌کنید.

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

نشست (session)

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

شناسه نشست

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

    Metrix.getSessionId();

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

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

    Metrix.getSessionNum();

رویداد (event)

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

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

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

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

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

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

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

    Metrix.newEvent("my_event_slug");

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

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

    Map<String, String> 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");

    Metrix.newEvent("purchase_event_slug", attributes);

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

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

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

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

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

    Map<String, String> attributes = new HashMap<>();
    attributes.put("manufacturer", "Nike");
    Metrix.addUserAttributes(attributes);

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

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

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

    Metrix.newRevenue("my_event_slug", 12000, RevenueCurrency.IRR, "myOrderId");

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

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

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

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

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

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

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

    Metrix.getUserId();

امضاء کتابخانه

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

    Metrix.setAppSecret(secretId, info1, info2, info3, info4);

توجه: این فراخوانی باید در متد onCreate در کلاس Application برنامه صورت گیرد.

شمارش پاک کردن اپلیکیشن

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

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

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

• وارد کردن

server key و sender id پروژه فایربیس در پنل متریکس

در پنل متریکس به تنظیمات اپلیکیشن خود رفته و سربرگ Push Configuration را انتخاب کنید.

در این صفحه server key و sender id پروژه فایربیس خود را در فیلد های مربوطه وارد کنید و با کلیک بر روی دکمه save مقادیر را ذخیره کنید.

این مقادیر را می‌توانید از کنسول فایربیس خود در بخش project settings در سربرگ Cload Messaging دریافت نمایید.

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

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

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

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

    Metrix.setPushToken("pushToken");

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

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

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

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

attributionData.getAcquisitionAd() // نام تبلیغ
attributionData.getAcquisitionAdSet() // گروه تبلیغاتی
attributionData.getAcquisitionCampaign() // کمپین تبلیغاتی
attributionData.getAcquisitionSource() // شبکه تبلیغاتی
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 را کنترل کنید می‌توانید از کالبک زیر استفاده نمایید:

    Metrix.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 پیش‌فرض برای نصب‌های organic

اگر بخواهید برای کاربرانی که نصب آنها organic بوده و از یک کلیک ناشی نمی‌شود ترکر داشته باشید، با استفاده از این تابع می‌توانید با یک trackerToken که از پنل دریافت می‌کنید، یک tracker پیش‌فرض برای اپلیکیشن خود قرار دهید:

    Metrix.setDefaultTracker(trackerToken);

توجه: این فراخوانی باید در متد onCreate در کلاس Application برنامه صورت گیرد.

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

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

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

    Metrix.setStore("store name");

توجه: این فراخوانی باید در متد onCreate در کلاس Application برنامه صورت گیرد.