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