رمز "خيارات الإعلان" وتراكبه

يجب على جميع التطبيقات التي تعرض إعلانات مخصّصة تستضيفها Google تنفيذ رمز AdChoices وتراكبه، عند توفيره من خلال Google. "خيارات الإعلان" (يُشار إليها أيضًا باسم "لماذا هذا الإعلان؟") هي ميزة للشفافية توضّح للمستخدمين سبب عرض إعلان معيّن لهم، وتقدّم معلومات عن كيفية حماية خصوصيتهم.

لمزيد من المعلومات، اطّلِع على سبب ظهور إعلان لك.

يشرح هذا الدليل كيفية استخراج المعلومات اللازمة لتنفيذ "خيارات الإعلان" بشكل صحيح من استجابة البيانات الوصفية بتنسيق VAST لإعلانك أو من استجابة البيانات الوصفية لمصدر DAI.

متطلبات عرض "خيارات الإعلان"

للالتزام بمتطلبات Google لعرض رموز "خيارات الإعلان"، يجب أن يستوفي تطبيقك أو موقعك الإلكتروني المعايير التالية:

  1. يجب عرض رمز "خيارات الإعلان" فوق أي إعلان يتم تقديمه
  2. يجب عرض رمز "خيارات الإعلان" في الموضع المُشار إليه بسمتَي "الموقع X" و"الموقع Y" المضمّنين في بيانات الرمز، وبالحجم المحدّد من خلال خصائص العرض والارتفاع، بوحدات البكسل غير الكثافة (DP).
  3. يجب عدم حجب رمز خيارات الإعلان بواسطة تراكبات إعلانات أو عناصر أخرى للواجهة.
  4. يجب أن يكون رمز "خيارات الإعلان" قابلاً للنقر على الأنظمة الأساسية التي تتيح النقر أو ما يعادلها (مثل الاختيار باللمس أو التحديد عن بُعد).
  5. على المنصات المتوافقة مع المتصفِّحات، يجب أن يؤدي النقر على رمز "خيارات الإعلان" إلى فتح علامة تبويب أو نافذة متصفِّح بعنوان URL محدّد في السمة "clickthrough" أو "click_data".
  6. في الأنظمة الأساسية التي لا تتوافق مع المتصفّح، يؤدي النقر على رمز "خيارات الإعلان" إلى فتح تراكب شكلي يعرض إحدى الصور المحدّدة في السمة "IconClickFallbackImage" أو "click_fallback_images".
  7. على الأنظمة الأساسية التي لا تتوافق مع المتصفّح، يجب عرض الصورة الاحتياطية بالحجم المحدَّد ضمن السمة "IconClickFallbackImage" أو "click_fallback_images"، بوحدات البكسل غير الكثافة (DP).

تحليل "خيارات الإعلان" من استجابة XML لنموذج عرض إعلانات الفيديو (VAST)

عند العمل مع استجابة إعلان XML، لا يتم دعم "خيارات الإعلان" إلا في الإصدار 3.0 من نموذج عرض إعلانات الفيديو (VAST) والإصدارات الأحدث. يتم تنفيذ "خيارات الإعلان" في شكل رمز نموذج عرض إعلانات فيديو (VAST).

الإصدار 4.2 من نموذج عرض إعلانات فيديو (VAST)

إذا كانت استجابة إعلان XML تتبع معيار VAST 4.2، يتم عرض "خيارات الإعلان" كرمز نموذج عرض إعلانات فيديو (VAST). إذا كان تطبيقك أو موقعك الإلكتروني يدعم بشكل كامل رموز VAST 4.2 (القسم 3.11 من معيار VAST 4.2)، لن يتطلب دعم "خيارات الإعلان" أي جهد إضافي.

إذا كان تطبيقك لا يتوافق مع رموز VAST 4.2، عليك تحليل الرموز يدويًا التي تحمل اسم البرنامج "GoogleWhyThisAd" من استجابة VAST بناءً على هذا المعيار. يمكنك استخدام نموذج VAST 4.2 xml هذا لإجراء اختبارات إضافية في تطبيقك.

نموذج استجابة VAST 4.2

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.2">
  <Ad id="20011">
    <Wrapper>
      ...
      <Creatives>
        ...
        <Creative id="5480" sequence="1">
          ...
          <Linear>
            ...
            <Icons>
              ...
              <Icon program="GoogleWhyThisAd" width="40" height="30" xPosition="left" yPosition="100" duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="AdChoices icon">
                <StaticResource creativeType="image/png">
                  <![CDATA[ https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png ]]>
                </StaticResource>
                <IconClicks>
                  <IconClickThrough>
                    <![CDATA[ https://g.co/adsettings ]]>
                  </IconClickThrough>
                  <IconClickFallbackImages>
                    <IconClickFallbackImage width="950" height="600">
                      <AltText>
                        <![CDATA[ This ad was shown to you based on: * Google's estimation of your interests, based on your activity on Google on this device (for example, your searches) * the information on the website you were viewing. ]]>
                      </AltText>
                      <StaticResource creativeType="image/png">
                        <![CDATA[ https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices_fallback_image.png ]]>
                      </StaticResource>
                    </IconClickFallbackImage>
                    ...
                  </IconClickFallbackImages>
                </IconClicks>
              </Icon>
              ...
            </Icons>
            ...
          </Linear>
          ...
        </Creative>
        ...
      </Creatives>
      ...
    </Wrapper>
    ...
  </Ad>
</VAST>

الإصدار 3.0 من نموذج عرض إعلانات فيديو (VAST)

إذا كانت استجابة إعلان XML متوافقة مع معيار VAST 3.0، يتم عرض "خيارات الإعلان" كمزيج من رمز نموذج عرض إعلانات فيديو (VAST) وإضافة VAST مخصّصة. إذا كان تطبيقك أو موقعك الإلكتروني متوافقًا بالكامل مع معيار رمز VAST 3.0 وإذا كان النظام الأساسي قادرًا على الانتقال إلى رمز عنوان URL للنقر وعرضه، لن يتطلب دعم "خيارات الإعلان" أي جهد إضافي.

إذا تعذّر على نظامك الأساسي الانتقال إلى عناوين URL لنسبة النقر إلى الظهور وعرضها، وهذا ينطبق بشكل أساسي على الأجهزة التي لا تحتوي على متصفح ويب مدمج، يجب تنفيذ دعم الإضافة "IconFallbackImages". تحتوي هذه الإضافة على مجموعة من علامات "IconFallbackImages" التي تتطابق فيها سمة "program" مع رمز تم تضمينه في نموذج عرض إعلانات الفيديو (VAST).

لإتاحة خيارات الإعلان بشكل كامل، يجب ربط العلامة IconFallbackImages باسم البرنامج "GoogleWhyThisAd" بالرمز الذي يحمل اسم البرنامج "GoogleWhyThisAd"، بحيث يتم عرض الصورة الاحتياطية المرتبطة بها عندما يتفاعل المستخدم مع الرمز.

لدعم التغييرات المستقبلية المحتملة على معيار "خيارات الإعلان"، ننصح بشدة بدمج دعم الصور الاحتياطية لجميع رموز VAST، عند توفّرها. يمكنك استخدام نموذج VAST 3.0 xml هذا لإجراء اختبارات إضافية في تطبيقك.

بنية إضافة IconFallbackImages

علامة السمات الوصف
الإضافة كتابة بالنسبة إلى هذه الإضافة، يحتوي النوع دائمًا على القيمة IconClickFallbackImages.
-IconClickFallbackImages برنامج تتطابق هذه السمة دائمًا مع سمة البرنامج لرمز VAST 3.0 المرتبط.
تتطابق بنية هذه العقدة مع معيار VAST 4.2 لـ IconClickFallbackImages، باستثناء إضافة السمة program.
--IconClickFallbackImage width العرض المفضل لعرض الصورة.
الطول الارتفاع المفضل لعرض الصورة.
---AltText وصف الصورة يسهل الوصول إليه.
---StaticResource creativeType تمثّل هذه السمة mimetype للصورة الاحتياطية.
قيمة CDATA تحتوي على عنوان URL للصورة الاحتياطية.

نموذج استجابة VAST 3.0

<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
 <Ad id="123456">
  <InLine>
   ...
   <Creatives>
    ...
    <Creative id="7891011" AdID="ABCD123456EF" sequence="1">
     ...
     <Linear>
      ...
      <Icons>
       ...
       <Icon program="GoogleWhyThisAd" width="50" height="50" xPosition="20" yPosition="bottom" duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="Why This Ad?">
        <StaticResource creativeType="image/png">
         <![CDATA[https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png]]>
        </StaticResource>
        <IconClicks>
         ...
         <IconClickThrough><![CDATA[https://g.co/adsettings]]></IconClickThrough>
        </IconClicks>
       </Icon>
       ...
      </Icons>
     ...
     </Linear>
     ...
    </Creative>
    ...
   </Creatives>
   <Extensions>
    ...
    <Extension type="IconClickFallbackImages">
     ...
     <IconClickFallbackImages program="GoogleWhyThisAd">
      <IconClickFallbackImage width="400" height="150">
       <AltText>Alt icon fallback</AltText>
       <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/gvabox/nickchavez/media/png/wta_dialog.png]]></StaticResource>
      </IconClickFallbackImage>
      ...
     </IconClickFallbackImages>
     ...
    </Extension>
    ...
   </Extensions>
   ...
  </InLine>
  ...
 </Ad>
</VAST>

تحليل "خيارات الإعلان" من ملف JSON للبيانات الوصفية لواجهة برمجة التطبيقات DAI

عند استخدام واجهة برمجة تطبيقات DAI، يتم تمرير تفاصيل "خيارات الإعلان" عبر كائن JSON الذي يعرضه الطلبات إلى عنوان URL للبيانات الوصفية.

يحتوي كائن JSON للبيانات الوصفية على قائمة إعلانات مرتبطة بمعرّف الإعلان. وداخل كل كائن إعلان توجد صفيفة رموز. إذا كان الإعلان المعني يستخدم "خيارات الإعلان"، سيتم تضمين رمز "خيارات الإعلان" في ذلك المصفوفة.

تنسيق رمز JSON

إنّ تنسيق رمز JSON هو ترجمة بنسبة عرض إلى ارتفاع 1:1 استنادًا إلى معيار رمز VAST 4.2 (القسم 3.11)، حيثما أمكن. ومع ذلك، لإتاحة تنسيق JSON الأكثر صرامة، غيّرت بعض السمات الأسماء، حسب الضرورة.

تنسيق رمز JSON

برنامج بالنسبة إلى رمز "خيارات الإعلان"، تحتوي هذه القيمة دائمًا على السلسلة "GoogleWhyThisAd".
x_position تمثّل هذه السمة الموضع الأفقي للزاوية اليمنى العليا للرمز، مقارنةً بالزاوية العلوية اليمنى من تصميم الفيديو، بالبكسل. يقبل هذا الحقل أيضًا قيم الموضع سريع الاستجابة "يمينًا" أو "يسار".
y_position تمثّل هذه السمة الموضع العمودي للزاوية العلوية اليمنى من الرمز، بالنسبة إلى الزاوية العلوية اليمنى من تصميم الفيديو، بالبكسل. يقبل هذا الحقل أيضًا قيم الموضع سريع الاستجابة "top" أو "bottom".
width تمثّل هذه السمة عرض الرمز بالبكسل.
الطول ارتفاع الرمز بالبكسل.
creative_type تمثّل هذه السمة mimetype للصورة المقدَّمة للرمز. يتم ضبط الإعدادات التلقائية على "image/png".
المصدر عنوان URL لاسترداد رمز "خيارات الإعلان".
alt_text النص البديل الذي سيتم عرضه لرمز "خيارات الإعلان".
click_data يشير ذلك المصطلح إلى عنصر يحتوي على السمة click_data.url التي تمثّل عنوان URL الذي يجب توجيه المشاهدين إليه في حال النقر على رمز "خيارات الإعلان" على منصة تتيح تصفّح الويب.
click_fallback_images مجموعة من عناصر الصور لعرضها للمشاهدين الذين ينقرون على رمز خيارات الإعلان على الأنظمة الأساسية التي لا تتوافق مع تصفح الويب.

تنسيق JSON للصورة الاحتياطية

width تمثّل هذه السمة عرض الصورة الاحتياطية بالبكسل.
الطول ارتفاع الصورة الاحتياطية بالبكسل.
creative_type تمثّل هذه السمة mimetype للصورة الاحتياطية. يتم ضبط الإعدادات التلقائية على "image/png".
المصدر عنوان URL لاسترداد الصورة الاحتياطية.
alt_text النص البديل المطلوب عرضه للصورة الاحتياطية

نموذج JSON للبيانات الوصفية

{
  ...
  "ads": {
    ...
    "0002640412_ad1": {
      ...
      "icons": [
        ...
        {
          "alt_text": "AdChoices icon",
          "click_data": {
            "url": "https://g.co/adsettings"
          },
          "click_fallback_images": [
            {
              "alt_text": "This ad was shown to you based on: * Google's
estimation of your interests, based on your activity on Google on this device
(for example, your searches) * the information on the website you were
viewing.",
              "creative_type": "image/jpg",
              "height": 600,
              "resource": "https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices_fallback_image.png",
              "width": 950
            }
          ],
          "creative_type": "image/png",
          "height": 30,
          "program": "AdChoices",
          "resource": "https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png",
          "type": "static",
          "width": 40,
          "x_position": "0",
          "y_position": "100"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}