ساخت درخواست

POST /api/v1/partners/ads HTTP/1.1
Host: jamssp.yektanet.com
Content-Type: application/json

بدنه‌ی درخواست از چهار بخش اصلی تشکیل می‌شود:

{
  "requestId": "9b0f5a4e-2e4e-4a1f-88a8-d0fce5e5b1f1",
  "debug": false,
  "user": { ... },
  "page": { ... },
  "positions": [ ... ]
}

فیلدهای سطح بالا

فیلد	نوع	الزامی	توضیح
requestId	string	✅	شناسه‌ی یکتای هر درخواست (پیشنهاد: UUID v4). برای حذف درخواست‌های تکراری استفاده می‌شود. برای هر بار بارگذاری صفحه یا هر صفحه‌ی جدید از یک لیست، مقدار جدید بسازید.
debug	boolean		اگر true باشد، هیچ هزینه یا درآمدی ثبت نمی‌شود. فقط در تست.
user	object	✅	اطلاعات کاربر و دستگاه.
page	object		اطلاعات صفحه.
positions	array	✅	جایگاه‌هایی که باید پر شوند (حداقل یکی).

کاربر (user)

فیلد	نوع	الزامی	توضیح
environment	string	✅	یکی از mobile (اپ بومی)، mobile-pwa (وب موبایل / PWA)، desktop. برای نمایش تبلیغ مناسب ضروری است؛ مثلاً تبلیغ نصب اپ در دسکتاپ بی‌فایده است.
sessionToken	string		توکن نشست (UUID). تا وقتی کاربر فعال است ثابت بماند و پس از ۳۰ دقیقه عدم فعالیت عوض شود. جزئیات
gaid	string		Google Advertising ID (UUID) در اپ‌های اندروید. مقدار صفر یا نامعتبر نادیده گرفته می‌شود. بدون آن، کمپین‌هایی که به attribution نصب نیاز دارند نمایش داده نمی‌شوند.
platformId	string		شناسه‌ی کاربر در سیستم شما، فقط برای کاربران لاگین‌شده. به شمارش دقیق کاربران یکتا و جلوگیری از نمایش تبلیغ تکراری یا اسپم کمک می‌کند. برای کاربر مهمان خالی بگذارید.
screenWidth	integer		عرض صفحه‌ی نمایش به پیکسل.
screenHeight	integer		ارتفاع صفحه‌ی نمایش به پیکسل.
searchQuery	string		عبارتی که کاربر جستجو کرده است (در صفحات نتایج جستجو). تبلیغات مرتبط‌تری برمی‌گرداند و از تجربه‌ی کاربری محافظت می‌کند.

شناسه‌ی کاربر در وب

در وب و PWA، شناسه‌ی کاربر یکتانت در کوکی _yngt روی دامنه‌ی یکتانت نگه‌داری می‌شود و توسط اسکریپت نمایش‌دهندگان ساخته می‌شود. برای اینکه مرورگر این کوکی را بفرستد، درخواست را با credentials: 'include' ارسال کنید (پایین را ببینید).

در WebView داخل اپ، کوکی‌ها با هر بار باز شدن WebView پاک می‌شوند. برای شناسایی بهتر کاربر، پس از کلیک روی تبلیغ لینک را در مرورگر (Chrome) باز کنید، نه WebView. TWA از کوکی‌های Chrome استفاده می‌کند و مشکلی ندارد.

صفحه (page)

فیلد	نوع	توضیح
url	string	آدرس کامل صفحه.
title	string	عنوان صفحه (<title>).
description	string	توضیحات صفحه (<meta name="description">).
referer	string	آدرس صفحه‌ی قبلی (با یک r، مطابق هدر HTTP).
breadcrumbs	string[]	مسیر دسته‌بندی صفحه، مثلاً ["خودرو", "سواری", "پراید"]. برای صفحات لیستی مفید است.

url، title و description یکتانت را از محتوای اطراف تبلیغ آگاه می‌کنند و در وب (mobile-pwa و desktop) باید ارسال شوند. در اپ بومی (mobile) می‌توانند خالی باشند.

اطلاع

breadcrumbs برای سازگاری با نسخه‌های آینده پذیرفته می‌شود و فعلاً در انتخاب تبلیغ اثری ندارد. ارسال آن از همین حالا پیشنهاد می‌شود.

جایگاه‌ها (positions)

فیلد	نوع	الزامی	توضیح
id	integer	✅	شناسه‌ی جایگاه برای درخواست: شناسه‌ی پنل ناشر به‌علاوه‌ی یک عدد ثابت بر اساس نوع جایگاه. محاسبه‌گر
slotCount	integer	✅	تعداد اسلاتی که می‌خواهید پر شود.

در یک درخواست می‌توانید چند جایگاه را با هم بخواهید. بهتر است همه‌ی جایگاه‌های یک صفحه را در یک درخواست بفرستید تا یکتانت از نمایش تبلیغ تکراری در آن صفحه جلوگیری کند.

فیلدهای سفارشی

اگر داده‌ی دیگری دارید که به هدف‌گیری کمک می‌کند (مثلاً شهر یا استان کاربر یا دسته‌بندی اختصاصی)، با تیم یکتانت هماهنگ کنید تا راه مناسب را پیدا کنیم.

نمونه در مرورگر

async function loadYektanetAds(positions) {
  const response = await fetch('https://jamssp.yektanet.com/api/v1/partners/ads', {
    method: 'POST',
    credentials: 'include', // کوکی شناسه‌ی کاربر یکتانت ارسال شود
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      requestId: crypto.randomUUID(),
      user: {
        environment: window.matchMedia('(max-width: 768px)').matches ? 'mobile-pwa' : 'desktop',
        sessionToken: getSessionToken(), // پیاده‌سازی: صفحه‌ی «رویدادها»
        screenWidth: window.screen.width,
        screenHeight: window.screen.height,
      },
      page: {
        url: location.href,
        title: document.title,
        description: document.querySelector('meta[name="description"]')?.content ?? '',
        referer: document.referrer,
      },
      positions, // مثلاً [{id: 4294973520, slotCount: 2}]
    }),
  });
  if (!response.ok) return [];
  const text = await response.text();
  return text ? JSON.parse(text).positions : [];
}