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

اتریبیوشن (Attribution)

این ویژگی‌ها را پیاده‌سازی کنید تا نصب‌ها را از فروشگاه‌های خاص ردیابی کنید، حذف نصب‌ها را نظارت کنید و دیپ لینک‌ها (deep links) را مدیریت کنید.

تمایز نصب‌های ارگانیک بر اساس فروشگاه

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

روش 1: استفاده از AndroidManifest.xml (توصیه شده)

نام فروشگاه را در فایل AndroidManifest.xml خود قرار دهید.

<manifest>
  <application>
    <!-- خطوط زیر را اضافه کرده و با نام فروشگاه جایگزین کنید -->
    <meta-data
        android:name="metrix_storeName"
        android:value="YOUR_STORE_NAME" />
  </application>
</manifest>
  • مقدار YOUR_STORE_NAME را با نام فروشگاه (مانند GooglePlay، CafeBazaar یا Myket) جایگزین کنید. برای یکپارچگی آمار، این نام باید برای یک فروشگاه در تمام نسخه‌ها ثابت بماند.

(توجه: کلید metrix_storeName را تغییر ندهید.)

  • در پنل Metrix، این مقدار به عنوان نام کمپین برای ترکر organic ظاهر می‌شود و به شما امکان می‌دهد نصب‌های ارگانیک را بر اساس فروشگاه دسته‌بندی کنید.

روش 2: Programmatically

همچنین می‌توانید نام فروشگاه را در کد خود تنظیم کنید.

MetrixAttribution.setStore("GooglePlay");

ردیابی حذف نصب (Uninstall Tracking)

Metrix از پوش نوتیفیکیشن‌های بی‌صدا از طریق Firebase Cloud Messaging (FCM) برای ردیابی حذف نصب اپلیکیشن‌ها استفاده می‌کند.

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

  1. وارد کردن اعتبارسنجی Firebase: در پنل Metrix خود، به تنظیمات اپلیکیشن رفته و تب Uninstall Config را انتخاب کنید. فایل Service Account Data فایربیس خود را آپلود کنید. می‌توانید این فایل را در کنسول Firebase خود تحت عنوان Project Settings → Service Accounts → Generate New Private Key تولید کنید. پیکربندی پوش نوتیفیکیشن
  2. فعال‌سازی ردیابی: پس از ذخیره اعتبارسنجی‌ها، ردیابی حذف نصب را با روشن کردن سوئیچ در پنل فعال کنید.
  3. ارسال توکن پوش: در اپلیکیشن خود، پس از مقداردهی اولیه FCM و دریافت توکن پوش، آن را به Metrix ارسال کنید.
MetrixAttribution.setPushToken("YOUR_FCM_PUSH_TOKEN");

تنظیم یک ترکر پیش‌فرض (Default Tracker)

یک ترکر پیش‌فرض برای کاربرانی که اپلیکیشن شما را مستقیماً از یک فایل APK نصب می‌کنند (یعنی نه از طریق یک کلیک) اختصاص دهید. این برای ردیابی نصب‌ها از کانال‌های توزیع مستقیم مفید است.

مهم: هرگز یک اپلیکیشن را با ترکر پیش‌فرض تنظیم شده در فروشگاه منتشر نکنید. انجام این کار باعث می‌شود تمام نصب‌های ارگانیک شما از آن فروشگاه به اشتباه به ترکر پیش‌فرض نسبت داده شوند.

روش 1: استفاده از AndroidManifest.xml

<manifest>
  <application>
    <meta-data
        android:name="metrix_trackerToken"
        android:value="YOUR_TRACKER_TOKEN" />
  </application>
</manifest>

روش 2: Programmatically

MetrixAttribution.setDefaultTracker("YOUR_TRACKER_TOKEN");

دیپ لینک (Deep Linking)

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

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

سناریوی استاندارد (اپلیکیشن نصب شده است)

اگر کاربران شما اپلیکیشن شما را نصب کرده‌اند و می‌خواهید پس از کلیک بر روی یک دیپ لینک، یک صفحه خاص از اپلیکیشن شما باز شود، ابتدا باید یک نام طرح (scheme name) منحصربه‌فرد انتخاب کنید. سپس، باید آن را به اکتیویتی (activity) که قصد دارید هنگام کلیک روی دیپ لینک راه‌اندازی شود، اختصاص دهید. برای این کار، به فایل AndroidManifest.xml رفته و بخش intent-filter را به اکتیویتی مورد نظر، همراه با نام طرح انتخابی خود، اضافه کنید. همانطور که در زیر نشان داده شده است:

  1. پیکربندی AndroidManifest.xml: یک intent-filter به اکتیویتی هدف با یک URL scheme منحصربه‌فرد اضافه کنید.

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

  2. مدیریت Intent: در متدهای onCreate و onNewIntent اکتیویتی خود به داده‌های دیپ لینک دسترسی پیدا کنید.

    @Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Intent intent = getIntent();
    Uri data = intent.getData();
    // مدیریت داده‌های دیپ لینک...
}
 
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    Uri data = intent.getData();
    // مدیریت داده‌های دیپ لینک اگر اکتیویتی از قبل در حال اجرا باشد...
}

سناریوی Deferred (اپلیکیشن نصب نشده است)

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

یک listener برای دریافت دیپ لینک deferred تنظیم کنید.

MetrixAttribution.setOnDeeplinkResponseListener(new OnDeeplinkResponseListener() {
    @Override
    public boolean launchReceivedDeeplink(Uri deeplink) {
        // منطق سفارشی شما برای مدیریت دیپ لینک
        // ...
 
        // برای اینکه Metrix به‌طور خودکار لینک را باز کند (سناریوی استاندارد)، true برگردانید.
        // اگر خودتان آن را به‌طور کامل مدیریت کرده‌اید، false برگردانید.
        if (shouldMetrixSdkLaunchTheDeeplink(deeplink)) {
            return true;
        } else {
            return false;
        }
    }
});

توجه: دیپ لینکینگ Deferred در حال حاضر برای نصب‌های از Google Play و کافه بازار پشتیبانی می‌شود.

بازیابی اطلاعات کمپین

برای دریافت جزئیات درباره کمپینی که منجر به نصب شده است، به تغییرات اتریبیوشن گوش دهید.

MetrixAttribution.setOnAttributionChangedListener(new OnAttributionChangeListener() {
    @Override
    public void onAttributionChanged(AttributionData attributionData) {
        // از attributionData در اینجا استفاده کنید
    }
});

فیلدهای AttributionData:

AttributionData شامل فیلدهای زیر است:

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

مقادیر وضعیت اتریبیوشن (Attribution Status):

  • ATTRIBUTED کاربر با موفقیت به یک کمپین اتریبیوت شده است.
  • NOT_ATTRIBUTED_YET فرآیند اتریبیوشن هنوز در حال انجام است و نتیجه نهایی مشخص نشده است.
  • ATTRIBUTION_NOT_NEEDED کاربر به‌صورت ارگانیک جذب شده است یا در هیچ‌یک از کمپین‌های تبلیغاتی قرار نمی‌گیرد؛ بنابراین نیازی به انجام فرآیند اتریبیوشن برای او وجود ندارد.
  • UNKNOWN وضعیت اتریبیوشن کاربر در حال حاضر نامشخص است.

بازیابی شناسه دستگاه Metrix

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

MetrixAttribution.setUserIdListener(new UserIdListener() {
    @Override
    public void onUserIdReceived(String metrixUserId) {
        // منطق شما با شناسه کاربری Metrix
    }
});

ردیابی نشست (Session Tracking)

هر تعامل کاربر در یک جلسه رخ می‌دهد. SDK Metrix به‌طور خودکار اطلاعات جلسه، از جمله مدت زمان و فعالیت را جمع‌آوری می‌کند و به شما بینشی در مورد تعامل کاربر می‌دهد.

شناسه نشست (Session Identifier)

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

MetrixAnalytics.setSessionIdListener(new SessionIdListener() {
    @Override
    public void onSessionIdChanged(String sessionId) {
        // مثال: Crashlytics.setString("metrix_session_id", sessionId);
    }
});

شماره نشست جاری(Session Number)

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

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

موارد استفاده عملی و مثال‌ها

ورود به سیستم و حفظ کاربر (Onboarding and Retention)

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

MetrixAnalytics.setSessionNumberListener(sessionNumber -> {
    if (sessionNumber == 1) {
        // این اولین نشست کاربر است
        showOnboardingTutorial();
        MetrixAnalytics.newEvent("first_session_started");
    } else if (sessionNumber == 2) {
        // کاربر برای نشست دوم بازگشته است
        MetrixAnalytics.newEvent("user_retained_session_2");
    } else if (sessionNumber >= 10) {
        // کاربر بسیار فعال
        offerLoyaltyReward();
        MetrixAnalytics.newEvent("user_highly_engaged");
    }
});

همبستگی با گزارش‌های کرش (Crash Reports)

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

MetrixAnalytics.setSessionIdListener(sessionId -> {
    // مثال با Firebase Crashlytics
    FirebaseCrashlytics.getInstance().setCustomKey("metrix_session_id", sessionId);
});
Tracking EventsMessaging