استهداف وكيل المستخدم

تم في السابق تضمين عنوان User-Agent في طلبات عروض الأسعار لتوفير بيانات استهداف مفيدة، مثل المتصفّح والنظام الأساسي للجهاز الذي بدأ الطلب. ومع ذلك، غالبًا ما تحذف المتصفحات جزءًا كبيرًا من حقل User-Agent بسبب صعوبة استخدامه ولحماية خصوصية المستخدمين بشكل أفضل. استجابةً لذلك، تتيح Google استخدام تعديلات برنامج وكيل المستخدم، والتي يتم تضمينها في طلبات عروض الأسعار عند توفّرها لتكملة عنوان User-Agent. يمكن الحصول على حقول معلومات الوكيل المستخدم هذه (باختصار) من عناوين Sec-Ch-UA* أو من واجهة برمجة التطبيقات الخاصة بحقول معلومات الوكيل المستخدم في JavaScript.

يتم عرض عنوان User-Agent كسلسلة في الحقل BidRequest.device.ua.

سيتم ملء رسالة UserAgent بحقول معلومات الوكيل المستخدم عند توفّرها، ولكن سيتم ملؤها في الحالات الأخرى استنادًا إلى القيم التي تم تحليلها من عنوان User-Agent. يتم عرض هذا في الحقل BidRequest.device.sua.

ننصح مقدّمي عروض الأسعار بشدة باستخدام الرسالة UserAgent بدلاً من سلسلة User-Agent.

كيفية تعبئة UserAgent

على عكس عنوان User-Agent، تمثّل رسالة UserAgent معلومات وكيل المستخدم مقسّمة إلى حقول متعددة للحصول على معلومات محدّدة.

استنادًا إلى ما إذا كانت تلميحات العميل متوفّرة في طلب الإعلان، يمكن ملء الرسالة UserAgent بالطرق التالية:

• إذا كان الطلب يتضمّن تلميحات عميل منخفضة الإنتروبيا على الأقل، سيتم ملء 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 استنادًا إلى حقول معلومات العميل

لنفترض أنّ هناك طلب إعلان يرسل فيه المتصفّح العناوين التالية:

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 على أنّه "Windows NT" إذا كان يستند إلى عنوان User-Agent، أو "Windows" إذا كان يستند إلى Client Hints.
• بعض إدخالات UserAgent.browsers فريدة لعنوان User-Agent أو لتعديلات برنامج العميل. على سبيل المثال، سيظهر "AppleWebKit" إذا كان UserAgent يستند إلى عنوان User-Agent، بينما لن يظهر "Chromium" إلا إذا كان يستند إلى تلميحات العميل.
• يمكن أن يحتوي UserAgent استنادًا إلى عنوان User-Agent على قيم ثابتة فقط. على سبيل المثال، إذا كان النظام الأساسي هو Windows 11 22H2، سيتم ضبط UserAgent.platform.brand على "Windows NT" وسيتم ضبط UserAgent.platform.version على [“10”, “0”] لأنّ هذه هي القيمة الثابتة لأي إصدار من Windows يبلغ 10 أو أعلى.

لن تكون البيانات في UserAgent المستندة إلى تلميحات العميل بديلاً غير دقيق للمعلومات المجمدة أو المنقّحة. في حال وجود أي تضارب بين حقل User-Agent وUserAgent استنادًا إلى Client Hints، يجب تفضيل المعلومات الواردة من UserAgent.

حقول عنصر UserAgent

يلخّص هذا القسم كل حقل، مع التركيز على السلوك الخاص بنظام RTB من Google وأفضل الممارسات المتعلّقة بالاستخدام.

المتصفحات

تحتوي على قائمة بإدخالات BrandVersion مرتّبة بشكل عام حسب درجة التحديد، مثلاً، إذا أردت إدراج محتويات browsers، قد يظهر brand لكل إدخال بالترتيب التالي:

العلامة التجارية	المعنى
برنامج المتصفح Mozilla	متوافق مع Mozilla
AppleWebKit	مستند إلى AppleWebKit، وهو مجموعة فرعية من Mozilla.
Chrome	متصفّح Chrome، وهو مجموعة فرعية من المتصفّحات المتوافقة مع AppleWebKit
Safari	إصدار متوافق مع أجهزة الكمبيوتر المكتبي، على عكس الإصدار المتوافق مع الأجهزة الجوّالة

لن تعرض السمة UserAgent المتصفحات دائمًا بأي ترتيب محدّد، خاصةً إذا كانت تستند إلى تلميحات العميل. في ما يلي وصف للاختلافات الأخرى التي يمكن توقّع ظهورها استنادًا إلى قيمة source:

• ‫USER_AGENT: قد يتم تقليل الحقل version إلى إصدار رئيسي أو تجميده (يعتمد ذلك على السياسة الخاصة بالوكيل). يُرجى العِلم أنّه لن يكون هناك أي إشارة إلى أنّ القيمة ثابتة.
• CLIENT_HINTS_LOW_ENTROPY وCLIENT_HINTS_HIGH_ENTROPY: لا يتم ترتيب الإدخالات حسب أي معايير، على سبيل المثال، قد يرسل المتصفّح نفسه هذه الإدخالات بترتيبات مختلفة في كل طلب. قد تتضمّن أيضًا إدخال GREASE، والذي يجب تجاهله.
• ‫CLIENT_HINTS_HIGH_ENTROPY: يمكن ضبط جميع حقول version التي يتم العثور عليها في المتصفحات على الإصدارات الكاملة.

النظام الأساسي

إدخال BrandVersion يصف المنصة. قد لا يكون ذلك متوافقًا مع حقل User-Agent في العنوان وتلميحات العميل، لذا قد يتطلّب استهداف بعض المنصات اختبار اسمَين. على سبيل المثال، تحمل العلامة التجارية لنظام التشغيل Macintosh من Apple الاسم "Macintosh" في عنوان User-Agent، ولكن الاسم "macOS" في تلميحات العميل. في ما يلي وصف للاختلافات الأخرى التي يمكنك توقّعها استنادًا إلى قيمة source:

• ‫USER_AGENT: قد يتم تقليل حقل version إلى إصدار رئيسي أو تجميده. يُرجى العِلم أنّه لن يكون هناك أي إشارة إلى أنّ القيمة مجمدة.
• CLIENT_HINTS_LOW_ENTROPY: لن تتم تعبئة الحقل version.
• ‫CLIENT_HINTS_HIGH_ENTROPY: يمكن ضبط الحقل version على الإصدار الكامل.

الجهاز الجوّال

تشير هذه السمة إلى ما إذا كان يجب تحسين المحتوى، مثل الإعلانات، ليتناسب مع الشاشات الصغيرة و/أو إدخال اللمس. يُرجى العِلم أنّ هذا ليس مؤشرًا على نوع الجهاز بالضرورة، إذ يمكن ضبط متصفحات الأجهزة الجوّالة لطلب "موقع إلكتروني متوافق مع أجهزة الكمبيوتر".

الهندسة المعمارية

تحدّد بنية النظام الأساسي، مثل "x86" أو "arm".

بالنسبة إلى UserAgent المستند إلى تلميحات العميل، يُرجى العِلم أنّه لن يتم ملء هذا الحقل إلا عندما يتم ضبط source على CLIENT_HINTS_HIGH_ENTROPY.

Bitness

تحدّد هذه السمة عدد البتات في النظام الأساسي، مثل ما إذا كان يحتوي على وحدة معالجة مركزية (CPU) ‏32 بت أو 64 بت. الحقل عبارة عن سلسلة أعداد صحيحة تقدّم معلومات إضافية حول بنية الجهاز، مثلاً، يمكن أن تتضمّن بنية x86 عددًا من البتات مضبوطًا على 32 أو 64.

بالنسبة إلى UserAgent المستند إلى تلميحات العميل، يُرجى العِلم أنّه لن يتم ملء هذا الحقل إلا عندما يتم ضبط source على CLIENT_HINTS_HIGH_ENTROPY.

الطراز

تحدّد هذه السمة طراز الجهاز. بالنسبة إلى الأجهزة الجوّالة، أي غير أجهزة الكمبيوتر المحمول أو المكتبي، سيتم ملء هذا الحقل باسم طراز، مثل "Pixel 6 Pro".

في ما يلي وصف للاختلافات التي يمكنك توقّع ظهورها استنادًا إلى قيمة source:

• USER_AGENT
  • الأجهزة غير الجوّالة: غالبًا ما يحتوي الحقل model على قيمة مجمّعة للبنية والبتات، مثل "x64" لنظام التشغيل Windows. هذه القيمة غير متوافقة مع منصات متعددة، فعلى سبيل المثال، قد يستخدم نظام التشغيل Linux السلسلة "x86_64" للأجهزة نفسها.
  • الأجهزة الجوّالة: لن يتضمّن هذا الحقل البنية وعدد البتات. إذا كنت مهتمًا بهذه القيم، يمكنك الاطّلاع على UserAgent.architecture وUserAgent.bitness.
• CLIENT_HINTS_LOW_ENTROPY: لن تتم تعبئة الحقل model.
• CLIENT_HINTS_HIGH_ENTROPY: لن تتم تعبئة الحقل model إلا لطراز جهاز الجوّال. لم يتم ضبط أي قيمة لمنصات أجهزة الكمبيوتر.

المصدر

تحدّد هذه السمة العناوين التي تم استخدامها لإنشاء UserAgent. بالنسبة إلى تلميحات العميل، يميّز ذلك أيضًا بين الحالتَين التاليتَين:

• CLIENT_HINTS_LOW_ENTROPY: تتوفر حقول معلومات الوكيل المستخدم الأساسية فقط.
• CLIENT_HINTS_HIGH_ENTROPY: تتوفّر حقول معلومات العميل، بما في ذلك حقل واحد على الأقل مصنّف على أنّه يتضمّن بيانات عشوائية عالية.