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

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

כל הרשאה היא:

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

access_globals

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

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

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

רישום ביומן

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

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

השם המוצג: קריאת נתונים באחסון של Analytics

תיאור: מאפשר לקרוא נתונים מאוחסנים של Analytics, כמו מזהי לקוחות.

הגדרה: אין

נדרש על ידי: readAnalyticsStorage

חתימת שאילתה: queryPermission('read_analytics_storage')

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

קוד לדוגמה

const queryPermission = require('queryPermission');
const readAnalyticsStorage = require('readAnalyticsStorage');
if (queryPermission('read_analytics_storage')) {
  const value = readAnalyticsStorage();
}

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')

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

קוד לדוגמה

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

‫Display name: Sets a cookie (השם המוצג: הגדרת קובץ Cookie)

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

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

נדרש על ידי: setCookie

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

הערות: המדיניות קובעת אם אפשר לכתוב קובץ Cookie, בהתאם לשם קובץ ה-Cookie, לדומיין, לנתיב, למאפיין 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

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

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