BidRequest

هر بار که صفحه‌ای از سایت یک نمایش‌دهنده باز می‌شود و امکان نمایش تبلیغ وجود دارد، یک BidRequest به DSPها ارسال می‌شود. هر درخواست یک یا چند Imp (هر جایگاه یک Imp) دارد.

نمونه‌ی درخواست

در این نمونه، عضو اول imp یک جایگاه همسان (native) و عضو دوم یک جایگاه بنر است:

{
  "id": "8141592653589793",
  "imp": [
    {
      "id": "1486",
      "tagid": "1486",
      "bidfloor": 10000,
      "bidfloorcur": "IRR",
      "native": {
        "request_native": {
          "plcmtcnt": 6,
          "assets": [
            {"id": 1, "required": true, "title": {"len": 70}},
            {"id": 2, "required": true, "img": {"type": 3, "w": 300, "h": 450}},
            {"id": 3, "required": false, "img": {"type": 2}},
            {"id": 4, "required": false, "img": {"type": 1}},
            {"id": 5, "required": false, "data": {"type": 502}},
            {"id": 6, "required": false, "data": {"type": 501}},
            {"id": 7, "required": false, "data": {"type": 6}},
            {"id": 8, "required": false, "data": {"type": 12}},
            {"id": 9, "required": false, "data": {"type": 1}}
          ]
        }
      }
    },
    {
      "id": "1521",
      "tagid": "1521",
      "bidfloor": 21000,
      "bidfloorcur": "IRR",
      "banner": {"w": 300, "h": 250}
    }
  ],
  "at": 1,
  "tmax": 200,
  "cur": ["IRR"],
  "device": {
    "ua": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:85.0) Gecko/20100101 Firefox/85.0",
    "ip": "81.90.149.130",
    "w": 1920,
    "h": 1080,
    "dnt": false,
    "devicetype": 2,
    "os": "OS_TYPE_WINDOWS",
    "osv": "OS_VERSION_OTHER",
    "make": "DEVICE_BRAND_ASUS",
    "geo": {"country": "IRN", "region": "23"}
  },
  "user": {"id": "3545f8bf-fc9d-4950-4668-176bb2bf434c"},
  "site": {
    "publisher": {"id": "yn-rtb", "name": "Yektanet", "domain": "yektanet.com"}
  }
}

اطلاع

درخواست‌ها با gRPC و Protocol Buffers ارسال می‌شوند؛ JSON بالا فقط برای خوانایی است و نام فیلدها همان نام‌های openrtb.proto است.

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

فیلد	مقدار
id	شناسه‌ی یکتای درخواست (عدد به‌صورت رشته).
imp[]	جایگاه‌های پیشنهادی؛ پایین را ببینید.
at	FIRST_PRICE (۱).
tmax	۲۰۰ میلی‌ثانیه.
cur	["IRR"]
site یا app	site برای ترافیک وب، app برای ترافیک اپ (ادیوری).
device	اطلاعات دستگاه.
user.id	وب: شناسه‌ی کاربر یکتانت. اپ: Google Advertising ID.

Imp

فیلد	مقدار
id	شناسه‌ی جایگاه. impid در پاسخ باید دقیقاً همین مقدار باشد.
tagid	همان شناسه‌ی جایگاه.
bidfloor	حداقل قیمت (CPM، ریال). پیشنهادهای کمتر از آن حذف می‌شوند.
bidfloorcur	IRR
native / banner	بسته به نوع جایگاه، یکی از این دو (پایین).
instl	true برای جایگاه‌های میان‌صفحه‌ای و app open موبایل.

Native

imp.native.request_native یک NativeRequest است. plcmtcnt تعداد اسلات‌های جایگاه است: می‌توانید تا همین تعداد bid برای آن imp برگردانید. هر asset با id ثابت درخواست می‌شود و در پاسخ باید با همان id برگردد:

id	Asset	نوع	توضیح
۱	Title	title (len ≤ ۷۰)	عنوان تبلیغ
۲	Main image	img type=MAIN	وب: ۳۰۰×۴۵۰. موبایل: حداقل ۶۴۰×۳۶۰، image/jpeg یا image/gif
۳	Logo	img type=LOGO	لوگوی تبلیغ‌کننده، در ابعاد ۳۲۰×۸۰
۴	Icon / watermark	img type=ICON	آیکون، در ابعاد ۱۰۰×۱۰۰
۵	Color	data type=COLOR	رنگ دکمه‌ی CTA، کد hex بدون # (مثلاً f2ef1f)
۶	Discount	data type=DISCOUNT	درصد تخفیف، عدد صحیح بین ۱ و ۹۹
۷	Price	data type=PRICE	قیمت به ریال، عدد صحیح مثبت
۸	CTA text	data type=CTATEXT	متن دکمه
۹	Sponsored	data type=SPONSORED	نام برند
۱۰	Video	video	فقط در جایگاه‌های مقاله، برای DSPهای فعال‌شده
۱۱	Description	data type=DESC	توضیح (موبایل)
۱۲	Network logo	img type=LOGO	لوگوی شبکه‌ی DSP؛ فقط برای DSPهایی که نمایش لوگوی خودشان را خواسته‌اند

assetهای الزامی در پاسخ:

• Native وب: 1 (عنوان) و 2 (تصویر). بقیه اختیاری‌اند، اما اگر ارسال شوند نوعشان باید درست باشد.
• جایگاه مقاله با ویدیو: دقیقاً یکی از 2 (تصویر) یا 10 (ویدیو). اگر تصویر برگردد، عنوان هم الزامی است.
• موبایل (اپ): 1، 2، 4، 8، 9 و 11 الزامی‌اند.

ویدیو

جایگاه‌های موبایل: video/mp4 یا video/quicktime، ۳ تا ۶۰ ثانیه، VAST 3.0، progressive. جایگاه‌های مقاله‌ی وب: application/x-mpegURL (HLS)، ۱ تا ۶۰۰ ثانیه، VAST 3.0، streaming. در هر دو حالت ویدیو باید با vasttag (VAST inline با حداقل یک Linear و یک MediaFile) برگردد. ویدیوی Wrapper پشتیبانی نمی‌شود.

Banner

imp.banner شامل w و h جایگاه است. پاسخ در adm یک HTML برمی‌گردد (پایین را ببینید).

Site (ترافیک وب)

فیلد	مقدار
id	شناسه‌ی ناشر در یکتانت.
domain	دامنه‌ی اصلی صفحه (مثلاً sub.example.com ← example.com).
page	آدرس صفحه (در AMP فقط دامنه).
content.title	عنوان صفحه.
search	توضیحات صفحه.
cat	دسته‌بندی IAB صفحه (v2).
publisher	همیشه یکتانت: {id: "yn-rtb", name: "Yektanet", domain: "yektanet.com"}

App (ترافیک اپ)

فیلد	مقدار
id	شناسه‌ی ناشر.
name	نام ناشر.
publisher	همیشه یکتانت (مانند بالا).

اطلاع

بسته به قرارداد، ممکن است اطلاعات ناشر (site.id، domain، page و…) برای برخی DSPها ارسال نشود. در این حالت فقط publisher یکتانت پر است.

Device

فیلد	مقدار
ua	User-Agent
ip	IP کاربر
w, h	ابعاد صفحه
dnt	Do-Not-Track
devicetype	PERSONAL_COMPUTER (دسکتاپ) یا MOBILE (وب موبایل و اپ)
os, osv, make	سیستم‌عامل، نسخه و برند دستگاه
geo.country	کشور؛ همیشه IRN.
geo.region	کد استان طبق جدول زیر (ISO 3166-2:IR).

کدهای استان

geo.region	استان
00	مرکزی
01	گیلان
02	مازندران
03	آذربایجان شرقی
04	آذربایجان غربی
05	کرمانشاه
06	خوزستان
07	فارس
08	کرمان
09	خراسان رضوی
10	اصفهان
11	سیستان و بلوچستان
12	کردستان
13	همدان
14	چهارمحال و بختیاری
15	لرستان
16	ایلام
17	کهگیلویه و بویراحمد
18	بوشهر
19	زنجان
20	سمنان
21	یزد
22	هرمزگان
23	تهران
24	اردبیل
25	قم
26	قزوین
27	گلستان
28	خراسان شمالی
29	خراسان جنوبی
30	البرز