راه‌اندازی سریع: از کلید تا اولین رویداد

در ده دقیقه یک کلید بسازید، اولین رویداد را بفرستید و ببینید که رسیده است. بدون SDK و فقط با یک درخواست.

برای این صفحه یک حساب سگمنتیک لازم است و یک ترمینال. نه SDK، نه npm، نه کتابخانه. در پایان صفحه یک رویداد فرستاده‌اید، در پنل دیده‌اید که رسیده، و آن را به یک کاربر مشخص وصل کرده‌اید.

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

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

#کلید بسازید

وارد پنل شوید و به https://app.segmentic.net/fa/connect بروید. در منوی کنار، این صفحه زیر «تنظیمات» است و اسمش «SDK و اتصال» است. خود صفحه «اتصال» نام دارد و چهار قدم پشت سر هم دارد: اپ، کلید، نصب، بررسی.

قدم اول، اپ. یک نام بدهید (برای نمونه «سایت اصلی»)، پلتفرم را انتخاب کنید و «افزودن» را بزنید. پلتفرم‌هایی که می‌شود انتخاب کرد: web، android، ios، windows، macos، linux و server. هر سایت یا اپ یک ردیف جدا می‌شود، چون هر ردیف کلید مستقل خودش را دارد و ابطال یکی بقیه را از کار نمی‌اندازد.

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

این کلید داخل کد عمومی سایت شما می‌نشیند و فقط اجازهٔ نوشتن رویداد دارد: نه خواندن پرونده، نه ساخت کلید دیگر. کلیدی که برای API مدیریتی لازم است چیز دیگری است، با sk_seg_ شروع می‌شود و جای دیگری ساخته می‌شود («تنظیمات» و بعد «کلیدهای API»). اگر آن را روی in.segmentic.net بفرستید پاسخ ۴۰۱ می‌گیرید.

#اولین رویداد

جای wk_seg_... کلید خودتان را بگذارید و این را در ترمینال اجرا کنید:

curl -X POST https://in.segmentic.net/v1/track \
  -H "Authorization: Bearer wk_seg_..." \
  -H "Content-Type: application/json" \
  -d '{
        "message_id": "qs-1",
        "event": "install_check",
        "anonymous_id": "quickstart-1",
        "properties": { "source": "curl" }
      }'

پاسخ:

{ "status": "ok", "accepted": 1 }

accepted تعداد رویدادهایی است که پذیرفته شده‌اند. وقتی صفر باشد در پاسخ نمی‌آید، پس نبودنش یعنی هیچ رویدادی پذیرفته نشده است.

چند نکته دربارهٔ همین یک درخواست:

• مسیر تعیین می‌کند نوع پیام چیست. /v1/track فقط رویداد track می‌سازد و اگر در بدنه فیلد type بگذارید نادیده گرفته می‌شود.
• یکی از user_id یا anonymous_id اجباری است. اگر هیچ‌کدام نباشد پاسخ ۴۰۰ است با پیام missing_identity.
• روی track، فیلد event اجباری است. نبودش پاسخ ۴۰۰ می‌دهد با پیام missing_event_name.
• timestamp اختیاری است و اگر نفرستید زمان دریافت سرور ثبت می‌شود. اگر فرستادید باید RFC 3339 باشد؛ ثانیهٔ یونیکس یا تاریخ خالی، JSON را خراب می‌کند و پاسخ ۴۰۰ می‌گیرد.
• زمان بیرون از پنجره رد نمی‌شود، کشیده می‌شود. قدیمی‌تر از پنجرهٔ نگهداری حساب به لبهٔ همان پنجره می‌رود با هشدار timestamp_too_old، و جلوتر از یک ساعت به زمان دریافت با هشدار timestamp_in_future. پاسخ در هر دو حالت ۲۰۰ است، پس اگر هشدارها را نخوانید هیچ‌وقت خبردار نمی‌شوید.
• شناسهٔ حساب و شناسهٔ اپ از خود کلید خوانده می‌شوند، نه از بدنه. ip و user-agent هم از خود اتصال گرفته می‌شوند، پس کلاینت نمی‌تواند موقعیت یا دستگاه خودش را جعل کند.
• کلید را می‌شود جای هدر Authorization در هدر X-Segmentic-Key یا در پارامتر ?write_key= هم فرستاد. سومی برای بیکن تصویری و sendBeacon است که نمی‌توانند هدر بگذارند.

#هشدار در پاسخ

حالا همان درخواست را بدون message_id بفرستید:

curl -X POST https://in.segmentic.net/v1/track \
  -H "Authorization: Bearer wk_seg_..." \
  -H "Content-Type: application/json" \
  -d '{
        "event": "install_check",
        "anonymous_id": "quickstart-1"
      }'

پاسخ همچنان ۲۰۰ است، ولی این بار چیزی همراهش می‌آید:

{
  "status": "ok",
  "accepted": 1,
  "warnings": [
    {
      "code": "generated_message_id",
      "field": "message_id",
      "note": "no message_id sent; retries of this event cannot be de-duplicated"
    }
  ]
}

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

حذف تکراری در محدودهٔ همان حساب کار می‌کند و پنجره‌اش پیش‌فرض ۴۸ ساعت است. اگر همان message_id را دوباره بفرستید، باز هم ۲۰۰ و باز هم accepted: 1 می‌گیرید و هیچ رویداد دومی ثبت نمی‌شود. پاسخ به‌عمد همان است: SDK که خطا بگیرد تا ابد دوباره می‌فرستد. تکراری هم شمارش نمی‌شود و در صورتحساب نمی‌آید.

#وقتی پاسخ ۲۰۰ نیست

فرق ۴۰۱ و ۵۰۳ عمدی است و از یک خرابی واقعی درآمده. SDK، عدد ۴۰۱ را دائمی می‌فهمد و رویداد را دور می‌ریزد؛ ۵۰۳ را گذرا می‌فهمد و نگه می‌دارد. یک بار پستگرس خاموش شد و بررسی کلید همان ۴۰۱ را برگرداند، پس هشت رویداد از هشت رویداد دور ریخته شد در حالی که کل بافر روی دیسک درست برای همین حالت ساخته شده بود. حالا خرابی سمت ما همیشه ۵۰۳ است.

متن پیام ۴۰۲ همیشه فارسی است. این میزبان هیچ میان‌افزار زبانی ندارد، پس هدر Accept-Language روی آن اثری ندارد.

روی میزبان ورود داده هیچ محدودیت نرخی وجود ندارد. تنها چیزی که حجم را کنترل می‌کند سقف رویداد همان اشتراک است که پاسخش ۴۰۲ است.

هر پاسخ، چه ۲۰۰ باشد چه خطا، هدر X-Segmentic-Trace دارد: شانزده نویسهٔ هگز که همان یک درخواست را در لاگ ما پیدا می‌کند. در هیچ بدنهٔ خطایی نمی‌آید، پس باید همان موقع از هدر برش دارید. اگر خودتان مقدار معتبری بفرستید، همان برمی‌گردد و دو طرف یک شناسه دارند. وقت باز کردن تیکت، همین یک عدد را بفرستید.

#دیدن رویداد در پنل

دو جا می‌شود دید که رویداد رسیده، و هر کدام به یک سؤال جواب می‌دهند.

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

«رویدادهای زنده»، در https://app.segmentic.net/fa/debug. در منو زیر «اتصال‌ها و یکپارچه‌سازی» است و «تست زنده اتصال» نام دارد. اینجا هر رویداد را با نام، شناسهٔ کاربر، مقدارهای ارسال‌شده و هشدارهای همان رویداد می‌بینید.

اگر رویدادی که با curl فرستادید در این صفحه نیامد، مشکل در فرستادن است نه در گزارش‌ها.

#وصل کردن رویداد به یک نفر

تا اینجا رویداد به quickstart-1 تعلق دارد، که یک شناسهٔ ناشناس است. identify همان چیزی است که یک آدم مشخص را با ویژگی‌هایش می‌سازد:

curl -X POST https://in.segmentic.net/v1/identify \
  -H "Authorization: Bearer wk_seg_..." \
  -H "Content-Type: application/json" \
  -d '{
        "message_id": "qs-2",
        "user_id": "u_123",
        "anonymous_id": "quickstart-1",
        "traits": {
          "email": "Ali@Digikala.COM",
          "phone": "09123456789",
          "city": "شيراز",
          "key_balance": 428
        }
      }'

پاسخ:

{ "status": "ok", "accepted": 1 }

چهار اتفاق افتاد که در پاسخ دیده نمی‌شوند:

• email فقط کوچک و trim شد و به ali@digikala.com تبدیل شد. هیچ اعتبارسنجی قالبی روی ایمیل انجام نمی‌شود.
• phone به شکل E.164 ذخیره شد، یعنی +989123456789، و یک ویژگی دوم به‌نام phone_operator با مقدار mci هم نوشته شد. اگر شماره معتبر نبود، مقدار خام ذخیره می‌شد، phone_operator نوشته نمی‌شد و هشدار invalid_phone برمی‌گشت.
• city نرمال شد: یای عربی به یای فارسی. بدون این کار، سگمنتی که روی «شیراز» شرط می‌گذارد کاربرانی را که با کیبورد عربی تایپ شده‌اند بی‌صدا جا می‌اندازد.
• key_balance دو بار نوشته شد: یک بار رشته با مقدار "428" و یک بار عدد با مقدار 428. نیمهٔ عددی همان چیزی است که شرط «بیشتر از ۱۰۰» را جواب می‌دهد. رشتهٔ عددی هرگز به عدد تبدیل نمی‌شود، چون "0912..." صفر ابتدایی‌اش را از دست می‌دهد و یک کد ملی بزرگ‌تر از توان پنجاه‌وسه، رقم آخرش را.

بعد از این درخواست یک پرونده با شناسهٔ u_123 وجود دارد. پیش از آن هیچ پرونده‌ای وجود نداشت: کاربر ناشناس ردیف پرونده نمی‌گیرد.

#همان درخواست از جاوااسکریپت

حالا که رویداد را با چشم خودتان دیده‌اید، نوبت SDK است.

بستهٔ @segmentic/web روی هیچ رجیستری منتشر نشده و npm install @segmentic/web شکست می‌خورد. راهی که امروز کار می‌کند تگ اسکریپت است، از همان میزبانی که رویداد به آن می‌رود، پس در سیاست امنیتی محتوای سایتتان فقط یک مبدأ اضافه می‌شود:

<script src="https://in.segmentic.net/sdk/segmentic.js"></script>
<script>
  Segmentic.init({
    writeKey: "wk_seg_...",
    apiHost: "https://in.segmentic.net"
  });
  Segmentic.track("install_check", { source: "browser" });
</script>

سه چیزی که اگر ندانید فکر می‌کنید کار نکرده است:

• SDK بلافاصله نمی‌فرستد. تا بیست پیام یا تا ده ثانیه صبر می‌کند، هرکدام زودتر برسد. await Segmentic.flush() صف را همان لحظه خالی می‌کند، ولی مقصدش POST /v1/batch است، پس نتیجه‌اش در «رویدادهای زنده» دیده نمی‌شود. تأیید رسیدن را از قدم «بررسی» صفحهٔ «اتصال» بگیرید.
• init خودش یک بازدید صفحه می‌فرستد، چون autoPageView پیش‌فرض روشن است.
• اگر مرورگر «ردیابی نکن» را روشن کرده باشد هیچ‌چیز فرستاده نمی‌شود، چون respectDoNotTrack پیش‌فرض روشن است. این اولین چیزی است که موقع «هیچ رویدادی نمی‌آید» باید بررسی کنید.

بقیهٔ متدها، صف آفلاین و پوش مرورگر در SDK وب.

#همان درخواست از سرور

همان کلید نوشتن از بک‌اند هم کار می‌کند. با پایتون:

import requests

response = requests.post(
    "https://in.segmentic.net/v1/track",
    headers={"Authorization": "Bearer wk_seg_..."},
    json={
        "message_id": "qs-3",
        "event": "order_completed",
        "user_id": "u_123",
        "properties": {"revenue": 2500000, "currency": "IRR"},
    },
    timeout=10,
)
print(response.status_code, response.json())

خروجی:

200 {'status': 'ok', 'accepted': 1}

order_completed یکی از یازده نام استاندارد است و همان چیزی است که قیف‌ها و سناریوهای آماده روی آن سوارند. revenue هم از روی همین ویژگی برداشته می‌شود؛ اگر نبود، total و بعد value و در آخر price ضربدر quantity امتحان می‌شوند. واحد پول اگر گفته نشود IRR است و هیچ تبدیلی حدس زده نمی‌شود.

برای رویدادی که فقط بک‌اند شما از آن مطمئن است، یک در دوم هم هست: POST /v1/events روی https://api.segmentic.net با کلید sk_seg_. آن در دو تفاوت دارد که هر دو بی‌صدا هستند: تکراری‌ها را حذف نمی‌کند، پس همان message_id دو بار فرستاده‌شده دو رویداد می‌شود؛ و پنجرهٔ زمانش ثابت سی روز است، پس هر زمانی قدیمی‌تر از آن به لبهٔ سی روز کشیده می‌شود و هشدارش هم دور ریخته می‌شود. برای همین است که تاریخچه را از این در منتقل نکنید. تفاوت‌ها در سرور به سرور.

#بعد چه بخوانید

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