AMP

amp-auto-ads

يعمل هذا المكّوِن ديناميكيًا على إدخال الإعلانات في صفحة AMP باستخدام ملف تهيئة يتم عرضه عن بُعد.

مدى التوفرتجريبي
النص البرمجي المطلوب<script async custom-element="amp-auto-ads" src="https://cdn.ampproject.org/v0/amp-auto-ads-0.1.js"></script>
التنسيقات المعتمدةغير متاح

[جدول المحتويات]

السلوك

يحاول المكوِّن amp-auto-ads إدراج إعلانات إضافية مع الالتزام بمجموعة من القيود التي تحددها شبكة الإعلانات، وذلك مع أخذ عدد المواضع الصالحة (المتوفرة في التهيئة) بالحسبان. تعمل هذه القيود على ما يلي:

  • وضع حد لإجمالي عدد الإعلانات التي يمكن إدراجها
  • وضع الحد الأدنى للمسافة الواجبة بين أي إعلانات متجاورة

بالإضافة إلى ذلك، لا يتم إدراج الإعلانات في الصفحة إلا في الأماكن التي لا تؤدي إلى إعادة تدفق غير مقبولة (كما هو محدد في tryChangeSize).

يجب وضع العلامة <amp-auto-ads> كأول عنصر ثانوي في <body>.

يجب تحديد نوع شبكة الإعلانات وأي معلومات إضافية (تطلبها شبكة الإعلانات) في العلامة.

<amp-auto-ads
    type="adsense"
    data-ad-client="ca-pub-5439573510495356">
</amp-auto-ads>

شبكات الإعلانات المتوافقة

السمات

type (مطلوبة)تمثل هذه السمة معرّف شبكة الإعلانات.
data-foo-barتتطلب معظم شبكات الإعلانات تهيئة إضافية، والتي يمكن تمريرها إلى الشبكة باستخدام سمات data- باللغة HTML. تخضع أسماء المعلَمات إلى تحويل الشرطات إلى الحالة camelCase الخاصة بسمات البيانات القياسية. يتم مثلاً إرسال "data-foo-bar" إلى الإعلان لتهيئته ليكون "fooBar". يمكنك مراجعة وثائق شبكة الإعلانات لمعرفة السمات التي يمكن استخدامها.
السمات المشتركةيتضمن هذا العنصر السمات المشتركة التي تشمل مكونات AMP.

مواصفات التهيئة

تحدد التهيئة المكان الذي يمكن للمكّوِن <amp-auto-ads> وضع الإعلانات فيه على الصفحة. ويتم جلب التهيئة من شبكة إعلانات خارجية على عنوان URL المحدد في ad-network-config.js. يجب أن تكون التهيئة كائن JSON متسلسل يطابق تعريف ConfigObj الموضح أدناه.

مثال على التهيئة

يحدد المثال التالي وجوب وضع الإعلان مباشرة بعد جميع عناصر <P class='paragraph'> الواقعة في الخاصية <DIV id='domId'> الثالثة من الصفحة. يجب أن يكون الإعلان الذي يتم وضعه في أي من هذه المواضع من النوع BANNER وأن يكون له هامش علوي قدره 4 بكسل وهامش سفلي قدره 10 بكسل.

{
  "placements": [
    {
      "anchor": {
        "selector": "DIV#domId",
        "index": 2,
        "sub": {
          "selector": "P.paragraph",
          "all": true,
        },
      },
      "pos": 4,
      "type": 1,
      "style": {
        "top_m": 5,
        "bot_m": 10,
      },
    },
  ]
}

تعريف الكائنات

ConfigObj

الحقول المراد تحديدها في كائن التهيئة:

اسم الحقلالنوعالوصف
placementsArray<!PlacementObj>حقل مطلوب يبين الأماكن المحتملة التي يمكن إدراج الإعلانات فيها على الصفحة.
attributesObject<string, string>حقل اختياري يحدد تعيينًا من اسم الخاصية لقيمها لتطبيقه على كل العناصر <amp-ad> التي تم إدراجها باستخدام هذه التهيئة. يُسمح فقط بأسماء السمات التالية:
  • type
  • layout
  • data-* (أي سمة بيانات)
adConstraintsAdConstraintsObjحقل اختياري يحدد القيود الواجب استخدامها عند وضع الإعلانات على الصفحة. إذا لم يتم تحديد الحقل، سيحاول amp-auto-ads استخدام القيود التلقائية المحددة في [ad-network-config.js](0.1/ad-network-config.js).

PlacementObj

الحقول المراد تحديدها في كائن التهيئة placements:

اسم الحقلالنوعالوصف
anchorAnchorObjحقل مطلوب يوفر المعلومات المستخدَمة للبحث عن العناصر المرتبط بها موضع الإعلان في الصفحة.
posRelativePositionEnumحقل مطلوب يبين موضع الإعلان نسبة إلى عنصر الارتساء.
typePlacementTypeEnumحقل مطلوب يشير إلى نوع موضع الإعلان.
stylePlacementStyleObjحقل اختياري يشير إلى التصميم الواجب تطبيقه على الإعلان المدرج في هذا الموضع.
attributesObject<string, string>حقل اختياري يحدد تعيينًا من اسم الخاصية لقيمها لتطبيقه على جميع عناصر <amp-ad> المدرجة باستخدام هذا الموضع. تلغي السمة المحددة هنا أي سمة تحمل الاسم نفسه ومحددة أيضًا على العنصر الرئيسي ConfigObj. يُسمح فقط بأسماء السمات التالية:
  • type
  • layout
  • data-* (أي سمة بيانات)

AnchorObj

الحقول المراد تحديدها في كائن التهيئة anchor:

اسم الحقلالنوعالوصف
selectorstringحقل مطلوب يبين محدِد CSS لاختيار العناصر في هذا المستوى من تعريف الارتساء.
indexnumberحقل اختياري يحدد فهرس العناصر المختارة من قِبل المحدِد الذي يجب أن يقتصر عليها هذا المستوى من تعريف الارتساء. تلقائيًا، يتم تعيين القيمة على 0 (إذا كان الحقل all false).
allbooleanيتم تجاهله في حال تحديد الحقل index. إذا عيّنته على true، يشير إلى وجوب تضمين جميع العناصر المُختَارة من قبِل المحدِد، وإلا فعينّه على false.
min_cnumberحقل اختياري يبين الحد الأدنى لطول الخاصية textContent لعنصر ليتم تضمينه. القيمة التلقائية هي 0.
subAnchorObjحقل اختياري يحدد AnchorObj متكرر والذي سيختار عناصر داخل أي عناصر محددة في هذا المستوى من تعريف الارتساء.

PlacementStyleObj

الحقول المراد تحديدها في كائن التهيئة style:

اسم الحقلالنوعالوصف
top_mnumberحقل اختياري يبين الهامش العلوي بالبكسل الذي يجب أن يحتوي عليه الإعلان المُدرَج في هذا الموضع. القيمة التلقائية: 0.
bot_mnumberحقل اختياري يبين الهامش السفلي الذي يجب أن يحتوي عليه الإعلان المُدرَج في هذا الموضع. القيمة التلقائية: 0.

RelativePositionEnum

قيم ENUM للحقل pos في كائن التهيئة placements:

الاسمالقيمةالوصف
BEFORE1إعلان يجب إدراجه كعنصر تابع قبل الارتساء مباشرة.
FIRST_CHILD2إعلان يجب إدراجه كعنصر ثانوي أول للارتساء.
LAST_CHILD3إعلان يجب إدراجه كعنصر ثانوي أخير للارتساء.
AFTER4إعلان يجب إدراجه كعنصر تابع بعد الارتساء مباشرة.

PlacementTypeEnum

قيم ENUM للحقل type في كائن التهيئة placements:

الاسمالقيمةالوصف
BANNER1موضع يصف متوسط موضع الإعلان البانر.

AdConstraintsObj

الحقول المراد تحديدها في كائن التهيئة adConstraints:

اسم الحقلالنوعالوصف
initialMinSpacingstringحقل مطلوب يبين الحد الأدنى للمسافة الواجبة بين الإعلان وأي إعلانات حالية على الصفحة (تم وضعها يدويًا أو وضعها amp-auto-ads قبلاً) في وقت الإدراج. يتم التعبير عن القيم كرقم مع بادئة الوحدة. على سبيل المثال، "10px" تعني 10 بكسل أو "0.5vp" تعني نصف ارتفاع إطار العرض. هذا ولا تصلح القيم السلبية. الوحدات المقبولة هي:
  • px - بكسل
  • vp - مضاعف ارتفاع إطار العرض
تنطبق هذه القيمة فقط عندما يكون عدد الإعلانات الحالي في الصفحة أقل من أي مطابقة لـ adCount المحددة في الحقل subsequentMinSpacing.
subsequentMinSpacingArray<!SubsequentMinSpacingObj>حقل اختياري يحدد المساحات الإعلانية الواجب تطبيقها بناءً على عدد الإعلانات الحالي في الصفحة وقت الإدراج.
maxAdCountnumberحقل مطلوب يبين الحد الأقصى لعدد الإعلانات التي يمكن أن يدرجها amp-auto-ads في الصفحة. يتم احتساب كل من الإعلانات الموضوعة يدويًا والمدرجة بالمكّوِن amp-auto-ads من هذا الإجمالي. إذا تم مثلاً تعيين هذا الحقل على 5 وكان هناك 3 إعلانات موضوعة يدويًا في الصفحة، سيضع amp-auto-ads إعلانين إضافيين بحد أقصى.

SubsequentMinSpacingObj

الحقول المراد تحديدها في كائن التهيئة subsequentMinSpacing. يمكن استخدام إدخالات subsequentMinSpacing لتغيير المساحات المطلوبة بين الإعلانات الإضافية بناء على عدد الإعلانات الحالي في الصفحة. فكِّر في السيناريو التالي كمثال:

  • إعلانان حاليان في الصفحة
  • حقل subsequentMinSpacing هو:
[
  {adCount: 3, spacing: "500px"},
  {adCount: 5, spacing: "1000px"},
]

في البداية، يوجد إعلانان حاليان في الصفحة، لذلك لا مطابقة للتعيين. يأخذ الحد الأدنى للمساحة القيمة التلقائية لـ initialMinSpacing في الكائن AdConstraints. سيحاول amp-auto-ads بشكل متكرر وضع الإعلانات إلى أن تنفد المواضع التي يمكن استخدامها بدون تخطي adContraints. بعد أن وضع amp-auto-ads أول إعلان له، أصبح هناك الآن 3 إعلانات على الصفحة، وبما أن هناك تعيين لثلاثة (أو أكثر) من الإعلانات في subsequentMinSpacing، يصبح الحد الأدنى للمساحة الآن 500 بكسل. ينطبق هذا الأمر إلى أن يصبح هناك 5 إعلانات على الصفحة، بسبب قاعدة الإعلانات الخمسة. يتطلب عندئذٍ إدراج الإعلان السادس مساحة فارغة من الإعلانات قدرها 1000 بكسل على الأقل.

اسم الحقلالنوعالوصف
adCountnumberحقل مطلوب. وهو الحد الأدنى لعدد الإعلانات الحالية على الصفحة والتي تتسبب في تطبيق هذه القاعدة (بفرض عدم توفر قاعدة أخرى بتطابق أفضل). انظر الوصف أعلاه للحصول على شرح أكثر تفصيلاً.
spacingstringحقل مطلوب يبين الحد الأدنى للمساحة الإعلانية الذي ينطبق عند مطابقة هذه القاعدة استنادًا إلى adCount. يتم التعبير عن القيم كرقم مع بادئة الوحدة. على سبيل المثال، "10px" تعني 10 بكسل أو "0.5vp" تعني نصف ارتفاع إطار العرض. هذا ولا تصلح القيم السلبية. الوحدات المقبولة هي:
  • px - بكسل
  • vp - مضاعف ارتفاع إطار العرض

التحقق

اطِّلع على قواعد amp-auto-ads في مواصفات مدقق AMP.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub