Partners API

با Partners API تبلیغات را به‌صورت داده‌ی خام JSON دریافت می‌کنید و با طراحی خودتان نمایش می‌دهید. این روش در هر محیطی (وب، PWA، اپ بومی) قابل استفاده است.

جریان کامل یک درخواست در Partners API

خلاصه

آدرس	POST https://jamssp.yektanet.com/api/v1/partners/ads
ورودی	context شامل اطلاعات کاربر (user)، صفحه (page) و جایگاه‌ها (positions)
خروجی	فهرست تبلیغ‌ها برای هر جایگاه
فرمت	application/json
احراز هویت	ندارد؛ شناسه‌ی جایگاه‌ها ناشر را مشخص می‌کند
سازگاری	تغییرات همیشه backward compatible هستند

نمونه‌ی سریع

curl 'https://jamssp.yektanet.com/api/v1/partners/ads' \
  -H 'content-type: application/json' \
  --data-raw '{
    "requestId": "199fea34-bfe2-43eb-b8fd-4eec4a344ff8",
    "debug": true,
    "user": {
      "environment": "desktop",
      "sessionToken": "df846d5e-72db-524e-b1f2-6ea1eee1ad0f",
      "screenWidth": 1440,
      "screenHeight": 900,
      "searchQuery": "کفش آدیداس"
    },
    "page": {
      "url": "https://example.com/search?q=shoes",
      "title": "خرید لوازم ورزشی",
      "description": "خرید کفش ورزشی مردانه"
    },
    "positions": [{"id": 4294973520, "slotCount": 3}]
  }'

همیشه در تست‌ها debug: true

درخواست‌های بدون debug: true واقعی حساب می‌شوند: از تبلیغ‌کننده هزینه کسر و به ناشر درآمد پرداخت می‌شود. در همه‌ی درخواست‌های آزمایشی این فیلد را true بگذارید و در محیط production حذفش کنید.

درخواست را از کجا بفرستیم؟

درخواست را مستقیماً از دستگاه کاربر (مرورگر یا اپ) بفرستید، نه از سرور خودتان. یکتانت آدرس IP، User-Agent و کوکی شناسه‌ی کاربر را از خود درخواست HTTP می‌خواند. این اطلاعات برای هدف‌گیری، تشخیص موقعیت و جلوگیری از تقلب ضروری است. در درخواست سرور به سرور این اطلاعات از بین می‌رود و درآمد شما کاهش می‌یابد. اگر ناچار به فراخوانی سمت سرور هستید، پیش از پیاده‌سازی با تیم یکتانت هماهنگ کنید.

API از CORS پشتیبانی می‌کند و از هر دامنه‌ای قابل فراخوانی است.

مراحل پیاده‌سازی

1. ساخت حساب نمایش‌دهنده و تعریف جایگاه‌ها با راهنمایی تیم یکتانت، و دریافت position IDها.
2. فقط وب/PWA: اسکریپت نمایش‌دهندگان را هم نصب کنید تا شناسه‌ی کاربر (کوکی _yngt) و نشست ساخته شوند. لازم نیست جایگاهی از طریق اسکریپت تعریف کنید.
3. ساخت درخواست
4. نمایش پاسخ
5. فراخوانی رویدادها: نمایش دیده‌شده، کلیک و نشست.
6. تست و هماهنگی با تیم یکتانت برای رفتن به production.

مرجع کامل فیلدها: مرجع Partners API