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

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

اتریبیوشن (Attribution) در متریکس به معنای نسبت دادن نصب اپلیکیشن شما به منبع دقیق آن (مانند یک کمپین تبلیغاتی، یک استور خاص، یا یک فایل APK) است. این قابلیت به شما کمک می‌کند تا عملکرد کمپین‌های بازاریابی خود را به دقت بسنجید و بودجه خود را به مؤثرترین کانال‌ها اختصاص دهید.

این بخش به شما نشان می‌دهد که چگونه قابلیت‌های اتریبیوشن متریکس را در اپلیکیشن Unity خود پیاده‌سازی کنید.

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

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

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

۱.۱. فعال‌سازی برای اپلیکیشن Android

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

<manifest>
 
  ...
 
  <application>
 
    ...
 
    <meta-data
        android:name="metrix_storeName"
        android:value="STORE_NAME" />
 
  </application>
</manifest>

۱.۲. فعال‌سازی برای اپلیکیشن iOS

متد Metrix.SetStore را در ابتدای اجرای برنامه خود (مثلاً در متد Awake یا Start یک MonoBehaviour) فراخوانی کنید:

Metrix.SetStore("your_store_name"); // Example: Metrix.SetStore("AppStore");

۲. شمارش حذف اپلیکیشن (Uninstall Tracking) (مخصوص Android)

متریکس برای شمارش حذف (Uninstall) اپلیکیشن شما در اندروید، از قابلیت ارسال silent push (پوش نوتیفیکیشن خاموش) استفاده می‌کند.

برای استفاده از این ابزار، لازم است که از سرویس Firebase Cloud Messaging (FCM) در پروژه خود استفاده نمایید.

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

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

push configuration

  • وارد پنل متریکس خود شوید و به تنظیمات اپلیکیشن بروید.
  • سربرگ Uninstall Config را انتخاب کنید.
  • تنظیمات پروژه فایربیس خود را در فیلدهای مربوطه وارد نمایید.
  • با کلیک بر روی دکمه save، مقادیر را ذخیره کنید.
  • نکته: برای دریافت فایل Service account Data، می‌توانید از کنسول فایربیس خود در بخش Project Settings، سربرگ Service Accounts، دکمه Generate new private key را بزنید.

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

  2. ارسال Push Token در اپلیکیشن: پس از پیاده‌سازی FCM در اپلیکیشن خود، به هنگام دریافت توکن پوش‌نوتیفیکیشن از FCM، با فراخوانی متد Metrix.SetPushToken، این توکن را برای متریکس ارسال نمایید. این توکن برای ارتباط FCM با دستگاه کاربر و تشخیص حذف ضروری است.

    Metrix.SetPushToken(token); // 'token' is the FCM registration token obtained from Firebase

۳. مشخص کردن Tracker پیش‌فرض (Default Tracker)

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

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

۳.۱. فعال‌سازی برای اپلیکیشن Android

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

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

۳.۲. فعال‌سازی برای اپلیکیشن iOS

متد Metrix.SetDefaultTracker را در ابتدای اجرای برنامه خود فراخوانی کنید:

Metrix.SetDefaultTracker("your_tracker_token"); // Replace with the default tracker token from Metrix dashboard

۴. Deep Linking (دیپ‌لینک)

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

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

برای پیاده‌سازی سناریو استاندارد در Unity، می‌توانید مستندات رسمی Unity در مورد فعال‌سازی دیپ‌لینک را اینجا  مرور کنید.

۴.۲. سناریو Deferred Deep Linking (دیپ‌لینک تأخیری)

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

متریکس برای پشتیبانی از Deferred Deep Linking در اندروید (که به صورت بومی توسط پلتفرم پشتیبانی نمی‌شود)، مکانیزم خاص خود را دارد. اگر قصد کنترل این سناریو را دارید، می‌توانید از Callback زیر استفاده نمایید:

// Define your callback function to handle the deeplink
void DeferredDeeplinkListener(string deeplink) {
  // Your custom logic to handle the deeplink URL (e.g., navigate to a specific screen)
  Debug.Log("Deferred Deeplink received: " + deeplink);
}
 
// Subscribe to the deeplink response listener
Metrix.SetOnDeeplinkResponseListener(DeferredDeeplinkListener);
 
// Control whether Metrix should automatically launch the deeplink
Metrix.SetShouldLaunchDeeplink(true); // Set to 'true' for automatic launching, 'false' if you want to handle it manually in the callback

  • Metrix.SetOnDeeplinkResponseListener(DeferredDeeplinkListener): این متد، تابع DeferredDeeplinkListener شما را به عنوان Callback برای دریافت اطلاعات دیپ‌لینک تأخیری تنظیم می‌کند. پس از اینکه متریکس اطلاعات دیپ‌لینک را از سرور خود دریافت کرد، محتوای آن (URL دیپ‌لینک) را به این Callback ارسال می‌کند.

  • Metrix.SetShouldLaunchDeeplink(bool shouldLaunch):

    • اگر این متد با مقدار true فراخوانی شود، متریکس به صورت اتوماتیک سناریو استاندارد دیپ‌لینک را (یعنی باز کردن URL دیپ‌لینک در مرورگر یا اپلیکیشن مرتبط) اجرا می‌کند. در این حالت، Callback صرفاً اطلاعات را برای شما فراهم می‌کند.
    • اگر با مقدار false فراخوانی شود، متریکس فقط اطلاعات دیپ‌لینک را در Callback قرار می‌دهد و هیچ عملیات خودکاری انجام نمی‌دهد. در این صورت، شما باید بر اساس اطلاعات دریافتی در Callback، اکشن مورد نظر خود را در اپلیکیشن پیاده‌سازی کنید.

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

۵. دریافت اطلاعات کمپین (Campaign Information)

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

// Define your callback function to receive attribution data
void MetrixAttributionChangedListener(MetrixAttribution metrixAttribution) {
  // Your logic to handle attribution data
  Debug.Log("Attribution Data: " + metrixAttribution.acquisitionCampaign);
}
 
// Subscribe to the attribution changed listener
Metrix.SetOnAttributionChangedListener(MetrixAttributionChangedListener);

مدل MetrixAttribution (شیء metrixAttribution در Callback بالا) اطلاعات زیر را در اختیار شما قرار می‌دهد:

  • metrixAttribution.acquisitionAd: نام تبلیغ (Ad Name)
  • metrixAttribution.acquisitionAdSet: نام گروه تبلیغاتی (Ad Set Name)
  • metrixAttribution.acquisitionCampaign: نام کمپین تبلیغاتی (Campaign Name)
  • metrixAttribution.acquisitionSource: نام شبکه تبلیغاتی (Ad Network Name)
  • metrixAttribution.acquisitionSubId: شناسه زیرگروه تبلیغاتی (Sub-ID)
  • metrixAttribution.attributionStatus: وضعیت کاربر در کمپین را مشخص می‌کند.

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

  • ATTRIBUTED: کاربر به یک کمپین خاص اتریبیوت شده است.
  • NOT_ATTRIBUTED_YET: هنوز اتریبیوشن انجام نشده است (مثلاً داده‌ها در حال پردازش هستند).
  • ATTRIBUTION_NOT_NEEDED: نیازی به اتریبیوشن ندارد (مثلاً کاربر ارگانیک است یا خارج از کمپین).
  • UNKNOWN: وضعیت ناشناخته.

۶. دریافت شناسه دستگاه‌های متریکس (Metrix Device ID)

متریکس برای هر دستگاهی که اپلیکیشن شما را نصب کند، یک شناسه منحصر به فرد تولید می‌کند (Metrix Device ID). شما می‌توانید این شناسه را به محض شناسایی دستگاه توسط سرویس متریکس دریافت نمایید.

برای دسترسی به این شناسه، از متد Metrix.SetUserIdListener استفاده کنید:

// Define your callback function to receive the Metrix Device ID
void MetrixUserIdListener(string metrixUserId) {
  // Your logic to use the Metrix Device ID
  Debug.Log("Metrix Device ID: " + metrixUserId);
}
 
// Subscribe to the user ID listener
Metrix.SetUserIdListener(MetrixUserIdListener);

نکته: شناسه دستگاه متریکس (Metrix Device ID) زمانی در اختیار شما قرار می‌گیرد که دستگاه توسط سرویس متریکس شناسایی و ثبت شده باشد.

۷. مدیریت نشست (Session)

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

۷.۱. شناسه نشست (Session ID)

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

// Define your callback function to receive the Session ID
void MetrixSessionIdListener(string sessionId) {
  // Your logic to use the Session ID
  Debug.Log("Metrix Session ID: " + sessionId);
}
 
// Subscribe to the session ID listener
Metrix.SetSessionIdListener(MetrixSessionIdListener);

۷.۲. شماره نشست جاری (Current Session Number)

با استفاده از متد Metrix.SetSessionNumberListener، می‌توانید از شماره نشست جاری کاربر در تمام مدت استفاده او از اپلیکیشن شما اطلاع پیدا کنید. این شماره از 1 شروع شده و با هر نشست جدید افزایش می‌یابد.

// Define your callback function to receive the Session Number
void MetrixSessionNumberListener(string sessionNumber) {
  // Your logic to use the Session Number
  Debug.Log("Metrix Session Number: " + sessionNumber);
}
 
// Subscribe to the session number listener
Metrix.SetSessionNumberListener(MetrixSessionNumberListener);
Tracking EventsMessaging