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

تمثّل السيناريوهات التالية بعض الأخطاء الأكثر شيوعًا التي يتم رصدها عند تطبيق علامة 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 async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
// Also correct, if using Limited Ads
<script async src="https://pagead2.googlesyndication.com/tag/js/gpt.js"></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 بقائمة من الأوامر التي سيتم تشغيلها حالما يصبح جدول تقسيم المعرّف الفريد العمومي جاهزًا. هذه هي الطريقة الصحيحة للتأكّد من تشغيل معاودة الاتصال عند تحميل علامة "ناشر Google".

السيناريو 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();
}
شرح أو وصف الحلّ ستعمل علامة "ناشر Google" (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

وصف حالة استخدام عالية المستوى قد تؤدي ظروف السباق إلى حدوث أعطال مع تطوّر السمات الداخلية لمعرّف علامة "ناشر Google". في المستقبل، قد لا تظلّ مجموعة من العبارات التي تم ترتيبها بشكل غير صحيح والتي كانت تعمل بسبب التوقيتات المحددة في التنفيذ قابلة للتشغيل.
مثال على مقتطف الرمز مع خطأ 
// 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();
شرح أو وصف الحلّ تجنَّب شروط السباق من خلال الحرص على الالتزام بالتوقيت المعتاد في علامة "ناشر Google". وتشمل أمثلة الطلبات الجزئية الصالحة ما يلي:
  • تعريف-تفعيل-العرض
    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 بشكل غير متزامن، يعتمد ذلك على سرعة تحميل عمليات الاستدعاء في قائمة انتظار الأوامر على الفور أو قد لا يتم تنفيذها على الفور. وفي المثال أعلاه، يؤدي ذلك إلى تغيير سلوك الأوامر المدرَجة في قائمة الانتظار.

لتجنُّب حدوث أي مشاكل، يجب كتابة الرموز البرمجية بدون افتراض أنّ الدوال الموضوعة في قائمة انتظار الأوامر سيتم تنفيذها على الفور، ويجب توخي الحذر في ما يتعلق بقواعد تحديد نطاق 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");
السابق
مراقبة الأداء