پرش به محتوا
مستندات
EN
ورود به پنل
شروع
  • نقشهٔ مستندات
  • راه‌اندازی سریع
  • مفهوم‌ها
جمع‌آوری داده
  • تعریف رویداد
  • فرهنگ‌نامهٔ رویدادها
  • گذاشتن رویداد
  • ادغام هویت
  • SDK وب
  • SDK اندروید
  • SDK یونیتی
  • ثبت دستگاه
  • سرور به سرور
  • کاتالوگ محصولات
  • وب‌هوک
مخاطب و پیام‌رسانی
  • سگمنت
  • سناریو
  • پیام تراکنشی
  • رضایت و سقف
  • پیام درون‌برنامه‌ای
تحلیل و خروجی
  • گزارش و خروجی
مرجع توسعه‌دهنده
  • مرجع API
    • نقاط ورود داده
    • API مدیریتی
  • کدهای خطا
  • سقف‌ها
  • OpenAPI
ابزارهای توسعه
  • سرور MCP
  • کار با عامل
حریم خصوصی و تغییرات
  • داده‌های شخصی
  • نسخه و تغییرها

نصب و استفاده از SDK یونیتی

بسته را در یونیتی نصب کنید، رویدادهای بازیکن را بفرستید و توکن پوش دستگاه را ثبت کنید.

SDK یونیتی رویداد ثبت می‌کند، یادش می‌ماند بازیکن کیست، تا وقتی گوشی آفلاین است رویدادها را نگه می‌دارد و توکن پوش را ثبت می‌کند. کد بسته با C# نوشته شده است. Package Manager ماژول داخلی UnityWebRequest را همراه آن نصب می‌کند. بسته کتابخانهٔ خارجی اندروید یا iOS به بازی اضافه نمی‌کند.

همان پروتکل SDKهای دیگر را حرف می‌زند. هرچه در جاگذاری رویداد، رویدادها و هویت آمده است بدون تغییر دربارهٔ آن هم درست است.

#چه کاری را SDK می‌کند و چه کاری با شماست

SDK انجام می‌دهدشما انجام می‌دهید
رویدادها را دسته‌ای می‌فرستد و تا وقتی بازیکن آفلاین است روی دیسک نگه می‌داردتصمیم می‌گیرید چه رویدادهایی بفرستید و چه اسمی بدهید
هنگام تلاش دوباره شناسهٔ رویداد را حفظ می‌کند تا collector بتواند رویداد تکراری را تشخیص دهدrevenue را فقط روی رویدادی می‌فرستید که واقعا پول جابه‌جا شده
با انتظار رو‌به‌رشد و تصادفی دوباره تلاش می‌کند و می‌گوید چه چیزی را دور ریختهبعد از ورود خودتان Identify را صدا می‌زنید
وقتی اپ به پس‌زمینه می‌رود صف را ذخیره می‌کندتوکن پوش را از پلاگین پوش خودتان می‌گیرید
توکن پوشی که بدهید را ثبت می‌کندآدرس https://in.segmentic.net (یا میزبان خودتان) را در قاعده‌های شبکه باز می‌گذارید

#نصب

  1. بستهٔ SDK یونیتی نسخهٔ ۰.۱.۰ و فایل SHA-256 آن را در یک پوشه ذخیره کنید.
  2. در همان پوشه، روی مک shasum -a 256 -c net.segmentic.sdk-0.1.0.tgz.sha256 و روی لینوکس sha256sum -c net.segmentic.sdk-0.1.0.tgz.sha256 را اجرا کنید. پس از دیدن OK ادامه دهید.
  3. در یونیتی Window > Package Manager را باز کنید. از منوی + گزینهٔ Install package from tarball... و سپس فایل .tgz را انتخاب کنید.
  4. برای به‌روزرسانی، بستهٔ نسخهٔ بعدی را به همین روش نصب کنید. شناسهٔ اسکریپت‌های متصل به آبجکت‌ها بین نسخه‌ها حفظ می‌شود.

نسخهٔ ۰.۱.۰ با یونیتی ۶.۶ (6000.6.8f1) آزمایش شده است. Package Manager ماژول داخلی UnityWebRequest را خودکار نصب می‌کند.

#راه‌اندازی

Boot.cs
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 بی‌خطر است: بار دوم همان کلاینت در حال اجرا را برمی‌گرداند.

#رویدادها

C#
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 روی هر رویدادی به ارزش طول عمر مشتری اضافه می‌کنند. درآمد را ببینید.

#بازیکن کیست

C#
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 بدهید، و هر بار که عوض شد دوباره:

C#
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 هستند؛ برای iOS apns. شناسهٔ دستگاه یک شناسهٔ تصادفی است که SDK در حافظهٔ خصوصی خود اپ نگه می‌دارد، هرگز advertising ID نیست.

#صف آفلاین و تلاش دوباره

رویدادها در حافظه صف می‌شوند، هر چند ثانیه و هر بار که اپ pause شود یا بسته شود در پوشهٔ خصوصی اپ ذخیره می‌شوند، و در دسته‌های ۲۰ تایی (یا هر ۱۰ ثانیه) فرستاده می‌شوند. صف ۱۰۰۰ رویداد جا دارد؛ وقتی پر شود قدیمی‌ترین دور ریخته و شمرده می‌شود.

جواب سرورکار SDK
200دسته را برمی‌دارد. موردهایی که سرور تک‌به‌تک رد کرده (rejected در جواب) دورریخته‌شده شمرده می‌شوند و دوباره تلاش نمی‌شوند. تکراری‌ها فرستاده‌شده حساب می‌شوند
بدون جواب، timeout، 5xx، 429، 408همه‌چیز را نگه می‌دارد و با انتظار رو‌به‌رشد تصادفی دوباره می‌کوشد: تا ۲، ۴، ۸ و تا ۳۰۰ ثانیه. اگر Retry-After بلندتر باشد رعایتش می‌کند
413دسته را نصف می‌کند و دوباره می‌فرستد تا جا شود. یک رویداد تکی که باز هم بزرگ است دور ریخته و شمرده می‌شود
هر 4xx دیگر (400، 401، 402، 403 و مانند آن)همان دسته را دور می‌ریزد و می‌شمارد: سرور هر بار همین‌طور ردش می‌کند. LastError کد وضعیت را نگه می‌دارد

هر رویداد از لحظهٔ ساخته شدن message_id خودش را دارد. تلاش دوباره، یا ارسالی که با کرش نیمه ماند، همان شناسه را می‌فرستد. بازهٔ تشخیص تکرار در collector قابل تنظیم است و پیش‌فرض آن ۴۸ ساعت است. تلاش دیرتر یا اختلال در ذخیرهٔ شناسه‌ها می‌تواند باعث ثبت تکراری شود.

کرش سخت می‌تواند رویدادهای ثانیه‌های آخر را از بین ببرد، چون ذخیره روی هر فراخوانی نوشته نمی‌شود.

#سلامت SDK را ببینید

C#
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 آزمایش جداگانه دارد.

قبلیSDK اندرویدبعدیثبت دستگاه

در این صفحه

  • چه کاری را SDK می‌کند و چه کاری با شماست
  • نصب
  • راه‌اندازی
  • رویدادها
  • بازیکن کیست
  • پوش
  • صف آفلاین و تلاش دوباره
  • سلامت SDK را ببینید
  • پلتفرم‌ها
  • چه چیزی در این نسخه نیست
  • چه چیزی اجرا شده و چه چیزی نه

سگمنتیک

این صفحه از روی کد نوشته شده است