הרשאות לשימוש בתבניות מותאמות אישית

במסמך הזה מתוארות ההרשאות לתבניות בהתאמה אישית לאינטרנט.

כל הרשאה היא:

  • נבדקים על ידי ממשקי API שדורשים אותם.
  • זיהוי אוטומטי ב-JavaScript שבארגז חול (sandbox), על סמך ממשקי ה-API שבהם נעשה שימוש. הסיבה לכך היא שהעריכות מתבצעות בכלי לעריכת תבניות בהתאמה אישית (כדי ליצור לולאת משוב מהירה) וכשהקוד מורכב (כדי לוודא שנאכפים את ההרשאות הנכונות).
  • ניתן לערוך את ההרשאה באמצעות עורך תבניות בהתאמה אישית כדי לקבל הרשאה ספציפית יותר.
  • אפשר לשלוח שאילתות ב-JavaScript בארגז חול באמצעות ה-API של queryPermission.

access_globals

שם לתצוגה: יש גישה למשתנים גלובליים

תיאור: הרשאה שמאפשרת גישה למשתנה גלובלי (שעשוי לכלול ממשקי API רגישים).

Configuration: רשימת המפתחות שאפשר לגשת אליהם. כל מפתח הוא נתיב שמופרד באמצעות נקודה. לדוגמה: 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

שם תצוגה: קריאת הערכים של קובצי ה-Cookie

תיאור: קריאת הערכים של קובצי ה-Cookie עם השם שצוין.

הגדרה: רשימה של שמות קובצי cookie שמותר לקרוא.

חובה על פי: getCookieValues

חתימה של שאילתה: queryPermission('get_cookies', <name>)

הערות: קובעת אם ניתן לקרוא קובץ Cookie, בהתאם לשם שלו.

קוד לדוגמה

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

get_referrer

שם מוצג: קריאה של כתובת ה-URL ממקור ההפניה (referrer)

תיאור: מאפשרת גישת קריאה לחלקים מצומצמים של מקור ההפניה (referrer).

הגדרה: הערכים הבוליאניים הבאים קובעים איזה חלק מהגורם מפנה אפשר לקרוא. אפשר לקרוא חלק נתון של המקור שמפנה רק אם החלק התואם הוא true. אם כל המשתנים הבוליאניים האלה מוגדרים ל-true, מבצע הקריאה יכול לקרוא ל-getReferrerUrl בלי לציין רכיב כדי לקבל את כתובת ה-URL המלאה של המפנה. אם לא מוגדר ערך, ערך ברירת המחדל הוא 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: אם בוחרים באפשרות query, מחבר התבנית יכול להגביל עוד יותר את קבוצת מפתחות השאילתות שהוא יכול לקרוא מהם. זהו מערך פשוט של מפתחות, בלי תווים כלליים לחיפוש.

חובה על פי: 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

שם תצוגה: החדרת iframes מוסתרים

תיאור: החדרת 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);
}

רישום ביומן

שם תצוגה: יומנים למסוף

תיאור: יומנים ל-Developer Console ולמצב התצוגה המקדימה של GTM.

הגדרה: אפשרות להפעלת הרישום ביומן בסביבת הייצור. ברירת המחדל היא הפעלת רישום ביומן רק בניפוי באגים או בתצוגה מקדימה. אם ההרשאה תידחה, הפונקציה 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

שם מוצג: קריאה של שכבת נתונים

תיאור: קריאת נתונים מ-dataLayer.

הגדרה: קבוצה של ביטויי התאמה מרכזיים, שבהם התאמה למפתח יכולה להיות סדרה מובילה של הפניות מנוקדות, עם תו כללי לחיפוש בסוף. ביטויים להתאמת מפתחות קובעים אילו נכסים אפשר לקרוא משכבת הנתונים.

חובה על ידי: 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

שם תצוגה: קריאת המטא-נתונים של האירוע

תיאור: קריאת המטא-נתונים של האירוע בקריאות חוזרות (callbacks) של אירועים

הגדרה: ללא

חובה על ידי: 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

שם תצוגה: מגדיר קובץ Cookie

תיאור: הגדרה של קובץ Cookie עם השם והפרמטרים שצוינו.

הגדרה: טבלה של שמות קובצי cookie מותרים, עם הגבלות אופציונליות על השם, הדומיין, הנתיב, המאפיין secure ותוקף התוקף.

חובה על פי: setCookie

חתימה של שאילתה: queryPermission('set_cookies', <name>, <options>)

הערות: קובע אם ניתן לכתוב קובץ Cookie, בהתאם לשם, לדומיין, לנתיב, למאפיין secure ולתוקף של קובץ ה-Cookie.

קוד לדוגמה

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

שם מוצג: כתיבה של שכבת הנתונים

תיאור: כתיבת נתונים ל-dataLayer.

הגדרה: קבוצה של ביטויים להתאמה למפתחות, שבהם התאמה למפתח יכולה להיות סדרה של הפניות עם נקודות בתחילת הביטוי, עם תו כללי בסוף. ביטויים של התאמת מפתחות קובעים אילו נכסים יכולים לכתוב בשכבת הנתונים.

חובה על פי: 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'});
}