هدف گذاری عامل کاربر

هدر User-Agent از گذشته در درخواست‌های پیشنهاد قیمت گنجانده شده است تا داده‌های هدف‌گیری مفیدی مانند مرورگر و پلتفرم دستگاه آغازگر ارائه دهد. با این حال، مرورگرها اغلب به دلیل دشواری استفاده از User-Agent و برای محافظت بهتر از حریم خصوصی کاربر، آن را به شدت ویرایش می‌کنند. در پاسخ به این موضوع، گوگل از User-Agent Client Hints پشتیبانی می‌کند که در صورت وجود، در درخواست‌های پیشنهاد قیمت گنجانده می‌شوند تا هدر User-Agent را تکمیل کنند. این Client Hints (به اختصار) را می‌توان از هدرهای Sec-Ch-UA* یا از API Javascript Client Hints دریافت کرد.

هدر User-Agent به صورت یک رشته در فیلد BidRequest.device.ua نمایش داده می‌شود.

یک پیام UserAgent در صورت موجود بودن Client Hints با آنها پر می‌شود، اما در غیر این صورت بر اساس مقادیر تجزیه شده از هدر User-Agent پر می‌شود. این در فیلد BidRequest.device.sua نمایش داده می‌شود.

به پیشنهاددهندگان اکیداً توصیه می‌شود که به جای رشته User-Agent از پیام UserAgent استفاده کنند.

نحوه پر کردن UserAgent

برخلاف هدر User-Agent، پیام UserAgent اطلاعات user agent را که به چندین فیلد برای اطلاعات خاص تقسیم شده است، نشان می‌دهد.

بسته به اینکه آیا Client Hints در درخواست تبلیغ موجود است یا خیر، پیام UserAgent می‌تواند به روش‌های زیر پر شود:

• اگر درخواست حداقل حاوی Client Hint های کم آنتروپی باشد، UserAgent بر اساس محتویات آنها پر می‌شود.
• اگر درخواست فقط شامل سرآیند User-Agent باشد، UserAgent بر اساس آنچه که از سرآیند قابل تجزیه است، پر می‌شود.

نکته: می‌توان از فیلد source برای تشخیص اینکه چه چیزی برای پر کردن UserAgent استفاده می‌شود، استفاده کرد. برای مثال، اگر روی USER_AGENT_STRING تنظیم شده باشد، نشان می‌دهد که UserAgent بر اساس محتوای هدرهای User-Agent پر شده است.

مثال: پر کردن UserAgent بر اساس هدر User-Agent

فرض کنید یک درخواست تبلیغ وجود دارد که مرورگر هدرهای زیر را ارسال می‌کند:

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36

یک UserAgent که صرفاً بر اساس هدر User-Agent پر شده است، ممکن است به شکل زیر باشد:

browsers: [{ brand: "Mozilla", version: ["5", "0"] },
           { brand: "AppleWebKit", version: ["537", "36"] },
           { brand: "Chrome", version: ["103", "0", "0", "0"] },
           { brand: "Safari", version: ["537", "36"] }],
platform: { brand: "Windows NT", version: ["10", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
model: "x64",
source: USER_AGENT_STRING

مثال: پر کردن UserAgent بر اساس Client Hints

فرض کنید یک درخواست تبلیغ وجود دارد که مرورگر هدرهای زیر را ارسال می‌کند:

User-Agent:                 Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Sec-Ch-Ua:                  ".Not/A)Brand";v="99", "Google Chrome";v="103", "Chromium";v="103"
Sec-Ch-Ua-Arch:             x86
Sec-Ch-Ua-Full-Version:     103.0.5060.134
Sec-Ch-Ua-Mobile:           ?0
Sec-Ch-Ua-Platform:         Windows
Sec-Ch-Ua-Platform-Version: 15.0.0

در مواردی که حداقل Client Hints با آنتروپی کم گنجانده شده باشد، UserAgent بر اساس محتویات آن هدرها پر می‌شود، حتی اگر هدرهای User-Agent وجود داشته باشند. این کد به شکل زیر خواهد بود:

browsers: [{ brand: ".Not/A)Brand", version: ["99", "0", "0", "0"] },
           { brand: "Google Chrome", version: ["103", "0", "5060", "134"] },
           { brand: "Chromium", version: ["103", "0", "5060", "134"] }],
platform: { brand: "Windows", version: ["15", "0", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
source: CLIENT_HINTS_HIGH_ENTROPY

پر کردن بر اساس هدر User-Agent در مقابل Client Hints

برخی از فیلدها بسته به اینکه بر اساس سربرگ User-Agent یا Client Hints باشند، به طور متفاوتی پر می‌شوند. در زیر خلاصه‌ای از این تفاوت‌ها آمده است:

• برای مرورگرها و پلتفرم‌های یکسان، UserAgent.browsers.brand و UserAgent.platform.brand اغلب بین یک UserAgent بر اساس سربرگ User-Agent یا Client Hints متفاوت خواهند بود. برای مثال، UserAgent.platform.brand اگر بر اساس سربرگ User-Agent باشد، ممکن است به صورت «Windows NT» ظاهر شود، یا اگر بر اساس Client Hints باشد، به صورت «Windows» ظاهر شود.
• برخی از ورودی‌های UserAgent.browsers منحصر به سربرگ User-Agent یا Client Hints هستند. برای مثال، اگر UserAgent بر اساس سربرگ User-Agent باشد، «AppleWebKit» ظاهر می‌شود، در حالی که «Chromium» فقط در صورتی ظاهر می‌شود که بر اساس Client Hints باشد.
• فقط یک UserAgent بر اساس هدر User-Agent می‌تواند حاوی مقادیر ثابت باشد. برای مثال، اگر پلتفرم ویندوز ۱۱ نسخه ۲۲H2 باشد، UserAgent.platform.brand روی «Windows NT» تنظیم می‌شود و UserAgent.platform.version روی [“10”, “0”] تنظیم می‌شود زیرا این مقدار ثابت برای هر نسخه ویندوز ۱۰ یا بالاتر است.

داده‌های موجود در UserAgent که مبتنی بر Client Hints هستند، معمولاً جایگزین نادرستی برای اطلاعات مسدود شده یا ویرایش شده نخواهند بود. اگر هرگونه تناقضی بین سرآیند User-Agent و UserAgent مبتنی بر Client Hints وجود داشته باشد، اطلاعات UserAgent باید ترجیح داده شود.

فیلدهای شیء UserAgent

این بخش خلاصه‌ای از هر فیلد را با تمرکز بر رفتار خاص گوگل RTB و بهترین شیوه‌های استفاده از آن ارائه می‌دهد.

مرورگرها

شامل فهرستی از ورودی‌های BrandVersion است که عموماً بر اساس ویژگی مرتب شده‌اند - برای مثال، اگر قرار باشد محتوای browsers را فهرست کنید، brand هر ورودی ممکن است به ترتیب زیر ظاهر شود:

برند	معنی
موزیلا	سازگار با موزیلا
اپل وب‌کیت	مبتنی بر AppleWebKit، زیرمجموعه‌ای از Mozilla.
کروم	مرورگر کروم، زیرمجموعه‌ای از مرورگرهای سازگار با AppleWebKit
سافاری	نوع دسکتاپ، برخلاف موبایل.

UserAgent همیشه مرورگرها را به ترتیب خاصی فهرست نمی‌کند، به خصوص اگر بر اساس Client Hints باشد. در ادامه تفاوت‌های دیگری که می‌توانید بر اساس مقدار source انتظار داشته باشید، شرح داده شده است:

• USER_AGENT : فیلد version ممکن است به یک نسخه اصلی کاهش یابد یا ثابت بماند (بستگی به سیاست خاص عامل دارد). توجه داشته باشید که هیچ نشانه‌ای مبنی بر ثابت ماندن مقدار وجود نخواهد داشت.
• CLIENT_HINTS_LOW_ENTROPY و CLIENT_HINTS_HIGH_ENTROPY : ورودی‌ها بر اساس هیچ معیاری مرتب نشده‌اند؛ برای مثال، ممکن است یک مرورگر در هر درخواست این ورودی‌ها را با ترتیب‌های مختلف ارسال کند. همچنین ممکن است حاوی یک ورودی GREASE باشند که باید نادیده گرفته شود.
• CLIENT_HINTS_HIGH_ENTROPY : تمام فیلدهای version موجود در مرورگرها ممکن است روی نسخه‌های کامل تنظیم شوند.

پلتفرم

یک ورودی BrandVersion که پلتفرم را توصیف می‌کند. این ممکن است در هدر User-Agent و Client Hints سازگار نباشد، بنابراین هدف قرار دادن برخی از پلتفرم‌ها ممکن است نیاز به آزمایش دو نام داشته باشد. به عنوان مثال، سیستم عامل مکینتاش اپل در هدر User-Agent با نام تجاری "Macintosh" و در Client Hints با نام تجاری "macOS" شناخته می‌شود. موارد زیر تفاوت‌های دیگری را که می‌توانید بر اساس مقدار source انتظار داشته باشید، شرح می‌دهد:

• USER_AGENT : فیلد version ممکن است به یک نسخه اصلی کاهش یابد یا ثابت بماند. توجه داشته باشید که هیچ نشانه‌ای مبنی بر ثابت ماندن مقدار وجود نخواهد داشت.
• CLIENT_HINTS_LOW_ENTROPY : فیلد version پر نخواهد شد.
• CLIENT_HINTS_HIGH_ENTROPY : فیلد version می‌تواند روی نسخه کامل تنظیم شود.

موبایل

نشان می‌دهد که آیا محتوایی مانند تبلیغات باید برای صفحه نمایش‌های کوچک و/یا ورودی لمسی بهینه شوند یا خیر. توجه داشته باشید که این لزوماً نشان‌دهنده نوع دستگاه نیست، زیرا مرورگرهای تلفن همراه را می‌توان طوری پیکربندی کرد که یک «سایت دسکتاپ» را درخواست کنند.

معماری

معماری پلتفرم مانند «x86» یا «arm» را مشخص می‌کند.

برای یک UserAgent مبتنی بر Client Hints، توجه داشته باشید که این مقدار فقط زمانی پر می‌شود که source روی CLIENT_HINTS_HIGH_ENTROPY تنظیم شده باشد.

تلخی

میزان بیت پلتفرم را مشخص می‌کند، مانند اینکه آیا CPU آن 32 بیتی است یا 64 بیتی. این فیلد یک رشته عدد صحیح است که اطلاعات بیشتری در مورد معماری آن ارائه می‌دهد؛ برای مثال، یک معماری "x86" می‌تواند میزان بیت را روی "32" یا "64" تنظیم کند.

برای یک UserAgent مبتنی بر Client Hints، توجه داشته باشید که این مقدار فقط زمانی پر می‌شود که source روی CLIENT_HINTS_HIGH_ENTROPY تنظیم شده باشد.

مدل

مدل دستگاه را مشخص می‌کند. برای دستگاه‌های تلفن همراه - به معنای لپ‌تاپ یا دسکتاپ نیست - این با نام مدلی مانند «پیکسل ۶ پرو» پر می‌شود.

موارد زیر تفاوت‌هایی را که می‌توانید بر اساس مقدار source انتظار داشته باشید، شرح می‌دهد:

• USER_AGENT
  • دستگاه‌های غیرموبایل: فیلد model اغلب شامل ترکیبی از مقدار معماری و بیتنس مانند "x64" برای ویندوز است. این مقدار برای پلتفرم‌های مختلف مناسب نیست؛ برای مثال، لینوکس ممکن است از "x86_64" برای همان سخت‌افزار استفاده کند.
  • دستگاه‌های موبایل: این فیلد شامل معماری و بیتنس نمی‌شود. اگر به این مقادیر علاقه‌مند هستید، به UserAgent.architecture و UserAgent.bitness مراجعه کنید.
• CLIENT_HINTS_LOW_ENTROPY : فیلد model پر نخواهد شد.
• CLIENT_HINTS_HIGH_ENTROPY : فیلد model فقط برای مدل دستگاه دستگاه‌های تلفن همراه پر می‌شود. هیچ مقداری برای پلتفرم‌های دسکتاپ تنظیم نشده است.

منبع

مشخص می‌کند که کدام هدرها برای ایجاد UserAgent استفاده شده‌اند. برای Client Hints، این مورد همچنین بین دو حالت زیر تمایز قائل می‌شود:

• CLIENT_HINTS_LOW_ENTROPY : فقط نکات اولیه کلاینت در دسترس هستند.
• CLIENT_HINTS_HIGH_ENTROPY : نکات کلاینت در دسترس هستند، از جمله حداقل یک فیلد که به عنوان آنتروپی بالا طبقه‌بندی شده است.