نصب و استفاده از SDK یونیتی
بسته را در یونیتی نصب کنید، رویدادهای بازیکن را بفرستید و توکن پوش دستگاه را ثبت کنید.
SDK یونیتی رویداد ثبت میکند، یادش میماند بازیکن کیست، تا وقتی گوشی آفلاین است رویدادها را نگه میدارد و توکن پوش را ثبت میکند. کد بسته با C# نوشته شده است. Package Manager ماژول داخلی UnityWebRequest را همراه آن نصب میکند. بسته کتابخانهٔ خارجی اندروید یا iOS به بازی اضافه نمیکند.
همان پروتکل SDKهای دیگر را حرف میزند. هرچه در جاگذاری رویداد، رویدادها و هویت آمده است بدون تغییر دربارهٔ آن هم درست است.
چه کاری را SDK میکند و چه کاری با شماست
| SDK انجام میدهد | شما انجام میدهید |
|---|---|
| رویدادها را دستهای میفرستد و تا وقتی بازیکن آفلاین است روی دیسک نگه میدارد | تصمیم میگیرید چه رویدادهایی بفرستید و چه اسمی بدهید |
| هنگام تلاش دوباره شناسهٔ رویداد را حفظ میکند تا collector بتواند رویداد تکراری را تشخیص دهد | revenue را فقط روی رویدادی میفرستید که واقعا پول جابهجا شده |
| با انتظار روبهرشد و تصادفی دوباره تلاش میکند و میگوید چه چیزی را دور ریخته | بعد از ورود خودتان Identify را صدا میزنید |
| وقتی اپ به پسزمینه میرود صف را ذخیره میکند | توکن پوش را از پلاگین پوش خودتان میگیرید |
| توکن پوشی که بدهید را ثبت میکند | آدرس https://in.segmentic.net (یا میزبان خودتان) را در قاعدههای شبکه باز میگذارید |
نصب
- بستهٔ SDK یونیتی نسخهٔ ۰.۱.۰ و فایل SHA-256 آن را در یک پوشه ذخیره کنید.
- در همان پوشه، روی مک
shasum -a 256 -c net.segmentic.sdk-0.1.0.tgz.sha256و روی لینوکسsha256sum -c net.segmentic.sdk-0.1.0.tgz.sha256را اجرا کنید. پس از دیدنOKادامه دهید. - در یونیتی Window > Package Manager را باز کنید. از منوی + گزینهٔ Install package from tarball... و سپس فایل
.tgzرا انتخاب کنید. - برای بهروزرسانی، بستهٔ نسخهٔ بعدی را به همین روش نصب کنید. شناسهٔ اسکریپتهای متصل به آبجکتها بین نسخهها حفظ میشود.
نسخهٔ ۰.۱.۰ با یونیتی ۶.۶ (6000.6.8f1) آزمایش شده است. Package Manager ماژول داخلی UnityWebRequest را خودکار نصب میکند.
راهاندازی
using System.Collections.Generic;
using Segmentic;
using UnityEngine;
public class Boot : MonoBehaviour
{
void Start()
{
SegmenticSdk.Init(new SegmenticOptions
{
WriteKey = "wk_seg_...", // write key عمومی از پنل
ApiHost = "https://in.segmentic.net", // الزامی: نصب اختصاصی میزبان خودش را دارد
});
SegmenticSdk.Track("level_completed", new Dictionary<string, object>
{
{ "level", 3 },
{ "score", 1200 },
});
}
}
کد نمینویسید؟ کامپوننت Segmentic Initializer (منوی Component > Segmentic) را روی یک آبجکت در صحنهٔ اول بگذارید و write key و میزبان را پر کنید.
write key عمومی است و قرار است داخل بیلد برود. ApiHost عمدا مقدار پیشفرض ندارد: مقدار پیشفرض رویدادهای مشتری با نصب اختصاصی را به جای اشتباه میفرستد و با خطای ۴۰۱ تمام میشود که شبیه کلید غلط است.
از ترد اصلی صدایش بزنید، که جای اجرای کد یونیتی هم هست. دو بار Init بیخطر است: بار دوم همان کلاینت در حال اجرا را برمیگرداند.
رویدادها
SegmenticSdk.Track("product_viewed", new Dictionary<string, object> { { "product_id", "p-77" } });
SegmenticSdk.Screen("Shop");
- اسم خالی رویداد نادیده گرفته میشود و در لاگ میآید. اسمها از قاعدهٔ نامگذاری پیروی میکنند: حروف کوچک و بزرگ یکی نمیشوند، پس
Level Doneوlevel_doneبرای همیشه دو رویداد جدا هستند. - ویژگیها یک
Dictionary<string, object>هستند.Dictionary<string, int>تبدیل نمیشود؛ نسخهٔobjectرا بسازید. - عدد عدد میماند، بولین بولین میماند، و رشتهٔ عددی رشته میماند:
"2450000"هرگز با فیلتر «بزرگتر از» جور نمیشود. مقدارnullکنار گذاشته میشود. تاریخ به متن UTC با قالب ISO 8601 تبدیل میشود، enum به اسمش، و لیست و دیکشنری تودرتو به JSON. - عددها هر زبانی که روی گوشی باشد یک شکل نوشته میشوند. گوشی فارسی یا عربی ممیز اعشار را عوض نمیکند.
- اسم رویداد را از یک متغیر نسازید. وقتی اسم رویداد یک نشانی است را ببینید: همان اشتباه در بازی میشود
"clicked_" + buttonName. - کلیدهای
revenue،total،valueو جفتpriceباquantityروی هر رویدادی به ارزش طول عمر مشتری اضافه میکنند. درآمد را ببینید.
بازیکن کیست
SegmenticSdk.Identify("user-42", new Dictionary<string, object> { { "city", "Tehran" } });
SegmenticSdk.Reset(); // موقع خروج
- SDK اولین بار که اجرا میشود یک anonymous ID میسازد و تا وقتی بازی پاک شود یا
Resetصدا زده شود نگهش میدارد. Identifyبا user ID متفاوت از چیزی که ذخیره شده، اول یکaliasو بعدidentifyرا در صف میگذارد. کارهایی که بازیکن پیش از ورود کرده به همان پروفایل وصل میشود. صدا زدن دوباره با همان شناسه alias تازه نمیسازد، حتی بعد از راهاندازی دوباره.Resetکاربر را فراموش میکند و anonymous ID تازه میسازد، تا نفر بعدی روی یک دستگاه مشترک تاریخچهٔ قبلی را به ارث نبرد. رویدادهایی که پیشتر در صف رفتهاند همان شناسههایی را نگه میدارند که با آن ساخته شدهاند. ثبت پوشی که هنوز منتظر ارسال است هم دور ریخته میشود، چون شناسههای بازیکن قبلی را دارد. برای اینکه گوشی در سرور هم از بازیکن قبلی جدا شود، اولUnregisterDeviceرا صدا بزنید (پوش را ببینید).OptOut()جمعآوری را متوقف میکند، صف و نسخهٔ ذخیرهشدهٔ آن را پاک میکند، و بعد از راهاندازی دوباره هم یادش میماند.OptIn()برعکسش است. تا وقتی بازیکن انصراف داده، رویداد و ثبت دستگاه جدید در صف نمیرود و فرستاده نمیشود. تنها استثنا، درخواست صریحUnregisterDeviceاست که پیش ازOptOutدر صف قرار گرفته: همان درخواست خروج ذخیره میماند و حتی پس از راهاندازی دوباره retry میشود. درخواستی که پیشتر وارد شبکه شده قابل بازپسگیری نیست.
صف رویدادها، ثبتهای در انتظار دستگاه و هویت بازیکن به همان آدرس collector و همان کلید نوشتن تعلق دارند. با بازگرداندن تنظیمات اصلی، ارسال از صف همان مقصد ادامه مییابد. بعد از ارتقا از نسخهای که مقصد را ثبت نمیکرد، دوباره بازیکن را معرفی و دستگاه را ثبت کنید. SDK رویداد و ثبت قدیمی بدون مقصد مشخص را ارسال نمیکند. انصراف صف رویدادها و ثبت دستگاه را برای همهٔ مقصدهای ذخیرهشده پاک میکند. اگر وضعیت رضایت خوانده نشود، جمعآوری متوقف میشود. پس از رفع مشکل ذخیرهسازی، SDK را دوباره راهاندازی کنید تا تصمیم ذخیرهشده را بخواند. بعد از گرفتن رضایت تازه نیز میتوانید OptIn() را صدا بزنید.
درخواستهای صریح خروج دستگاه بهترتیب ثبت ارسال میشوند. اگر درخواست صریح دقیقاً با خروج قدیمی و یک دستگاه جاری متفاوت منطبق باشد، در حالت فعال، خروج هر دو دستگاه در صف قرار میگیرد. در حالت انصراف فقط خروج دستگاه قدیمی منطبق قابل بازیابی است. پیش از برگشت به نسخهٔ قدیمی، خروجهای معلق را با تنظیمات مقصد اصلی تسویه کنید. نسخهٔ قدیمی میتواند فایلهای بدون مقصد قبلی را دوباره بخواند، پس هنگام بازگشت، آن پوشهٔ داده را با collector دیگری استفاده نکنید.
در WebGL وضعیت رضایت در PlayerPrefs ذخیره میشود. پاک کردن دادههای سایت این تنظیم را هم پاک میکند.
پوش
SDK هیچوقت از پلتفرم توکن پوش نمیخواهد. بازی شما پلاگین پوش خودش را دارد؛ وقتی توکن را گرفتید به Segmentic بدهید، و هر بار که عوض شد دوباره:
SegmenticSdk.RegisterDevice(new DeviceRegistration
{
Tokens = new Dictionary<string, string>
{
{ "fcm", firebaseToken },
{ "bazaar", bazaarToken }, // یک دستگاه میتواند چند مسیر داشته باشد
},
});
- به
POST /v1/devicesمیرود، همان endpoint مسیر دستی، و از دستهٔ رویدادها رد نمیشود. - ذخیره میشود و با flush بعدی فرستاده میشود (حدود ده ثانیه، یا
await SegmenticSdk.FlushAsync()). اگر شبکه قطع باشد نگه داشته میشود، حتی بعد از راهاندازی دوباره، و فقط جدیدترین ثبت نگه داشته میشود. - جواب
4xxیعنی سرور رد کرده و همان بدنه دوباره هم رد میشود، پس فراموش میشود وGetStats().LastDeviceErrorدلیلش را میگوید. این فیلد جداست تا یک ارسال موفق رویداد آن را پنهان نکند. - وقتی توکن قابل استفاده نیست و پوش خاموش هم نشده، فرستاده نمیشود، چون سرور به آن
400میدهد. اگر بازیکن اعلان را خاموش کرد،new DeviceRegistration { PushEnabled = false }را بفرستید. - بعد از
Identifyدوباره ثبت کنید. ثبت دستگاه برای کسی انجام میشود که بازیکن همان لحظه است. ثبت پیش از ورود یک نصب ناشناس میسازد که امروز هیچ کمپینی هدفش نمیگیرد (به نصبهای ناشناس نگاه کنید)؛ پس بعد ازIdentifyدوبارهRegisterDeviceرا صدا بزنید. شناساندن بازیکن دیگر، یاReset، ثبتی را که هنوز برای بازیکن قبلی منتظر بود دور میریزد. - بازیکنی که
Identifyشده از بکاند شما اثبات میخواهد. بعد ازIdentifyثبت دستگاه شناسهٔ کاربر را هم میبرد و سرور جواب403 user identity is not verifiedمیدهد، مگر اینکهUserHashرا بدهید (یک HMAC که بکاند شما برای همان user ID میسازد؛ وBindingId). هر دو همانطور که داده شوند عبور داده میشوند؛ ثبت دستگاه را ببینید. ثبت پیش از ورود، وقتی هنوزIdentifyصدا زده نشده، بهعنوان یک نصب ناشناس پذیرفته میشود. - خروج از حساب:
SegmenticSdk.UnregisterDevice(userId, userHash, bindingId)گوشی را در سرور از آن بازیکن جدا میکند (خروج از حساب). همانuserHashرا میخواهد که بکاند شما میسازد، پس پیش ازReset()یاOptOut()صدایش بزنید که هنوز دارید، و مقدار boolean برگشتی را بررسی کنید. ذخیره میشود، با flush بعدی فرستاده میشود، اگر شبکه قطع باشد نگه داشته میشود، و ردشده فراموش و درLastDeviceErrorنشان داده میشود. درخواست خروجی که پیش ازOptOut()در صف رفته، در حالت انصراف هم retry میشود؛ ثبت دستگاه جدید همچنان مسدود است. برای ابطال دستگاهrevoked: trueبدهید.SignOutPendingدر آمار میگوید یکی منتظر است. خود OptOut بهتنهایی دستگاه را در سرور باطل نمیکند. ارتقا نمیتواند درخواست خروجی را که نسخهٔ قبلی پاک کرده بازیابی کند؛ بازگشت به نسخهٔ قدیمی هم ممکن است retry درخواست منتظر را لغو کند. - درخواست خروج فقط با
ApiHostوWriteKeyزمان ثبت آن دوباره ارسال میشود. اگر بعد از ارتقاLastDeviceErrorدربارهٔ درخواست قدیمی هشدار داد، آدرس و کلید اصلی را انتخاب کنید وUnregisterDeviceرا با همان شناسهٔ کاربر، امضا، binding و مقدارrevokedصدا بزنید. برای این کار میتوانید در حالت انصراف بمانید. نسخهٔ قبلی مقصد را ذخیره نمیکرد و SDK تا این فراخوانی صریح منتظر میماند. پیش از بازیابی درخواست قدیمی یا بازگشت به نسخهٔ قبلی، ارسال درخواست خروج فعلی را کامل کنید. - مسیرهای قابل قبول برای اندروید
fcm،bazaar،myketوhuaweiهستند؛ برای iOSapns. شناسهٔ دستگاه یک شناسهٔ تصادفی است که SDK در حافظهٔ خصوصی خود اپ نگه میدارد، هرگز advertising ID نیست.
صف آفلاین و تلاش دوباره
رویدادها در حافظه صف میشوند، هر چند ثانیه و هر بار که اپ pause شود یا بسته شود در پوشهٔ خصوصی اپ ذخیره میشوند، و در دستههای ۲۰ تایی (یا هر ۱۰ ثانیه) فرستاده میشوند. صف ۱۰۰۰ رویداد جا دارد؛ وقتی پر شود قدیمیترین دور ریخته و شمرده میشود.
| جواب سرور | کار SDK |
|---|---|
200 | دسته را برمیدارد. موردهایی که سرور تکبهتک رد کرده (rejected در جواب) دورریختهشده شمرده میشوند و دوباره تلاش نمیشوند. تکراریها فرستادهشده حساب میشوند |
بدون جواب، timeout، 5xx، 429، 408 | همهچیز را نگه میدارد و با انتظار روبهرشد تصادفی دوباره میکوشد: تا ۲، ۴، ۸ و تا ۳۰۰ ثانیه. اگر Retry-After بلندتر باشد رعایتش میکند |
413 | دسته را نصف میکند و دوباره میفرستد تا جا شود. یک رویداد تکی که باز هم بزرگ است دور ریخته و شمرده میشود |
هر 4xx دیگر (400، 401، 402، 403 و مانند آن) | همان دسته را دور میریزد و میشمارد: سرور هر بار همینطور ردش میکند. LastError کد وضعیت را نگه میدارد |
هر رویداد از لحظهٔ ساخته شدن message_id خودش را دارد. تلاش دوباره، یا ارسالی که با کرش نیمه ماند، همان شناسه را میفرستد. بازهٔ تشخیص تکرار در collector قابل تنظیم است و پیشفرض آن ۴۸ ساعت است. تلاش دیرتر یا اختلال در ذخیرهٔ شناسهها میتواند باعث ثبت تکراری شود.
کرش سخت میتواند رویدادهای ثانیههای آخر را از بین ببرد، چون ذخیره روی هر فراخوانی نوشته نمیشود.
سلامت SDK را ببینید
var s = SegmenticSdk.GetStats();
// s.Queued, s.Sent, s.Dropped, s.OptedOut, s.DurableStorage, s.AnonymousId, s.UserId,
// s.LastError, s.LastDeviceError, s.DevicePending, s.SignOutPending
در گزینهها Log = Debug.Log بگذارید تا هر تصمیم در کنسول یونیتی دیده شود. LastError برابر http 401 بعد از اولین نصب تقریبا همیشه یعنی write key یا میزبان غلط است، و LastDeviceError برابر http 403 یعنی ثبت پوش یک بازیکن واردشده UserHash نداشته است. برای دیدن اینکه چه چیزی به سرور رسید دیدن آنچه واقعا رسید را ببینید.
پلتفرمها
| پلتفرم | رویداد | صف بعد از راهاندازی دوباره میماند | ثبت پوش |
|---|---|---|---|
| اندروید | بله | بله | fcm، bazaar، myket، huawei |
| iOS | بله | بله | apns |
| پلیر ویندوز، مک، لینوکس و خود Editor | بله | بله | ثبت میشود، ولی امروز هیچ کمپینی به این دستگاهها نمیرسد |
| WebGL | بله | نه: فقط حافظه، DurableStorage برابر false است. anonymous ID و کاربر واردشده هم فراموش میشوند، پس هر بار بارگذاری صفحه یک بازدیدکنندهٔ تازه است تا دوباره Identify صدا بزنید | نه |
میزبانهای ساده با http:// روی iOS و اندروید بهطور پیشفرض بستهاند؛ از https:// استفاده کنید، یا برای یک جعبهٔ آزمایشی اختصاصی تنظیم پلیر یونیتی «Allow downloads over HTTP» را روشن کنید.
چه چیزی در این نسخه نیست
توکن پوش خودکار، پیام درونبرنامهای، ردیابی نصب، گزارش کرش، و رویدادهای خودکار app_opened یا نشست (همانطور که فرهنگ رویدادها میگوید هیچ SDKای اینها را نمیفرستد: خودتان بفرستید).
چه چیزی اجرا شده و چه چیزی نه
تستها با Unity 6000.6.8f1 روی مک و در آزمایش اندروید روی گوشی شیائومی با Android 13 و ARM64 IL2CPP اجرا شدند. آزمایش گوشی، SDK و ثبت دستگاه را پوشش میدهد. دریافت اعلان واقعی Firebase آزمایش جداگانه دارد.