پاسخ و نمایش تبلیغ

ساختار پاسخ

{
  "positions": [
    {
      "id": 4294973520,
      "ads": [
        {
          "title": "کلینیک دندان‌پزشکی در شمال تهران",
          "clickUrl": "https://event.yektanet.com/api/click/v1/collect?...",
          "viewedImpressionUrls": [
            "https://event.yektanet.com/api/viewed-impression/v1/collect?..."
          ],
          "ctaText": "بهترینو ببین!",
          "ctaColor": "#0f197d",
          "brandTitle": "بهترینو",
          "brandLogoUrl": "https://core-cdn.yektanet.com/media/clients/logo.png",
          "imageUrl": "https://prod.yektanet.com/media/images/thumbnails/300x200/...",
          "imageWidth": 300,
          "imageHeight": 200
        }
      ]
    }
  ]
}

هر عضو ads یعنی یک اسلات پرشده. اسلات‌ها به ترتیب از اسلات اول (بالا-راست) پر می‌شوند.
جایگاهی که هیچ تبلیغی برایش پیدا نشده در پاسخ نمی‌آید. نرخ پر شدن (fill rate) را از مقایسه‌ی جایگاه‌های درخواستی با جایگاه‌های برگشتی محاسبه کنید.
ممکن است پاسخ کاملاً خالی باشد (بدنه‌ی خالی با کد ۲۰۰). کلاینت شما باید این حالت را مدیریت کند و جایگاه را پنهان کند.

کدهای وضعیت

کد	معنی
`200`	موفق. ممکن است بدنه خالی یا بدون جایگاه باشد.
`400`	بدنه نامعتبر است (فیلد الزامی نیامده، مقدار `environment` نامعتبر و…).
`503`	سرویس موقتاً در دسترس نیست. جایگاه را خالی بگذارید و درخواست را تکرار نکنید.

فیلدهای تبلیغ

فیلد	همیشه	توضیح
`title`	✅	عنوان تبلیغ.
`clickUrl`	✅	لینک کلیک. کاربر باید روی همین لینک کلیک کند تا یکتانت او را به صفحه‌ی تبلیغ‌کننده هدایت کند. آن را تغییر ندهید.
`viewedImpressionUrls`	✅	لینک‌هایی که همه‌شان باید وقتی تبلیغ دیده شد فراخوانی شوند. جزئیات
`ctaText`	✅	متن دکمه‌ی فراخوان (CTA).
`ctaColor`	✅	رنگ دکمه‌ی CTA به فرمت `#rrggbb` با حروف کوچک.
`imageUrl`	✅	تصویر اصلی تبلیغ (از CDN یکتانت).
`imageWidth`, `imageHeight`		ابعاد واقعی تصویر به پیکسل.
`brandTitle`		نام برند تبلیغ‌کننده.
`brandLogoUrl`		لوگوی برند.
`backgroundImageUrl`		تصویر پس‌زمینه.
`faviconUrl`		favicon صفحه‌ی مقصد؛ فقط در جایگاه‌های جستجو.
`vastXml`		اگر تبلیغ ویدیویی باشد، متن کامل VAST XML که مستقیماً به پلیر داده می‌شود.
`product`		اگر وجود داشته باشد، تبلیغ محصول است.

تبلیغ ویدیویی (`vastXml`)

اگر تبلیغ ویدیویی باشد، vastXml متن کامل یک سند VAST است. آن را مستقیماً به پلیر ویدیوی خود بدهید (مثلاً به‌صورت متن VAST یا data URI، بسته به اینکه پلیر کدام را می‌پذیرد) تا پلیر تبلیغ را پخش کند و رویدادهای VAST را خودش فراخوانی کند.

تبلیغ محصول (`product`)

فیلد	توضیح
`priceRials`	قیمت به ریال.
`discountPercent`	درصد تخفیف (۰ تا ۱۰۰).

ساختار نمایش یک تبلیغ

تبلیغimageUrl

عنوان تبلیغtitle

۲٬۴۹۰٬۰۰۰ ریال ٪۱۵product

نام برندbrandLogoUrl · brandTitle

مشاهدهctaText · ctaColor

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

پیشنهاد می‌شود از تبلیغات display (تصویری) شروع کنید، سپس محصول و در نهایت ویدیو را اضافه کنید.

برچسب تبلیغ

تبلیغ را به‌وضوح از محتوای خودتان متمایز کنید (مثلاً با برچسب «تبلیغ»). این کار هم به اعتماد کاربر کمک می‌کند و هم برای برخی تبلیغ‌کنندگان الزامی است.

نمونه‌ی رندر

function renderAd(slotEl, ad) {
  const link = document.createElement('a');
  link.href = ad.clickUrl;
  link.target = '_blank';
  link.rel = 'nofollow noopener';
  link.innerHTML = `
    <img src="${ad.imageUrl}" alt="" style="width:100%;aspect-ratio:3/2;object-fit:cover">
    <p class="ad-title"></p>
    <span class="ad-cta" style="background:${ad.ctaColor}"></span>`;
  link.querySelector('.ad-title').textContent = ad.title;
  link.querySelector('.ad-cta').textContent = ad.ctaText;
  slotEl.replaceChildren(link);
  observeViewability(slotEl, ad.viewedImpressionUrls); // صفحه‌ی «رویدادها»
}

اطلاع

متن‌ها (title، ctaText، brandTitle) را با textContent قرار دهید، نه innerHTML.

ساختار پاسخ​

کدهای وضعیت​

فیلدهای تبلیغ​

تبلیغ ویدیویی (vastXml)​

تبلیغ محصول (product)​

ساختار نمایش یک تبلیغ​

نمونه‌ی رندر​