أذونات النماذج المخصَّصة

يوضّح هذا المستند الأذونات الخاصة بالنماذج المخصّصة على الويب.

---

كل إذن هو:

• يتم التحقّق منها من خلال واجهات برمجة التطبيقات التي تتطلّب ذلك.
• يتم رصدها تلقائيًا في JavaScript المحمية، استنادًا إلى واجهات برمجة التطبيقات المستخدَمة. يحدث ذلك عند إجراء التعديلات في محرِّر النماذج المخصّصة (لتلقّي ملاحظات سريعة)، وعند تجميع الرموز البرمجية (للتحقّق من فرض الأذونات الصحيحة).
• يمكن تعديلها في محرِّر النماذج المخصّصة لجعل الإذن أكثر تحديدًا.
• يمكن إجراء طلبات بحث عنها في JavaScript ضمن مساحة اختبار عبر واجهة برمجة التطبيقات queryPermission.

access_globals

الاسم المعروض: للوصول إلى المتغيّرات العمومية

الوصف: يتيح هذا الإذن الوصول إلى متغيّر عمومي (من المحتمل أن يشمل واجهات برمجة التطبيقات الحسّاسة).

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

مطلوبة من قِبل: setInWindow وcopyFromWindow وcallInWindow createQueue وcreateArgumentsQueue

توقيع الطلب: queryPermission('access_globals', 'read', <key to read from>) أو queryPermission('access_globals', 'write', <key to write to>) أو queryPermission('access_globals', 'readwrite', <key to read and write>) أو queryPermission('access_globals', 'execute', <key of function to execute>)

ملاحظات: تتحكّم هذه السمة في ما إذا كان بإمكان نموذج مخصّص قراءة و/أو الكتابة في القيمة العموميّة.

مثال على الرمز

const queryPermission = require('queryPermission');
const createQueue = require('createQueue');
if (queryPermission('access_globals', 'readwrite', 'dataLayer')) {
  const dataLayerPush = createQueue('dataLayer');
}

access_local_storage

الاسم المعروض: الوصول إلى مساحة التخزين المحلية

الوصف: يسمح بالوصول إلى المفاتيح المحدّدة في مساحة التخزين المحلية.

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

الجهة التي طلبت إجراء ذلك: localStorage

توقيع طلب البحث: queryPermission('access_local_storage', 'read', <key to read from>) أو queryPermission('access_local_storage', 'write', <key to write to>) أو queryPermission('access_local_storage', 'readwrite', <key to read and write>)

مثال على الرمز

const queryPermission = require('queryPermission');
const localStorage = require('localStorage');
const key = 'my_key';
if (queryPermission('access_local_storage', 'read', key)) {
  const value = localStorage.getItem(key);
}

access_template_storage

الاسم المعروض: يتيح هذا الإذن الوصول إلى مساحة تخزين النماذج.

الوصف: يسمح بالوصول إلى مساحة تخزين مؤقتة للنماذج التي يمكن لديها الاحتفاظ ببياناتها طوال مدة عرض الصفحة.

الإعداد: لا يوجد

الجهة التي طلبت إجراء ذلك: templateStorage

توقيع طلب البحث: queryPermission('access_template_storage')

مثال على الرمز

const queryPermission = require('queryPermission');
const templateStorage = require('templateStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
  const value = templateStorage.getItem(key);
}

get_cookies

الاسم المعروض: لقراءة قيم ملفات تعريف الارتباط

الوصف: يتيح هذا الإذن قراءة قيم ملفات تعريف الارتباط التي تحمل الاسم المحدّد.

الإعداد: قائمة بأسماء ملفات تعريف الارتباط المسموح بقراءتها

الجهة التي طلبت إجراء ذلك: getCookieValues

توقيع طلب البحث: queryPermission('get_cookies', <name>)

ملاحظات: تحدّد هذه السمة ما إذا كان يمكن قراءة ملف تعريف ارتباط استنادًا إلى اسمه.

مثال على الرمز

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

get_referrer

الاسم المعروض: لقراءة عنوان URL المُحيل

الوصف: يسمح بالوصول للقراءة إلى أجزاء محدّدة من المُحيل.

الإعداد: تحدّد القيم المنطقية التالية الجزء الذي يمكن قراءةه من المُحيل. لا يمكن قراءة جزء معيّن من المُحيل إلا إذا كان الجزء المقابل له true. يمكن للمتصل الاتصال بـ getReferrerUrl بدون مكوّن محدّد للحصول على عنوان URL الكامل للمُحيل إذا تم ضبط كل هذه القيم المنطقية على true. إذا لم يتم تحديد قيمة، تكون القيمة التلقائية هي all. في حال ضبط قيمة، يجب أن تكون القيمة صفيفًا من المكوّنات يكون المكوّن فيها أحد العناصر التالية: protocol أو host أو port أو path أو query أو extension.

queryKeys: في حال اختيار طلب البحث، يمكن لمؤلف النموذج فرض قيود إضافية على مجموعة مفاتيح طلبات البحث التي يمكنه القراءة منها. هذه صفيف بسيط من المفاتيح، بدون استخدام العناصر النائبة.

الجهات التي تتطلّب ذلك: getReferrerUrl وgetReferrerQueryParameters

توقيع طلب البحث: queryPermission('get_referrer', <url_component>)

مثال على الرمز

const queryPermission = require('queryPermission');
const getReferrerUrl = require('getReferrerUrl');
let referrer;
if (queryPermission('get_referrer', 'query')) {
  referrer = getReferrerUrl('queryParams');
}

get_url

الاسم المعروض: يقرأ عنوان URL

الوصف: تعرِض هذه السمة جزءًا من عنوان URL للصفحة الحالية أو كلّه.

الإعداد: تحدِّد القيم المنطقية التالية الجزء الذي يمكن قراءة عنوان URL منه. لا يمكن قراءة جزء معيّن من عنوان URL إلا إذا كان الجزء المقابل له هو true. يمكن للمتصل الاتصال بـ getUrl بدون تحديد مكوّن للحصول على عنوان URL بالكامل إذا تم ضبط كل هذه القيم المنطقية على true فقط. إذا لم يتم تحديد قيمة، تكون القيمة التلقائية هي all. في حال ضبط قيمة، يجب أن تكون القيمة صفيفًا للمكوّنات يكون فيها المكوّن أحد العناصر التالية: protocol أو host أو port أو path أو query أو extension أو fragment.

queryKeys: في حال اختيار طلب البحث، يمكن لمؤلف النموذج فرض قيود إضافية على مجموعة مفاتيح طلبات البحث التي يمكنه القراءة منها. هذه صفيف بسيط من المفاتيح، بدون استخدام العناصر النائبة.

الجهة التي طلبت إجراء ذلك: getUrl

توقيع طلب البحث: queryPermission('get_url', <optional url component>, <optional query key>)

في حال توفّر مكوّن عنوان URL، يجب أن يكون أحد الخيارات التالية: 'protocol' أو 'host' أو 'port' أو 'path' أو 'query' أو 'extension' أو 'fragment'. في حال حذفه، يكون طلب الإذن عبارة عن طلب للوصول إلى عنوان URL بالكامل.

في حال توفّر مفتاح طلب البحث، يجب أن يكون مَعلمة سلسلة طلب البحث التي يريد رمز النموذج قراءةً.

ملاحظات: تتحكّم هذه السمة في ما إذا كان بإمكان نموذج مخصّص القراءة من المحتوى الحالي في الموقع الجغرافي. يتيح هذا الخيار حصر البيانات بجزء معيّن من الموقع الجغرافي.

مثال على الرمز

const queryPermission = require('queryPermission');
const getUrl = require('getUrl');
if (queryPermission('get_url', 'query', 'gclid')) {
  const gclid = getUrl('query', false, null, 'gclid');
}

inject_hidden_iframe

الاسم المعروض: يُستخدَم لإدراج إطارات iframe مخفية.

الوصف: يتيح هذا الإذن إدخال إطار iframe غير مرئي باستخدام عنوان URL معيّن.

الإعداد: قائمة بأنماط عناوين URL

الجهة التي طلبت إجراء ذلك: injectHiddenIframe

توقيع طلب البحث: queryPermission('inject_hidden_iframe', <url>)

ملاحظات: تحدد هذه السمة ما إذا كان بإمكان نموذج مخصّص إدخال إطار iFrame غير مرئي، وتحديد مصدره.

مثال على الرمز

const queryPermission = require('queryPermission');
const injectHiddenIframe = require('injectHiddenIframe');
const url = 'https://www.example.com/iframes';
if (queryPermission('inject_hidden_iframe', url)) {
  injectHiddenIframe(url);
}

inject_script

الاسم المعروض: لإدراج نصوص برمجية

الوصف: يتم إدخال نص برمجي في الصفحة.

الإعداد: قائمة بأنماط عناوين URL

الجهة التي طلبت إجراء ذلك: injectScript

توقيع طلب البحث: queryPermission('inject_script', <url>)

ملاحظات: تحدّد هذه السمة ما إذا كان بإمكان نموذج مخصّص إدراج JavaScript، ومن أي مصدر يمكنه إجراء ذلك.

مثال على الرمز

const queryPermission = require('queryPermission');
const injectScript = require('injectScript');
const url = 'https://www.example.com?api.js';
if (queryPermission('inject_script', url)) {
  injectScript(url);
}

تسجيل

الاسم المعروض: إرسال السجلات إلى وحدة التحكّم

الوصف: يتيح هذا الإذن إرسال سجلّات إلى وحدة تحكّم المطوّرين وفي وضع المعاينة في "إدارة العلامات من Google".

الإعداد: خيار تفعيل التسجيل في قناة الإصدار العلني الإعداد التلقائي هو تفعيل تسجيل البيانات في وضع تصحيح الأخطاء/المعاينة فقط. في حال رفض الإذن، لن يُرسِل logToConsole خطأً، ولكن سيتم حظر رسالة السجلّ.

الجهة التي طلبت إجراء ذلك: logToConsole

توقيع طلب البحث: queryPermission('logging')

ملاحظات: تتحكّم هذه السمة في ما إذا كان بإمكان نموذج مخصّص تسجيل الدخول إلى وحدة تحكّم المطوّر.

مثال على الرمز

const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');

read_data_layer

الاسم المعروض: لقراءة طبقة البيانات

الوصف: يتيح هذا الإذن قراءة البيانات من طبقة البيانات.

الإعداد: مجموعة من تعبيرات مطابقة المفاتيح، حيث يمكن أن تكون مطابقة المفتاح سلسلة مقدّمة من الإحالات التي تحتوي على نقاط، مع حرف بدل متأخر. تحدِّد تعبيرات مطابقة المفتاح السمات التي يمكن قراءتها من طبقة البيانات.

الجهة التي طلبت إجراء ذلك: copyFromDataLayer

توقيع طلب البحث: queryPermission('read_data_layer', <data layer key to read from>)

ملاحظات: تتحكّم في ما إذا كان بإمكان نموذج مخصّص القراءة من طبقة البيانات.

مثال على الرمز

const queryPermission = require('queryPermission');
const copyFromDataLayer = require('copyFromDataLayer');
const dlKey = 'foo.bar';
if (queryPermission('read_data_layer', dlKey)) {
  const dlContents = copyFromDataLayer(dlKey);
}

read_character_set

الاسم المعروض: يتيح هذا الإذن قراءة دليل الرموز في المستند.

الوصف: يقرأ document.characterSet.

الإعداد: لا يوجد

الجهة التي طلبت إجراء ذلك: readCharacterSet

توقيع طلب البحث: queryPermission('read_character_set')

ملاحظات: تحدّد ما إذا كان بإمكان نموذج مخصّص قراءة document.characterSet.

مثال على الرمز

const queryPermission = require('queryPermission');
const readCharacterSet = require('readCharacterSet');
if (queryPermission('read_character_set')) {
  const characterSet = readCharacterSet();
}

read_container_data

الاسم المعروض: يتيح قراءة بيانات الحاوية

الوصف: يتيح هذا الإذن قراءة البيانات حول الحاوية.

الإعداد: لا يوجد

الجهة التي طلبت إجراء ذلك: getContainerVersion

توقيع طلب البحث: queryPermission('read_container_data')

ملاحظات: تتحكّم هذه السمة في ما إذا كان بإمكان نموذج مخصّص قراءة البيانات عن الحاوية.

مثال على الرمز

const queryPermission = require('queryPermission');
const getCookieValues = require('getContainerVersion');
let version;
if (queryPermission('read_container_data')) {
  version = getContainerVersion();
}

read_event_metadata

الاسم المعروض: يتيح هذا الإذن قراءة البيانات الوصفية للحدث.

الوصف: يتيح هذا الإذن قراءة البيانات الوصفية للحدث في "عمليات استدعاء الأحداث".

الإعداد: لا يوجد

الجهة التي طلبت إجراء ذلك: addEventCallback

توقيع طلب البحث: queryPermission('read_event_metadata')

ملاحظات: تتحكّم هذه السمة في ما إذا كان بإمكان نموذج مخصّص قراءة البيانات الوصفية للحدث في callbacks.

مثال على الرمز

const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
  addEventCallback((containerId, eventMetadata) => {
    // Read event metadata.
  });
}

read_title

الاسم المعروض: لقراءة عنوان المستند

الوصف: يقرأ document.title.

الإعداد: لا يوجد

الجهة التي طلبت إجراء ذلك: readTitle

توقيع طلب البحث: queryPermission('read_title')

ملاحظات: تحدّد ما إذا كان بإمكان نموذج مخصّص قراءة document.title.

مثال على الرمز

const queryPermission = require('queryPermission');
const readTitle = require('readTitle');
if (queryPermission('read_title')) {
  const title = readTitle();
}

send_pixel

الاسم المعروض: لإرسال وحدات البكسل

الوصف: يتيح هذا الإذن إرسال طلب استرداد بيانات باستخدام GET إلى عنوان URL محدّد. ولا تتم معالجة الردّ.

الإعداد: قائمة بأنماط عناوين URL المسموح بها

الجهة التي طلبت إجراء ذلك: sendPixel

توقيع طلب البحث: queryPermission('send_pixel', <url>)

ملاحظات: تحدّد هذه السمة ما إذا كان بإمكان نموذج مخصّص إرسال طلب GET، وإلى أي مصدر يمكنه إرسال هذا الطلب.

مثال على الرمز

const queryPermission = require('queryPermission');
const sendPixel = require('sendPixel');
const url = 'https://www.example.com?foo=3';
if (queryPermission('send_pixel', url)) {
  sendPixel(url);
}

set_cookies

الاسم المعروض: لضبط ملف تعريف ارتباط

الوصف: يُستخدَم لضبط ملفّ تعريف ارتباط بالاسم والمَعلمات المحدّدَين.

الإعداد: جدول بأسماء ملفات تعريف الارتباط المسموح بها، ولكل منها قيود optional على الاسم والنطاق والمسار وسمة secure ووقت انتهاء الصلاحية.

الجهة التي طلبت إجراء ذلك: setCookie

توقيع طلب البحث: queryPermission('set_cookies', <name>, <options>)

ملاحظات: تحدّد هذه السمة ما إذا كان يمكن كتابة ملف تعريف ارتباط، استنادًا إلى اسم ملف تعريف الارتباط ونطاقه ومساره وسمة secure وتاريخ انتهاء صلاحيته.

مثال على الرمز

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}

write_data_layer

الاسم المعروض: لكتابة طبقة البيانات

الوصف: تُستخدَم هذه السمة لكتابة البيانات في طبقة البيانات.

الإعداد: مجموعة من تعبيرات مطابقة المفاتيح، حيث يمكن أن تكون مطابقة المفتاح سلسلة مقدّمة من الإحالات التي تحتوي على نقاط، مع حرف بدل متأخر. تتحكم عبارات مطابقة المفتاح في المواقع التي يمكنها الكتابة في طبقة البيانات.

الجهة التي طلبت إجراء ذلك: gtagSet

توقيع طلب البحث: queryPermission('write_data_layer', <data layer key to write from>)

ملاحظات: تتحكّم في ما إذا كان بإمكان نموذج مخصّص الكتابة في طبقة البيانات.

مثال على الرمز

const queryPermission = require('queryPermission');
const gtagSet = require('gtagSet');
const dlKey = 'foo.bar';
if (queryPermission('write_data_layer', dlKey)) {
  gtagSet({dlKey: 'baz'});
}