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

السلوك
شبكات الإعلانات المتوافقة
السمات
مواصفات التهيئة
- مثال على التهيئة
- تعريف الكائنات
التحقق

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