تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

<!-- 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() API، يمكنك إضافتها في أعلى النص البرمجي:

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، أضِف حقلاً إلى النموذج:

انتقِل إلى علامة التبويب Fields وانقر على Add Field.
اختَر نوع الحقل Text input.
يمكنك تغيير رقم التعريف من 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);

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

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

الأذونات

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

حدث خطأ أثناء الوصول إلى النطاق العام.

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

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

انتقل إلى علامة التبويب Permissions وانقر على رمز التوسيع Accesses Global Variables ثم انقر على Add Key.
استخدِم ga للمفتاح وضَع علامة في المربّعات بجانب Read وWrite و Execute.
كرِّر هذه العملية مع ga.q وga.l. يُرجى العِلم أنّ هذه الحقول لا تحتاج إلى إذن Execute.

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

خطأ في وحدة إدخال النصوص البرمجية

لضبط إذن "Inject Scripts"، عليك إجراء ما يلي:

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

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

والآن عند النقر على Run Code (تشغيل الرمز)، من المفترض ألا تكون هناك أي أخطاء في وحدة التحكم. لقد حولت العلامة بنجاح إلى نموذج مخصص. انقر على 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);