ردیابی سمت سرور

کی سراغ سمت سرور بروید#

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

هر دو مسیر به یک جدول رویداد می‌نویسند و یک گراف هویت را تغذیه می‌کنند. لازم نیست یکی را به نفع دیگری کنار بگذارید؛ اما یک رویداد را از هر دو مسیر نفرستید، چون شناسه‌های آن دو مسیر یکی نیستند و دو ردیف مستقل می‌شوند.

کلید سرور بسازید#

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

چهار دامنه دسترسی وجود دارد و کمترین مجموعه لازم را بدهید:

ساختن کلید در سطح «ویرایش گر» به بالا ممکن است؛ دیدن فهرست کلیدها با دسترسی خواندن گزارش هم کافی است — ولی فهرست فقط پیشوند را نشان می‌دهد، نه رمز را.

اولین رویداد را بفرستید#

پایه آدرس https://api.adpix.io/api/v1/s2s است. هر درخواست دو چیز را با خود می‌آورد: کلید در هدر Authorization و شناسه دارایی در هدر X-Sov-Site.

curl -X POST https://api.adpix.io/api/v1/s2s/events \
  -H 'Authorization: Bearer sk_...' \
  -H 'X-Sov-Site: <property_id>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "purchase",
    "event_id": "order_10482",
    "order_id": "10482",
    "email": "ali@example.com",
    "value": 4900000,
    "currency": "IRR",
    "properties": { "gateway": "saman" }
  }'

{
  "accepted": true,
  "event_id": "order_10482",
  "global_user_id": "...",
  "anonymous_linked": true,
  "attribution_snapshot": { "channel": "Paid Search", "attribution_model": "last_non_direct" },
  "request_id": "req_..."
}

پیش از سیم کشی کامل، یک بار POST /api/v1/s2s/verify را صدا بزنید. اگر کلید و دارایی با هم بخوانند، پاسخ نام و منطقه زمانی دارایی، دامنه‌های کلید، طول پنجره اتریبیوشن و اجباری بودن یا نبودن HMAC را برمی‌گرداند — دقیقا همان چیزی که برای عیب یابی تنظیمات لازم دارید.

از میدان های بدنه، فقط event و event_id الزامی‌اند. value و currency برای درآمد است (کد ارز باید سه حرف بزرگ باشد)، items سطرهای سفارش را می‌سازد، و هر چیز دیگری را در properties بگذارید تا در گزارش‌ها به عنوان پارامتر رویداد در دسترس باشد.

event_id — ضامن اینکه یک سفارش دو بار شمرده نشود#

این مهم ترین قاعده این صفحه است. event_id را شما تعیین می‌کنید و باید در سیستم شما به طور پایدار همان رویداد را نشان دهد — مثلا order_10482، نه یک عدد تصادفی تازه در هر تلاش.

ادپیکس پاسخ اولین ارسال هر event_id را به همراه اثر انگشت بدنه درخواست نگه می‌دارد. بعد از آن:

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

بازدیدکننده را به کاربر واقعی وصل کنید#

هر رویداد باید بگوید موضوعش کیست. چهار راه دارید و می‌توانید بیش از یکی را با هم بفرستید:

• anonymous_id — همان شناسه ناشناسی که مرورگر ساخته است. اگر این را بفرستید، رفتار پیش از ورود کاربر هم به همین شخص می‌چسبد.
• external_id — شناسه کاربر در سیستم خودتان (شناسه مشتری CRM، شناسه کاربر پنل).
• email — قطعی.
• phone — قطعی و هم رتبه ایمیل. شماره با کد کشور پیش‌فرض دارایی به شکل بین المللی نرمال می‌شود، پس شماره ملی ۰۹۱۲… و شکل بین المللی همان شماره به یک کاربر می‌رسند.

ایمیل، شماره و شناسه بیرونی لینک های قطعی اند و هیچ وقت با حدس اثر انگشت مرورگر بازنویسی نمی‌شوند. برای لحظه ورود یا ثبت نام — جایی که هنوز رویداد کسب‌وکاری ندارید — POST /identify را صدا بزنید؛ همان لینک را برقرار می‌کند و شناسه کاربر سراسری، شناسه‌های ناشناس مرتبط و اتریبیوشن فعلی او را برمی‌گرداند. منطق کامل در ادپیکس چطور بازدیدکننده ها را می‌شناسد آمده است.

سفارش ها و عکس فوری اتریبیوشن#

اگر order_id بفرستید (یا رویداد را purchase، order_updated، order_refunded بنامید و شناسه سفارش را همراه کنید)، ادپیکس یک عکس فوری اتریبیوشن برای آن سفارش می‌سازد و منجمد می‌کند: کانال، منبع، کمپین، اولین و آخرین برخورد، فاصله روزها تا تبدیل و تعداد برخوردها.

سرمشق این عکس فوری «آخرین برخورد غیرمستقیم» است: اگر آخرین برخورد مستقیم یا خالی باشد، اولین برخورد جای آن را می‌گیرد.

عکس فوری یک بار نوشته می‌شود. به روزرسانی بعدی همان سفارش، مقدار و وضعیت را می‌آورد ولی اتریبیوشن دست نخورده می‌ماند — یعنی گزارش شما با تغییر رفتار بعدی مشتری بازنویسی نمی‌شود. برای خواندنش:

curl 'https://api.adpix.io/api/v1/s2s/attribution?order_id=10482' \
  -H 'Authorization: Bearer sk_...' \
  -H 'X-Sov-Site: <property_id>'

ارسال دسته ای#

برای پرکردن گذشته یا صف شبانه، POST /events/batch با بدنه {"events":[…]} بفرستید. سقف هر درخواست ۵۰۰ رویداد است؛ بیشتر از آن پاسخ ۴۱۳ می‌گیرد.

پاسخ یک آرایه results است، به همان ترتیب ورودی و یک نتیجه به ازای هر رویداد. یک رویداد نامعتبر بقیه را زمین نمی‌زند — نتیجه خودش خطا می‌شود و بقیه پذیرفته می‌شوند. بنابراین همیشه results را بخوانید؛ کد وضعیت کلی درخواست کافی نیست.

امضای HMAC#

اگر هنگام ساخت کلید «نیازمند HMAC» را تیک زده باشید، هر درخواست باید امضا هم داشته باشد. رشته امضا <timestamp>.<بدنه خام> است و کلید امضا همان رمز sk_…:

X-Sov-Timestamp: 1767225600
X-Sov-Signature: t=1767225600,v1=<hex(HMAC-SHA256)>

اختلاف زمان بیش از ۳۰۰ ثانیه با ساعت سرور، پاسخ stale_timestamp می‌گیرد — پس ساعت سرورتان باید همگام باشد. امضا روی بایت های خام بدنه حساب می‌شود، نه روی JSON بازتولیدشده؛ اگر بدنه را دوباره سریال کنید امضا نمی‌خواند.

اگر هدر امضا را بفرستید، حتی وقتی کلید HMAC را اجباری نکرده باشد، بررسی می‌شود.

این رویدادها در گزارش‌ها چه شکلی‌اند#

چند تفاوت عمدی با رویدادهای مرورگر هست که اگر ندانید، خیال می‌کنید داده گم شده است.

• نشست ندارند. یک رویداد سمت سرور نشست مرورگری نیست و ادپیکس برایش نشست نمی‌سازد. اگر می‌ساخت، هر سفارش CRM یک «نشست» تازه می‌شد و نرخ تبدیل را کوچک نشان می‌داد. نتیجه: این رویدادها در سنجه های نشست محور (نرخ تعامل، نشست به ازای کاربر) شمرده نمی‌شوند، ولی در شمارش رویداد، رویداد کلیدی، درآمد و اتریبیوشن کاربر کاملا حاضرند.
• آدرس صفحه ندارند. گزارش‌های صفحه محور آن‌ها را نشان نمی‌دهند.
• اتریبیوشنشان از تاریخچه همان کاربر می‌آید. اگر در context مقدار first_touch یا last_touch بفرستید همان به کار می‌رود؛ وگرنه ادپیکس سراغ اولین برخورد ماندگاری می‌رود که از مسیر مرورگر برای آن بازدیدکننده ذخیره کرده است. برای همین است که فرستادن anonymous_id تفاوت ایجاد می‌کند: بدون آن، سفارش به کمپینی که واقعا آن را آورده وصل نمی‌شود.
• موقعیت جغرافیایی و دستگاه از context می‌آید. context.ip و context.user_agent را بفرستید تا کشور و نوع دستگاه پر شود؛ اگر نفرستید خالی می‌ماند، چون IP سرور شما جای IP کاربر را نمی‌گیرد.

خطاها#

همه خطاها JSON برمی گردانند و همیشه یک request_id دارند. اگر تیکت می‌زنید، همان را بفرستید.

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

اندپوینت قدیمی /api/v1/track#

یک مسیر قدیمی تر هم هست که همان پوشش رویداد تگ مرورگر را با کلید سرور می‌پذیرد. هدر دارایی نمی‌گیرد، عکس فوری اتریبیوشن نمی‌سازد و هیچ تضمینی درباره ارسال دوباره نمی‌دهد. فقط برای یکپارچه سازی های قدیمی نگه داشته شده است؛ کار تازه را روی /api/v1/s2s/events بنویسید.

شکل کامل درخواست‌ها و پاسخ‌ها، برای وقتی که خودتان کلاینت می‌نویسید، در مرجع API سرور به سرور است.

پرسش‌های پرتکرار#

مطالب مرتبط#