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

ردیابی ایونت ها (Tracking Events)

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

متریکس از طریق SDK یونیتی، امکان تعریف و ارسال دو نوع اصلی از ایونت ها را فراهم می‌کند:

  • Action Events (ایونت های رفتاری): تعاملات کاربران با اپلیکیشن (مثلاً کلیک روی دکمه، مشاهده صفحه).
  • Revenue Events (ایونت های درآمدی): ردیابی تراکنش‌های مالی و درآمد کسب شده.

۱. ارسال Action Events (ایونت های رفتاری)

Action Events برای ثبت تعاملات مشخص کاربران با UI (رابط کاربری) اپلیکیشن یا بازی شما استفاده می‌شوند.

ساخت یک Action Event

شما می‌توانید ایونت های Action را به دو روش اصلی ایجاد و ارسال کنید:

  1. ثبت ایونت با استفاده از Slug (نامک) تعریف شده در پنل: اگر ایونت شما از قبل در پنل متریکس تعریف شده و دارای یک نامک (Slug) مشخص است (یک رشته کوتاه و یکتا مانند aewqd)، از متد Metrix.NewEvent استفاده کنید:
Metrix.NewEvent("my_event_slug"); // Example: Metrix.NewEvent("product_viewed_slug");
  1. ثبت ایونت با استفاده از نام دلخواه (Custom Name): اگر ترجیح می‌دهید از نام‌های توصیفی‌تر و خواناتر برای ایونت های خود استفاده کنید و یا نمی‌خواهید از قبل در پنل آن‌ها را تعریف کنید، از متد Metrix.NewEventByName استفاده کنید. در این صورت، اگر ایونت ی با این customName از قبل در پنل وجود نداشته باشد، به صورت اتوماتیک با نام دلخواه شما در پنل متریکس ساخته خواهد شد.

  • توصیه: برای customName از الگوی object_verb (مثال: product_viewed, button_clicked) استفاده کنید تا با Taxonomy متریکس هم‌خوانی داشته باشد.

Metrix.NewEventByName("my_event_name"); // Example: Metrix.NewEventByName("product_viewed");

افزودن خصیصه‌ها (Attributes) به Action Events

شما می‌توانید تعداد دلخواهی از خصیصه‌ها (Attributes) را برای ارائه جزئیات بیشتر همراه با ایونت های رفتاری خود ارسال کنید. خصیصه‌ها باید در قالب یک Dictionary<string, object> باشند و از انواع داده‌ای string, int, double, bool، یا DateTime (با فرمت ISO 8601) پشتیبانی می‌کنند.

var attributes = new Dictionary<string, object>();
attributes.Add("product_id", "P12345"); // String attribute
attributes.Add("category", "Electronics"); // String attribute
attributes.Add("price", 99.99); // Double attribute
attributes.Add("quantity", 1); // Integer attribute
attributes.Add("is_promo_item", true); // Boolean attribute
attributes.Add("view_date", "2024-11-20T11:24:03.000Z"); // Date attribute (ISO 8601 string)
attributes.Add("user_location", new Dictionary<string, object> { { "city", "Tehran" }, { "country", "Iran" } }); // Nested JSON Object
// Note: Direct JSON Array not shown, but can be managed by structuring your objects.
 
// ارسال ایونت  با Slug و Attributes
Metrix.NewEvent("purchase_event_slug", attributes);
 
// ارسال ایونت  با Custom Name و Attributes
Metrix.NewEventByName("purchase_event_name", attributes);

توضیح فیلدها در متدها:

  • ورودی اول (slug یا customName):
    • slug: نامک (string) ایونت مورد نظر شما که در پنل متریکس معرفی شده است.
    • customName: نام دلخواه (string) ایونت شما که در صورت عدم تعریف، به صورت خودکار در پنل ساخته می‌شود.
  • ورودی دوم (attributes): یک Dictionary<string, object> که ویژگی‌های ایونت را مشخص می‌کند.

۲. ارسال Revenue Events (ایونت های درآمدی)

Revenue Events برای ثبت تراکنش‌های مالی و درآمد حاصل از اپلیکیشن شما استفاده می‌شوند. این ایونت ها دارای یک مقدار عددی (درآمد) و واحد پول هستند.

  • نکته مهم: Revenue Events از خصیصه‌های اضافی (attributes) پشتیبانی نمی‌کنند.

ساخت یک Revenue Event

شما می‌توانید ایونت های درآمدی را به دو روش (با Slug یا Custom Name) ایجاد و ارسال کنید:

  1. ثبت ایونت با استفاده از Slug تعریف شده در پنل:
Metrix.NewRevenue("my_revenue_slug", 12000.0, 0); // Example: Metrix.NewRevenue("product_purchase", 12000.0, 0);
  1. ثبت ایونت با استفاده از نام دلخواه (Custom Name):
Metrix.NewRevenueByName("my_revenue_name", 12000.0, 0); // Example: Metrix.NewRevenueByName("in_app_purchase", 12000.0, 0);

توضیح فیلدها در متدها:

  • ورودی اول (slug یا customName):
    • slug: نامک (string) ایونت درآمدی شما.
    • customName: نام دلخواه (string) ایونت درآمدی شما.
  • ورودی دوم (revenueAmount): یک مقدار عددی (Double) که میزان درآمد کسب شده را نشان می‌دهد.
  • ورودی سوم (currencyCode): کد واحد پول مورد استفاده. این مقدار به صورت عدد صحیح تعیین می‌شود:
    • 0 برای ریال (IRR)
    • 1 برای دلار (USD)
    • 3 برای یورو (EUR)
    • نکته: برای اطلاع از سایر کدهای واحد پول پشتیبانی شده، لطفاً به مستندات کامل API یا پشتیبانی متریکس مراجعه کنید.

۳. نکات مهم در ردیابی ایونت ها

  • Taxonomy (تاکسونومی):
    • برای اطمینان از کیفیت و قابلیت تحلیل داده‌ها، از تاکسونومی ایونت ها و Tracking Plan متریکس پیروی کنید. این شامل استفاده از الگوی object_verb برای customName و نام‌گذاری استاندارد برای attributes است.
  • ایونت های Unique Per Device:
    • برخی ایونت ها ممکن است نیاز داشته باشند که فقط یک بار در هر دستگاه ثبت شوند (Unique Per Device). این ویژگی باید از قبل در پنل متریکس برای Slug ایونت مربوطه فعال شده باشد. در حال حاضر، ایونت هایی که با customName به صورت خودکار ساخته می‌شوند، این ویژگی را ندارند و قابل ویرایش نیستند. بنابراین، برای ایونت های Unique Per Device، حتماً از متد Metrix.NewEvent با slug تعریف شده در پنل استفاده کنید.
  • محدودیت Attributeها:
    • هر ایونت می‌تواند حداکثر ۵۰ attribute (شامل خصیصه‌های استاندارد و سفارشی) داشته باشد که طول key و value هر attribute حداکثر ۵۱۲ بایت می‌باشد.
Tracking UsersAttribution