تجنُّب الأخطاء الشائعة في التنفيذ

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

يتضمن كل سيناريو نهجًا مقترحًا لحل المشكلة المعروضة.

يُرجى العِلم أنّ هذه القائمة لا تمثّل قائمة شاملة بالمشاكل المحتملة ولكن يُتوقع أن يكون بمثابة دليل مفيد لتحديد أنواع المشكلات التي قد تحتاج إلى معالجتها.

علاوةً على ذلك، بناءً على التنفيذ، قد تحتاج إلى البحث عن جميع الأماكن التي قد تكون هذه التغييرات ضرورية داخل موقعك.

الأخطاء الشائعة

السيناريو 1: استخدام نُسخ غير رسمية من مكتبات JavaScript لـ GPT

وصف حالة استخدام عالية المستوى أو استضافة gpt.js أو pubads_impl.js أو أي مكتبات يتم تحميلها من الخوادم الخاصة بك أو وهي تحميل هذه الملفات من مصدر غير رسمي.
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Accessing these files from an unofficial source
<script async src="https://www.example.com/tag/js/gpt.js"></script>
الطرق المقترَحة لإصلاح الخطأ
// Correct: Access these files from a Google domain
<script src="https://securepubads.g.doubleclick.net/tag/js/gpt.js" crossorigin="anonymous" async></script>
// Also correct, if using Limited Ads
<script src="https://pagead2.googlesyndication.com/tag/js/gpt.js" async></script>

السيناريو 2: الاعتماد على أدوات معالجة علامات النص البرمجي gpt.js

وصف حالة استخدام عالية المستوى وبافتراض أن واجهة برمجة تطبيقات GPT جاهزة ليتم استدعاؤها عند ملف JavaScript تم تحميل gpt.js بشكل خاطئ، حيث توفر بعض أجزاء واجهة برمجة التطبيقات بواسطة ملف pubads_impl.js. الاعتماد بأي شكل من الأشكال (بما في ذلك أُطر العمل) على واجهة برمجة التطبيقات من داخل أدوات معالجة الأحداث المرفقة بعلامة النص البرمجي، تكون غير صحيحة.
مثال على مقتطف رمز برمجي به خطأ
var tag = document.createElement('script');
tag.type = 'text/javascript';
tag.src = (useSSL ? 'https:' : 'http:') +
        '//www.googletagservices.com/tag/js/gpt.js';
// Incorrect: Attaching a callback to the script's onload event.
tag.onload = callback;
var node = document.getElementsByTagName('script')[0];
node.parentNode.insertBefore(tag, node);
الطرق المقترَحة لإصلاح الخطأ
// Make sure that googletag.cmd exists.
window.googletag = window.googletag || {};
googletag.cmd = googletag.cmd || [];
// Correct: Queueing the callback on the command queue.
googletag.cmd.push(callback);
شرح / وصف الحل يحتفظ googletag.cmd بقائمة بالأوامر التي سيتم تشغيلها فور استخدام GPT جاهز. هذه هي الطريقة الصحيحة للتأكد من تشغيل معاودة الاتصال عند تحميل GPT.

السيناريو 3: التحقق من كائن googletag لمعرفة ما إذا كانت GPT جاهزة

وصف حالة استخدام عالية المستوى لأنّ واجهة برمجة تطبيقات GPT قد لا تكون جاهزة عند تحميل ملف JavaScript "gpt.js" أو عند تعريف الكائن googletag، جارٍ التحقق من ذلك الكائن لمعرفة ما إذا كان توفر واجهة برمجة تطبيقات GPT غير موثوقة.
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Relying on the presence of the googletag object
// as a check for the GPT API.
if (typeof googletag != 'undefined') {
 functionProcessingGPT();
}
الطرق المقترَحة لإصلاح الخطأ
// Correct: Relying on googletag.apiReady as a check for the GPT API.
if (window.googletag && googletag.apiReady) {
 functionProcessingGPT();
}
شرح / وصف الحل سيملأ GPT العلامة المنطقية googletag.apiReady بعد واجهة برمجة التطبيقات جاهزة ليتم استدعاؤها لتتمكن من إجراء تأكيدات موثوقة.

السيناريو 4: الاعتماد على بنية التعليمات البرمجية التي تم تشويشها

وصف حالة استخدام عالية المستوى إذا كنت تعتمد على بنية دقيقة لشفرة مكتبة GPT التي تم تصغيرها، فستحصل على تواجه بالتأكيد الأعطال. يُرجى قصر استخدامك على واجهة برمجة التطبيقات الموثقة في الدليل المرجعي لواجهة برمجة التطبيقات، لأننا نُجري التغييرات باستمرار الأعمال الداخلية لـ GPT للحصول على تحسينات مستمرة.
على سبيل المثال، أحد المتطلبات الشائعة هو اكتشاف وقت تحميل PubAdsService بالكامل في للاتصال بـ refresh().
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Relying on an obfuscated property.
if (googletag.pubads().a != null) {
 functionProcessingGPT();
}
الطرق المقترَحة لإصلاح الخطأ
// Correct: Relying on public GPT API methods
// (i.e. googletag.pubadsReady in this case).
if(window.googletag && googletag.pubadsReady) {
 functionProcessingGPT();
}
شرح / وصف الحل لا يمكن الاعتماد إلا على واجهة برمجة التطبيقات العامة. في حالة اكتشاف ما إذا كان PubAdsService مع التحميل بالكامل، تكون لدينا قيمة منطقية googletag.pubadsReady.

السيناريو 5: استبدال أي دالة أو متغير في GPT

وصف حالة استخدام عالية المستوى قد تحدث حالات الاستخدام التي تستند إلى استبدال أي دالة أو متغير مستخدم بواسطة GPT في أي وقت لأنّ هذه حالة استخدام غير متوافقة. قد تؤدي تغييرات التوقيت في الأقسام الداخلية في GPT إلى ظهور نوع من السلوك غير الصحيح من خلال الأعطال.
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Haphazardly overwriting a googletag.* property.
googletag.cmd = [];
الطرق المقترَحة لإصلاح الخطأ
// Correct: Never overwrite googletag.* properties if they already exist.
// Always check before assigning to them.
googletag.cmd = googletag.cmd || [];

السيناريو 6: ترتيب المكالمات بشكل خاطئ إلى GPT

وصف حالة استخدام عالية المستوى قد تؤدي ظروف السباق إلى حدوث أعطال مع تطوّر الأقسام الداخلية في GPT. إنّ مجموعة من العبارات المرتبة التي كانت فعالة بسبب توقيتات محددة في التنفيذ قد لا تظل جاهزة للعمل في المستقبل.
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Setting page-level key-value targeting after calling
// googletag.enableServices().
googletag.enableServices();
googletag.defineSlot(...);
googletag.pubads().setTargeting(e, a);
الطرق المقترَحة لإصلاح الخطأ
// Correct: Setting page-level key-value targeting before calling
// googletag.enableServices().
googletag.pubads().setTargeting(e, a);
googletag.defineSlot(...);
googletag.enableServices();
شرح / وصف الحل تجنَّب شروط السباق من خلال الالتزام بالتوقيت المعتاد لـ GPT. مثال صالح تشمل الطلبات الجزئية ما يلي:
  • تحديد-تفعيل-الشبكة الإعلانية
    1. تحديد الإعدادات على مستوى الصفحة
    2. تحديد الخانات
    3. enableServices()
    4. خانات العرض
  • تفعيل تحديد الإعلانات على الشبكة الإعلانية
    1. تحديد الإعدادات على مستوى الصفحة
    2. enableServices()
    3. تحديد الخانات
    4. خانات العرض

السيناريو 7: إساءة استخدام عمليات الإغلاق وتحديد نطاق متغيّر JavaScript

وصف حالة استخدام عالية المستوى الافتراضات غير الصحيحة حول تحديد نطاق متغيّر JavaScript وقيمة المتغيرات تم تسجيله في الدالة التي تم تمريرها إلى googletag.cmd.push.
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Variable x is declared outside the anonymous function
// but referenced within it.
for (var x = 0; x < slotCount; x++) {
 window.googletag.cmd.push(
  function(){
    // If GPT is not yet loaded, this code will be executed subsequently when
    // the command queue is processed. Every queued function will use the last value
    // assigned to x (most likely slotCount).
    // This is because the function closure captures the reference to x,
    // not the current value of x.
    window.googletag.display(slot[x]);
  })
 }
}
الطرق المقترَحة لإصلاح الخطأ
window.googletag.cmd.push(
 function(){
  // Correct: We both declare and reference x inside the context of the function.
  for (var x = 0; x < slotCount; x++){
   window.googletag.display(slot[x]);
  }
 }
)
شرح / وصف الحل

في JavaScript، تؤدي عمليات الإغلاق إلى التقاط المتغيرات من خلال المرجع بدلاً من القيمة. يعني ذلك أنه إذا تمت إعادة تعيين المتغير، فسيتم استخدام قيمته الجديدة عند إجراء وإغلاقه يتم تنفيذه لاحقًا. ومن ثم سيكون سلوك الرمز في الإغلاق اعتمادًا على ما إذا يتم تنفيذ معاودة الاتصال على الفور أو تأخيرها.

في حالة تحميل GPT بشكل غير متزامن، بناءً على مدى سرعة تحميل GPT قد يتم تنفيذ عمليات الاستدعاء في قائمة انتظار الأوامر على الفور أم لا. في الفترة السابقة على سبيل المثال، يؤدي هذا إلى تغيير سلوك الأوامر الموضوعة في قائمة الانتظار.

لتجنب أي مشكلات، يجب كتابة التعليمات البرمجية دون افتراض أن الدوال الموضوعة في قائمة انتظار الأوامر على الفور، ويجب توخي الحذر بخصوص تحديد نطاق قواعد JavaScript.

السيناريو 8: نقل حاويات الخانات داخل نموذج العناصر في المستند (DOM) بعد استدعاء الشاشة

وصف حالة استخدام عالية المستوى يمكن أن يؤدي نقل حاويات الخانات أو إدخالها في نموذج العناصر في المستند (DOM) بعد استدعاء الشاشة إلى إعادة التدفق غير المرغوب فيه والسلوك غير المتوقع في GPT.
مثال على مقتطف رمز برمجي به خطأ
// Incorrect: Moving slot containers after calling display
googletag.defineSlot("/1234/travel/asia", [728, 90], "div-gpt-ad-123456789-0");
googletag.enableServices();
googletag.display("div-gpt-ad-123456789-0");
...
// Inserting another element before the slot container, pushing the slot container down the page.
document.body.insertBefore(someOtherElement, document.getElementById("div-gpt-ad-123456789-0"));
الطرق المقترَحة لإصلاح الخطأ
// Correct: Make any DOM order changes before calling display

document.body.insertBefore(someOtherElement, document.getElementById("div-gpt-ad-123456789-0"));
...
googletag.defineSlot("/1234/travel/asia", [728, 90], "div-gpt-ad-123456789-0");
googletag.enableServices();
googletag.display("div-gpt-ad-123456789-0");