تحويل علامة حالية

ستتعرَّف في هذا الدليل على كيفية تحويل علامة HTML مخصَّصة حالية إلى استخدام JavaScript في وضع الحماية.

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

ملاحظة: من الناحية العملية، يجب تجنُّب injectScript() وتنفيذ النص البرمجي المستهدف مباشرةً في JavaScript في وضع الحماية. لا يتطلّب هذا الإجراء الثقة في جهة خارجية، ما يزيد من احتمال السماح به بموجب السياسات المفروضة.

العلامة الأصلية

تنبيه: يتم استخدام النص البرمجي analytics.js كمثال هنا، ولكن من المفترض أن يكون هذا النص مستخدَمًا. لن يتم استخدامها في مرحلة الإنتاج. بدلاً من ذلك، اتّبِع الخطوات الواردة في مقالة نشر "إحصاءات Google" باستخدام أداة "إدارة العلامات من Google".

<!-- Google Analytics -->
<script>
  window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
  ga('create', 'UA-XXXXXX-1', 'auto');
  ga('send', 'pageview');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
<!-- End Google Analytics -->

تحويل الرمز البرمجي

ضع في الاعتبار جزء JavaScript من العلامة أعلاه:

window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXXXX-1', 'auto');
ga('send', 'pageview');

لإنشاء محتوى JavaScript ضروري في وضع الحماية، اطّلِع على ماهية JavaScript الأصلية واجهات برمجة التطبيقات التي يستخدمها هذا النص البرمجي وتحويل الرمز البرمجي لاستخدام المكافئ المكافئ في وضع الحماية واجهات برمجة تطبيقات JavaScript.

على سبيل المثال، في العلامة analytics.js، يتم استخدام واجهات برمجة تطبيقات JavaScript الأصلية التالية:

JavaScript أصلي	JavaScript في وضع الحماية
window.ga	setInWindow
arguments	createArgumentsQueue
+ new Date	getTimestamp

لاستخدام واجهات برمجة تطبيقات JavaScript في وضع الحماية في النص البرمجي، يجب require. على سبيل المثال، لاستخدام واجهة برمجة التطبيقات setInWindow()، أضِفها إلى أعلى النص البرمجي:

const setInWindow = require('setInWindow');

بعد ذلك، تحويل window.ga:

window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)}
// becomes
const createArgumentsQueue = require('createArgumentsQueue');
const ga = createArgumentsQueue('ga', 'ga.q');

بعد ذلك، يمكنك تحويل المهمة ga.l:

ga.l=+new Date;
// becomes
const getTimestamp = require('getTimestamp');
setInWindow('ga.l', getTimestamp(), true);

أخيرًا، تحويل المكالمتَين إلى ga():

ga('create', 'UA-XXXXXX-1', 'auto');
ga('send', 'pageview');
// becomes
const trackingId = data.trackingId;
ga('create', trackingId, 'auto');
ga('send', 'pageview');

لاستخدام data.trackingId، أضِف حقلاً إلى النموذج:

1. انتقِل إلى علامة التبويب "Fields" وانقر على Add Field.

   

2. اختَر نوع الحقل Text input.

   

3. غيِّر رقم التعريف من text1 إلى trackingId.

   

في هذه المرحلة، تكون قد حوّلت أول علامة <script/>، ولكن يجب أيضًا للتحميل في النص البرمجي الداعم

ولإجراء ذلك:

<script async src='https://www.google-analytics.com/analytics.js'></script>

// becomes
const injectScript = require('injectScript');
const url = 'https://www.google-analytics.com/analytics.js';
injectScript(url, data.gtmOnSuccess, data.gtmOnFailure, url);

ملاحظة: يكون عادةً عنوان URL للنص البرمجي قيمة cacheToken جيدة.

يؤدي تمرير cacheToken إلى injectScript() إلى تفعيل التحسين. بالنسبة إلى في السيناريوهات التالية، سيتم تحميل النص البرمجي analytics.js مرة واحدة فقط:

• يشير هذا المصطلح إلى علامة يتم تشغيلها عدة مرات.
• أكثر من علامة واحدة من هذا النموذج المخصّص في الحاوية نفسها
• نماذج مخصّصة أخرى تستخدم injectScript() مع cacheToken نفسها

تنبيه: احرص على إرسال معلومات معاودة الاتصال "data.gtmOnSuccess" إلى injectScript(). يجب استدعاء data.gtmOnSuccess لجميع الإعدادات المخصصة النماذج. إذا قدّمت معاودة الاتصال بنجاح الخاصة بك، تأكَّد من أنّها تطلب data.gtmOnSuccess.

الأذونات

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

تظهر هذه الأخطاء لأن JavaScript يتطلب وضع الحماية أن تعلن عن القيم وعناوين URL التي يمكنك الوصول إليها. في هذا المثال، يجب الوصول إلى ga.q، ga.l وga متغير عمومي، وتريد إدخال نص برمجي تتم استضافته في https://www.google-analytics.com/analytics.js.

لضبط أذونات Global Variables:

1. الانتقال إلى علامة التبويب "Permissions" وتوسيع القسم "Accesses Global Variables" ثم انقر على Add Key.

   

2. استخدِم ga للمفتاح، وضَع علامة في المربّعات بجانب Read وWrite و Execute

   

3. كرر هذه العملية لـ ga.q وga.l. لاحظ أن هذه الحقول لا تحتاج الحصول على إذن Execute

   

في هذه المرحلة، إذا نقرت على Run Code (تشغيل الرمز) مرة أخرى، سيظهر لك خطأ جديد في وحدة التحكّم. هذه المرّة، تتم الإشارة إلى Inject Scripts في رسالة الخطأ.

لضبط إذن Inject Scripts:

1. أضِف https://www.google-analytics.com/analytics.js إلى Allowed URL Match Patterns.

   

   ملاحظة: تسمح URL Match Patterns بأحرف البدل للنطاق الفرعي والمسار، لذا كان بإمكانك استخدام https://www.google-analytics.com/*. ومع ذلك، هناك المزيد من يتم تفضيل أنماط مطابقة محددة إن أمكن. يمكنك الاطّلاع على سياسة inject_script للاطّلاع على التفاصيل الكاملة للسياسة.

الآن عند النقر على تشغيل الرمز، من المفترض ألا تكون هناك أخطاء في وحدة التحكّم. لديك تم تحويل العلامة إلى نموذج مخصص بنجاح. النقر على Save واستخدِم علامتك الجديدة تمامًا مثل أي علامة أخرى في أداة "إدارة العلامات من Google".

علامة محوَّلة بالكامل

يجب أن تبدو نتيجة JavaScript النهائية التي تم وضع الحماية لها على النحو التالي:

const setInWindow = require('setInWindow');
const copyFromWindow = require('copyFromWindow');
const createArgumentsQueue = require('createArgumentsQueue');
const getTimestamp = require('getTimestamp');
const injectScript = require('injectScript');
const trackingId = data.trackingId;

const ga = createArgumentsQueue('ga', 'ga.q');
setInWindow('ga.l', getTimestamp(), false);
ga('create', trackingId, 'auto');
ga('send', 'pageview');
const url = 'https://www.google-analytics.com/analytics.js';
injectScript(url, data.gtmOnSuccess, data.gtmOnFailure, url);