ساخت دادهٔ رویداد بدون JSON دستی

مسئله‌ای که باید حل می‌کردم

رویداد اگر عدد و نام کلید را بسته به زبان دستگاه تغییر بدهد، دادهٔ قابل مقایسه‌ای نمی‌سازد. من ساخت فیلد را از محل ارسال و JSON جدا نگه داشتم.

پیاده‌سازی در نسخهٔ فعلی

AnalyticsFieldBuilder.Add کلید را trim و lowercase می‌کنه و مقدار طولانی را محدود می‌کنه. overload عددها از InvariantCulture و bool از true یا false استفاده می‌کنه.

تصمیم و هزینهٔ طراحی

AddList تعداد را محدود می‌کنه و رشته‌های خالی را کنار می‌گذارد. ToDictionary کپی می‌دهد، بنابراین مصرف‌کننده لازم نیست فهرست داخلی builder را برای ساخت payload تغییر دهد.

مرزهای فعلی

این builder مقدارها را رشته می‌کنه و جای validator کل schema نیست. قرارداد نوع نهایی در transport و محدودیت اندازهٔ کل رویداد هم باید دیده بشه؛ محدودیت هر فیلد کافی نیست.

سناریوهای بررسی و معنای قرارداد

یک تفاوت نوع داده در همین ابزار کوچک پنهان هست: overload عددی AnalyticsFieldBuilder مقدار را با فرهنگ ثابت به متن تبدیل می‌کنه. این کار قالب متن را پایدار می‌کنه، اما عدد JSON تولید نمی‌کنه. در PHP، schema از نوع Number واقعاً int یا float می‌خواهد و رشتهٔ شبیه عدد را نمی‌پذیرد. موتور گزارش نیز برای جمع و میانگین فقط مقدار عددی واقعی را وارد می‌کنه. بنابراین اگر فیلدی قرار هست معیار عددی باشد، مسیر Dictionary با مقدار عددی و SDK عمومی باید درست استفاده بشه؛ وجود نام duration_seconds یا نمایش درست متن، نوع نهایی را تضمین نمی‌کنه.

اعتبارسنجی سمت سرور چند مرز دیگر داره. data باید Object باشد، timestamp منطقهٔ زمانی داشته باشد و received_at مخصوص سرور هست. کلیدهای تکراری JSON رد می‌شوند و عدد صحیح خارج از محدودهٔ دقیق متداول باید به شکل رشته ارسال بشه تا بی‌صدا گرد نشود. این رشته برای شناسه مناسب هست، نه جایگزین معیار عددی گزارش. تعریف Required نیز غیبت یا null را بررسی می‌کنه؛ معنای دامنهٔ هر مقدار هنوز نیاز به طراحی قرارداد داره. اگر فیلد اضافی ممنوع باشد، کنترل ریشه‌های data انجام می‌شود و سخت‌گیری همهٔ زیرکلیدهای Object ادعا نمی‌شود. ساخت payload منظم آغاز کار هست و توافق دقیق نوع، حجم و معنا بین Unity و PHP مرحلهٔ ضروری بعدی هست.

تعریف گزارش قابل انتقال هست اما انتقال layout به بازی تازه، دادهٔ مناسب را ایجاد نمی‌کنه. نام مسیرهای data باید با payload واقعی آن بازی هماهنگ باشد. یک نمودار خالی ممکنه نتیجهٔ فیلد نامناسب باشد، نه نبودن بازیکن. این نکته برای استفادهٔ عمومی Bunny Circus Analytics مهم هست: قالب شروعی برای قرارداد هست و باید با کد ارسال‌کننده تطبیق داده بشه، بدون ساخت رویداد نمونه به جای رفتار واقعی.

چیزی که از این مرحله یاد گرفتم

برای من، نظم رویداد پیش از داشبورد شروع می‌شود. اسم و عدد پایدار کمک می‌کنه زبان رابط عوض بشه ولی مفهوم داده عوض نشود، بدون اینکه اطلاعات نامحدود را داخل یک رویداد بریزم.

مثال عملی دادهٔ رویداد

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

خطای رایج و علت آن

ساخت JSON با چسباندن رشته‌ها می‌تواند ساختار داده را خراب کند. این خطا معمولاً وقتی پنهان می‌ماند که فقط مسیر موفق و ظاهر نهایی را ببینیم. برای پیدا کردن علت، آخرین وضعیت درست را از نخستین وضعیت نادرست جدا کن و ببین تغییر دقیقاً در کدام مرز رخ داده است. ساختار داده باید با serializer معتبر ساخته شود و اطلاعات ضروری محدود بماند. اگر این تفاوت در قرارداد مشخص نباشد، اصلاح یک نشانه ممکن است همان مسئله را در بخش دیگری دوباره ایجاد کند.

چطور نتیجه را بررسی کنیم؟

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

پرسش‌های کاربردی دربارهٔ دادهٔ رویداد

از کجا شروع کنم؟

از همان موقعیت محدود این مطلب شروع کن: نام بازیکن یا مقدار متنی شامل نقل‌قول را در رویداد آزمایشی بفرست. ابتدا نتیجهٔ مورد انتظار را مشخص کن و بعد سراغ پیاده‌سازی یا ابزار برو. وقتی مسیر پایه قابل توضیح و بررسی شد، می‌توان حالت‌های بیشتری اضافه کرد. ساخت همهٔ حالت‌ها از ابتدا، فهم علت خطا را سخت‌تر می‌کند.

چه زمانی می‌توانم بگویم این بخش درست کار می‌کند؟

زمانی که رفتار در موقعیت تعریف‌شده با قرارداد سازگار باشد و محدودیت‌های آن روشن بمانند. نوع عدد، متن، مقدار تهی و دادهٔ تو‌در‌تو را در ورودی و خروجی مقایسه کن. موفقیت در این آزمون دربارهٔ همان سناریو شاهد می‌دهد؛ از آن نمی‌توان بدون بررسی دربارهٔ همهٔ دستگاه‌ها، همهٔ قوانین محلی یا همهٔ حجم‌های داده نتیجه گرفت. ساختار داده باید با serializer معتبر ساخته شود و اطلاعات ضروری محدود بماند.