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

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

---

כל הרשאה:

• נבדקים על ידי ממשקי API שדורשים אותם.
• זיהוי אוטומטי ב-JavaScript בארגז חול, על סמך ממשקי ה-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)

תיאור: הרשאת קריאה לחלקים מוגבלים של המקור להפניה.

הגדרה: הערכים הבוליאניים הבאים קובעים איזה חלק מהגורם מפנה אפשר לקרוא. אפשר לקרוא חלק נתון של המקור שמפנה רק אם החלק התואם הוא true. אם כל המשתנים הבוליאניים האלה מוגדרים ל-true, מבצע הקריאה יכול לקרוא ל-getReferrerUrl בלי לציין רכיב כדי לקבל את כתובת ה-URL המלאה של המפנה. אם לא מגדירים ערך, ערך ברירת המחדל הוא all. אם מוגדר ערך, הערך חייב להיות מערך של רכיבים, כאשר כל רכיב הוא אחד מהערכים הבאים: protocol, ‏ host, ‏ port, ‏ path, ‏ query או extension.

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

נדרש על ידי: 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

שם לתצוגה: החדרת מסגרות 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);
}

רישום ביומן

שם תצוגה: רישום במסוף

תיאור: רישום ביומן של 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'});
}