AMP

amp-auto-ads

Description

Dynamically injects ads into an AMP page by using a remotely-served configuration file.

 

Required Scripts

<script async custom-element="amp-auto-ads" src="https://cdn.ampproject.org/v0/amp-auto-ads-0.1.js"></script>

يعمل هذا المكّوِن ديناميكيًا على إدخال الإعلانات في صفحة 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

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

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

PlacementObj

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

اسم الحقل النوع الوصف
anchor AnchorObj حقل مطلوب يوفر المعلومات المستخدَمة للبحث عن العناصر المرتبط بها موضع الإعلان في الصفحة.
pos RelativePositionEnum حقل مطلوب يبين موضع الإعلان نسبة إلى عنصر الارتساء.
type PlacementTypeEnum حقل مطلوب يشير إلى نوع موضع الإعلان.
style PlacementStyleObj حقل اختياري يشير إلى التصميم الواجب تطبيقه على الإعلان المدرج في هذا الموضع.
attributes Object<string, string> حقل اختياري يحدد تعيينًا من اسم الخاصية لقيمها لتطبيقه على جميع عناصر <amp-ad> المدرجة باستخدام هذا الموضع. تلغي السمة المحددة هنا أي سمة تحمل الاسم نفسه ومحددة أيضًا على العنصر الرئيسي ConfigObj. يُسمح فقط بأسماء السمات التالية:
  • type
  • layout
  • data-* (أي سمة بيانات)

AnchorObj

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

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

PlacementStyleObj

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

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

RelativePositionEnum

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

الاسم القيمة الوصف
BEFORE 1 إعلان يجب إدراجه كعنصر تابع قبل الارتساء مباشرة.
FIRST_CHILD 2 إعلان يجب إدراجه كعنصر ثانوي أول للارتساء.
LAST_CHILD 3 إعلان يجب إدراجه كعنصر ثانوي أخير للارتساء.
AFTER 4 إعلان يجب إدراجه كعنصر تابع بعد الارتساء مباشرة.

PlacementTypeEnum

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

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

AdConstraintsObj

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

اسم الحقل النوع الوصف
initialMinSpacing string حقل مطلوب يبين الحد الأدنى للمسافة الواجبة بين الإعلان وأي إعلانات حالية على الصفحة (تم وضعها يدويًا أو وضعها amp-auto-ads قبلاً) في وقت الإدراج. يتم التعبير عن القيم كرقم مع بادئة الوحدة. على سبيل المثال، "10px" تعني 10 بكسل أو "0.5vp" تعني نصف ارتفاع إطار العرض. هذا ولا تصلح القيم السلبية. الوحدات المقبولة هي:
  • px - بكسل
  • vp - مضاعف ارتفاع إطار العرض
تنطبق هذه القيمة فقط عندما يكون عدد الإعلانات الحالي في الصفحة أقل من أي مطابقة لـ adCount المحددة في الحقل subsequentMinSpacing.
subsequentMinSpacing Array<!SubsequentMinSpacingObj> حقل اختياري يحدد المساحات الإعلانية الواجب تطبيقها بناءً على عدد الإعلانات الحالي في الصفحة وقت الإدراج.
maxAdCount number حقل مطلوب يبين الحد الأقصى لعدد الإعلانات التي يمكن أن يدرجها 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 بكسل على الأقل.

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

التحقق

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

هل تحتاج إلى مزيد من المساعدة؟

لقد قرأت هذا المستند عشرات المرات ولكن ألم يُجِب عن جميع أسئلتك؟ ربما حصل ذات الأمر مع أشخاص آخرين: تواصل معهم على Stack Overflow.

الذهاب إلى Stack Overflow
هل وجدت خطأ أو تفتقد لميزة؟

يشجع مشروع AMP مشاركتك ومساهمتك بشدة! ونأمل أن تكون مشاركًا دائمًا في مجتمعنا مفتوح المصدر، ولكننا نشجع أيضًا المساهمات التي تحدث لمرة واحدة في الأمور التي تتحمس لها.

الانتقال إلى GitHub