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

تمثل السيناريوهات التالية بعض الأخطاء الأكثر شيوعًا التي يتم ملاحظتها عند تنفيذ 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: ترتيب المكالمات إلى علامة "ناشر Google" بشكلٍ خاطئ

وصف حالة استخدام عالية المستوى قد تؤدي ظروف السباق إلى حدوث أعطال مع تطوّر الأقسام الداخلية في 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. خانات العرض
  • Enable-Define-Display
    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");

السيناريو 9: استبدال واجهات برمجة تطبيقات المتصفّح

وصف حالة استخدام عالية المستوى لا تتوفر ميزة استبدال البيانات (المعروفة أيضًا باسم "تصحيح القرد" و"الملء التلقائي") في المتصفِّح في مكتبة "علامات ناشر Google". قد تؤدي هذه الممارسة إلى تعطيل النصوص البرمجية التابعة لجهات خارجية، مثل GPT بطرق غير متوقعة.
مثال على مقتطف رمز يتضمّن خطأ
// Incorrect: Overwriting window.fetch
const { fetch: originalFetch } = window;
window.fetch = (...args) => {
 console.log('Fetching!');
 return originalFetch(resource, config);
};
الطرق المقترَحة لإصلاح الخطأ
// Correct: Avoid making changes to browser APIs.
// If you need custom logic, consider leaving the browser API intact.
const myFetch = (...args) => {
  console.log('Fetching!');
  return window.fetch(...args);
}