رویدادها و ردیابی

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

نمایش دیده‌شده (Viewed impression)

وقتی حداقل ۵۰٪ از تبلیغ برای حداقل ۱ ثانیه پیوسته در viewport کاربر بود (برای ویدیو ۵ ثانیه)، همه‌ی لینک‌های viewedImpressionUrls را یک بار فراخوانی کنید.

• viewedImpressionUrls علاوه بر لینک یکتانت ممکن است شامل لینک‌های دیگری نیز باشد. همه را فراخوانی کنید.
• هر لینک فقط یک بار معتبر است. آن را دوباره فراخوانی نکنید.
• پیشنهاد: navigator.sendBeacon که حتی هنگام بسته شدن صفحه هم ارسال می‌شود؛ در غیر این صورت fetch با keepalive یا new Image().src.

function fire(url) {
  if (navigator.sendBeacon && navigator.sendBeacon(url)) return;
  fetch(url, {method: 'GET', mode: 'no-cors', credentials: 'include', keepalive: true});
}

function observeViewability(el, urls, minVisibleMs = 1000) {
  let timer = null;
  const observer = new IntersectionObserver(([entry]) => {
    if (entry.intersectionRatio >= 0.5) {
      timer ??= setTimeout(() => {
        urls.forEach(fire);
        observer.disconnect();
      }, minVisibleMs);
    } else {
      clearTimeout(timer);
      timer = null;
    }
  }, {threshold: [0, 0.5]});
  observer.observe(el);
}

// تبلیغ تصویری:
observeViewability(slotEl, ad.viewedImpressionUrls);
// تبلیغ ویدیویی (۵ ثانیه):
observeViewability(playerEl, ad.viewedImpressionUrls, 5000);

اطلاع

اگر کاربر تب را عوض کند (document.visibilityState === 'hidden')، تایمر را متوقف کنید؛ تبلیغی که کاربر واقعاً ندیده نباید «دیده‌شده» ثبت شود.

در اپ‌های بومی از معادل همین منطق استفاده کنید (مثلاً در اندروید با ViewTreeObserver و محاسبه‌ی درصد نمایان بودن view).

کلیک

• clickUrl را همان‌طور که هست به‌عنوان لینک تبلیغ قرار دهید. یکتانت کلیک را ثبت و کاربر را به صفحه‌ی تبلیغ‌کننده redirect می‌کند. کلیک فقط در صورت redirect موفق شمرده می‌شود.
• لینک را در تب جدید (target="_blank") باز کنید.
• روی لینک‌ها rel="nofollow" بگذارید تا خزنده‌های موتورهای جستجو روی تبلیغ کلیک نکنند.
• در اپ‌ها، لینک را در مرورگر (نه WebView) باز کنید. چرا؟

نشست (Session)

اگر اسکریپت نمایش‌دهندگان را نصب کرده باشید، نیازی به پیاده‌سازی نشست ندارید. در غیر این صورت:

1. در اولین بازدید یک UUID بسازید و به همراه زمان آخرین فعالیت ذخیره کنید.
2. در هر تعامل کاربر (یا هر ۵ تا ۱۰ ثانیه تا وقتی کاربر فعال است) زمان آخرین فعالیت را به‌روز کنید.
3. اگر بیش از ۳۰ دقیقه از آخرین فعالیت گذشته بود، UUID جدید بسازید.
4. مقدار را در user.sessionToken بفرستید.

const SESSION_KEY = 'yn_partner_session';
const SESSION_TTL_MS = 30 * 60 * 1000;

function getSessionToken() {
  const now = Date.now();
  let session = null;
  try { session = JSON.parse(localStorage.getItem(SESSION_KEY)); } catch {}
  if (!session || now - session.lastActive > SESSION_TTL_MS) {
    session = {token: crypto.randomUUID(), lastActive: now};
  }
  session.lastActive = now;
  try { localStorage.setItem(SESSION_KEY, JSON.stringify(session)); } catch {}
  return session.token;
}