ממשקי API של תבניות מותאמות אישית

ממשקי API מרכזיים

ממשקי ה-API האלה פועלים עם JavaScript בארגז חול כדי ליצור תבניות בהתאמה אישית ב-Google Tag Manager. כל API מתווסף עם הצהרת require(), למשל:

const myAPI = require('myAPI');

`addConsentListener`

רושמת פונקציית listener לביצוע כשהמצב של סוג ההסכמה שצוין משתנה.

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

דוגמה:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

תחביר

addConsentListener(consentType, listener)

פרמטרים

פרמטר	סוג	תיאור
`consentType`	מחרוזת	סוג ההסכמה שרוצים להאזין לשינויים במצב שלה.
`listener`	function	הפונקציה שמופעלת כשמצב ההסכמה שצוין משתנה.

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

פרמטר	סוג	תיאור
`consentType`	מחרוזת	סוג ההסכמה שמשתנה.
`granted`	boolean	ערך בוליאני שמוחזר כ-true אם סוג ההסכמה שצוין משתנה למצב granted.

הרשאות משויכות

הרשאה access_consent עם גישת קריאה לסוג ההסכמה.

`addEventCallback`

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

תחביר

addEventCallback(callback)

פרמטרים

פרמטר	סוג	תיאור
`callback`	function	הפונקציה להפעלה בסיום האירוע.

האובייקט eventData מכיל את הנתונים הבאים:

שם מפתח	סוג	תיאור
`tags`	מערך	מערך של אובייקטים של נתוני תגים. לכל תג שהופעל במהלך האירוע תהיה רשומה במערך הזה. אובייקט נתוני התג מכיל את מזהה התג (`id`), את סטטוס הביצוע שלו (`status`) ואת זמן הביצוע שלו (`executionTime`). נתוני התג יכללו גם מטא-נתונים נוספים של התג שהוגדרו בתג.

דוגמה

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

הרשאות משויכות

read_event_metadata

`aliasInWindow`

‫aliasInWindow API מאפשר ליצור כינוי (לדוגמה, window.foo = window.bar), שעוזר לתמוך בתגים מסוימים שנדרש להם כינוי. מקצה את הערך באובייקט window שנמצא במיקום fromPath למפתח באובייקט window במיקום toPath. מחזירה true אם הפעולה בוצעה ללא שגיאות, false אחרת.

תחביר

aliasInWindow(toPath, fromPath)

פרמטרים

פרמטר	סוג	תיאור
`toPath`	מחרוזת	נתיב מופרד בנקודות לאובייקט `window` שאליו צריך להעתיק ערך. כל הרכיבים בנתיב עד הרכיב האחרון צריכים להיות קיימים כבר באובייקט `window`.
`fromPath`	מחרוזת	נתיב מופרד בנקודות אל `window` לערך להעתקה. אם הערך לא קיים, הפעולה תיכשל.

דוגמה

aliasInWindow('foo.bar', 'baz.qux')

הרשאות משויכות

ההרשאה access_globals נדרשת גם ל-toPath וגם ל-fromPath. ל-toPath נדרשת הרשאת כתיבה, ול-fromPath נדרשת הרשאת קריאה.

`callInWindow`

המדיניות הזו מאפשרת לקרוא לפונקציות מנתיב מחוץ לאובייקט window, בצורה מבוקרת. מפעילה את הפונקציה בנתיב הנתון ב-window עם הארגומנטים הנתונים ומחזירה את הערך. אם אי אפשר למפות את סוג ההחזרה ישירות לסוג שנתמך ב-JavaScript בסביבת ארגז חול, יוחזר הערך undefined. שמונת הסוגים שנתמכים ב-JavaScript בסביבת ארגז חול הם null,‏ undefined,‏ boolean,‏ number,‏ string,‏ Array,‏ Object ו-function. אם הנתיב שצוין לא קיים או לא מפנה לפונקציה, הפונקציה מחזירה undefined.

תחביר

callInWindow(pathToFunction, argument [, argument2,... argumentN])

פרמטרים

פרמטר	סוג	תיאור
`pathToFunction`	מחרוזת	נתיב מופרד בנקודות לפונקציה ב-`window` להפעלה.
`args`	*	הארגומנטים שיועברו לפונקציה.

הרשאות משויכות

‫access_globals כשההרשאה execute מופעלת.

`callLater`

קובעת מועד לשיחה עם פונקציה שתתבצע באופן אסינכרוני. המערכת תקרא לפונקציה אחרי שהקוד הנוכחי יחזיר ערך. הפונקציה הזו שוות ערך ל-setTimeout(<function>, 0).

תחביר

callLater(function)

פרמטרים

פרמטר	סוג	תיאור
`function`	function	הפונקציה להפעלה.

`copyFromDataLayer`

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

תחביר

copyFromDataLayer(key[, dataLayerVersion])

פרמטרים

פרמטר	סוג	תיאור
`key`	מחרוזת	המפתח בפורמט 'a.b.c'.
`dataLayerVersion`	number	גרסת שכבת הנתונים האופציונלית. ערך ברירת המחדל הוא 2. אנחנו ממליצים מאוד שלא להשתמש בערך 1.

הרשאות משויכות

read_data_layer

`copyFromWindow`

מעתיק משתנה מאובייקט window. אם אי אפשר למפות את הערך ב-window ישירות לסוג שנתמך ב-JavaScript בסביבת ארגז חול, יוחזר הערך undefined. שמונת הסוגים שנתמכים ב-JavaScript בסביבת ארגז חול הם null,‏ undefined,‏ boolean,‏ number,‏ string,‏ Array,‏ Object ו-function. הפונקציה מחזירה את הערך שאוחזר (ואולץ).

תחביר

copyFromWindow(key)

פרמטרים

פרמטר	סוג	תיאור
`key`	מחרוזת	המפתח ב-`window` שאותו רוצים להעתיק.

הרשאות משויכות

access_globals

`createArgumentsQueue`

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

יוצר פונקציה בהיקף גלובלי (כלומר window), באמצעות הארגומנט fnKey (אותה סמנטיקה כמו createQueue). אחרי שהפונקציה נוצרת, ה-API הזה יוצר מערך ב-window (אם הוא עדיין לא קיים) באמצעות הארגומנט arrayKey.

כשקוראים לפונקציה שנוצרה ב-fnKey, היא דוחפת את אובייקט הארגומנטים שלה למערך שנוצר ב-arrayKey. הערך שהפונקציה מחזירה מה-API הוא הפונקציה שנוצרה בקטע fnKey.

כדי להשתמש בפונקציה הזו, צריך להגדיר הרשאות קריאה וכתיבה ל-fnKey ול-arrayKey בהרשאה access_globals.

דוגמה:

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

תחביר

createArgumentsQueue(fnKey, arrayKey)

פרמטרים

פרמטר	סוג	תיאור
`fnKey`	מחרוזת	הנתיב ב-`window` שבו הפונקציה מוגדרת, אם היא לא קיימת כבר. הארגומנט הזה תומך בסימון נקודות רגיל. אם הנתיב של המפתח לא קיים, מוצג חריג. כלומר, אם `fnKey` הוא `'one.two'`, תופעל חריגה.
`arrayKey`	מחרוזת	הנתיב ב-`window` שבו המערך מוגדר, אם הוא עדיין לא קיים. הארגומנט הזה תומך בסימון נקודות רגיל. אם הנתיב של המפתח לא קיים, מוצג חריג. כלומר, אם `arrayKey` הוא `'one.two'` ואין אובייקט גלובלי בשם `'one'`, תופעל חריגה.

הרשאות משויכות

access_globals

`createQueue`

יוצרת מערך ב-window (אם הוא עדיין לא קיים) ומחזירה פונקציה שתדחוף ערכים למערך הזה.

כדי להשתמש בפונקציה הזו, צריך להגדיר הרשאות קריאה וכתיבה ל-arrayKey בהרשאה access_globals.

דוגמה:

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

תחביר

createQueue(arrayKey)

פרמטרים

פרמטר	סוג	תיאור
`arrayKey`	מחרוזת	המפתח ב-`window` שבו המערך מוגדר, אם הוא עדיין לא קיים. הארגומנט הזה תומך בסימון נקודות רגיל. אם הנתיב של המפתח לא קיים, מוצג חריג. לדוגמה, אם `arrayKey` הוא `'one.two'`, ואין אובייקט גלובלי בשם `'one'`, תופעל חריגה.

הרשאות משויכות

access_globals

`decodeUri`

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

דוגמה:

const decode = require('decodeUri');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

תחביר

decodeUri(encoded_uri)

פרמטרים

פרמטר	סוג	תיאור
`encoded_uri`	מחרוזת	כתובת URI שעברה קידוד על ידי `encodeUri()` או בדרכים אחרות.

הרשאות משויכות

ללא.

`decodeUriComponent`

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

דוגמה:

const decode = require('decodeUriComponent');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

תחביר

decodeUriComponent(encoded_uri_component)

פרמטרים

פרמטר	סוג	תיאור
`encoded_uri_component`	מחרוזת	רכיב URI שעבר קידוד על ידי `encodeUriComponent()` או באמצעים אחרים.

הרשאות משויכות

ללא.

`encodeUri`

הפונקציה מחזירה מזהה משאבים אחיד (URI) מקודד על ידי ביטול התפקיד המיוחד של תווים מיוחדים. הפונקציה מחזירה מחרוזת שמייצגת את המחרוזת שצוינה, אחרי קידוד כ-URI. מחזירה undefined כשמספקים קלט לא תקין (תוחם יחיד).

דוגמה:

sendPixel('https://www.example.com/' + encodeUri(pathInput));

תחביר

encodeUri(uri)

פרמטרים

פרמטר	סוג	תיאור
`uri`	מחרוזת	‫URI מלא.

הרשאות משויכות

ללא.

`encodeUriComponent`

דוגמה:

sendPixel('https://www.example.com/?' + encodeUriComponent(queryInput));

תחביר

encodeUriComponent(str)

פרמטרים

פרמטר	סוג	תיאור
`str`	מחרוזת	רכיב של URI.

הרשאות משויכות

ללא.

`fromBase64`

‫fromBase64 API מאפשר לכם לפענח מחרוזות מהייצוג שלהן ב-base64. הפונקציה מחזירה undefined אם הקלט לא תקין.

תחביר

fromBase64(base64EncodedString)

פרמטרים

פרמטר	סוג	תיאור
`base64EncodedString`	מחרוזת	מחרוזת בקידוד Base64.

דוגמה

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

הרשאות משויכות

ללא

`generateRandom`

הפונקציה מחזירה מספר (מספר שלם) אקראי בטווח הנתון.

תחביר

generateRandom(min, max)

פרמטרים

פרמטר	סוג	תיאור
`min`	number	הערך המינימלי האפשרי של המספר השלם שמוחזר.
`max`	number	הערך הפוטנציאלי המקסימלי של המספר השלם שמוחזר.

הרשאות משויכות

ללא.

`getContainerVersion`

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

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

דוגמה

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

תחביר

getContainerVersion();

הרשאות משויכות

read_container_data

`getCookieValues`

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

תחביר

getCookieValues(name[, decode])

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	השם של קובץ ה-Cookie.
`decode`	boolean	ההגדרה הזו קובעת אם הערכים של קובצי ה-Cookie יפוענחו באמצעות הפונקציה `decodeURIComponent()` של JavaScript. ברירת המחדל היא `true`.

הרשאות משויכות

get_cookies

`getQueryParameters`

הפונקציה מחזירה את הפרמטר הראשון או את כל הפרמטרים של queryKey בכתובת ה-URL הנוכחית. מחזירה את הערך הראשון מה-queryKey או מערך של ערכים מה-queryKey.

תחביר

getQueryParameters(queryKey[, retrieveAll])

פרמטרים

פרמטר	סוג	תיאור
`queryKey`	מחרוזת	המפתח לקריאה מהפרמטרים של השאילתה.
`retrieveAll`	boolean	האם לאחזר את כל הערכים.

לדוגמה, אם כתובת ה-URL הנוכחית היא https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, אז:

getQueryParameters('var') == 'foo'
getQueryParameters('var', false) == 'foo'
getQueryParameters('var', null) == 'foo'
getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

הרשאות משויכות

ב-get_url צריך לאפשר את הרכיב query ולציין את queryKey במפתחות השאילתה המותרים (או לאפשר כל מפתח שאילתה).

`getReferrerQueryParameters`

ה-API‏ getReferrerQueryParameters פועל כמו getQueryParameters, אבל הוא פועל על כתובת ה-URL של מקור ההפניה (referrer) במקום על כתובת ה-URL הנוכחית. הפונקציה מחזירה את הפרמטר הראשון או את כל הפרמטרים של מזהה המפנה שצוין queryKey. הפונקציה מחזירה את הערך הראשון מתוך queryKey או מערך של ערכים מתוך queryKey.

תחביר

getReferrerQueryParameters(queryKey[, retrieveAll])

פרמטרים

פרמטר	סוג	תיאור
`queryKey`	מחרוזת	המפתח לקריאה מהפרמטרים של השאילתה.
`retrieveAll`	boolean	האם לאחזר את כל הערכים.

לדוגמה, אם כתובת ה-URL של מקור התנועה היא https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, אז:

getReferrerQueryParameters('var') == 'foo'
getReferrerQueryParameters('var', false) == 'foo'
getReferrerQueryParameters('var', null) == 'foo'
getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

הרשאות משויכות

הערך של get_referrer צריך לאפשר את הרכיב query, ולציין את queryKey במפתחות השאילתה המותרים (או לאפשר כל מפתח שאילתה).

`getReferrerUrl`

בהינתן סוג רכיב, ה-API קורא את אובייקט המסמך של מקור התנועה ומחזיר מחרוזת שמייצגת חלק ממקור התנועה. אם לא מציינים רכיב, מוחזרת כתובת ה-URL המלאה של מקור ההפניה.

תחביר

getReferrerUrl([component])

פרמטרים

פרמטר	סוג	תיאור
`component`	מחרוזת	הרכיב שיוחזר מכתובת ה-URL. יכול להיות אחד מהערכים הבאים: `protocol`, ‏ `host`, ‏ `port`, `path`, ‏ `query`, ‏ `extension`. אם `component` הוא `undefined`,‏ `null` או שלא תואם לאחד מהרכיבים האלה, כתובת ה-URL כולה תוחזר.

הרשאות משויכות

הערך של get_referrer צריך לאפשר את הרכיב query, ולציין את queryKey במפתחות השאילתה המותרים (או לאפשר כל מפתח שאילתה).

`getTimestamp`

הוצא משימוש. מומלץ להשתמש ב-getTimestampMillis.

הפונקציה מחזירה מספר שמייצג את השעה הנוכחית באלפיות השנייה מאז ראשית הזמן של Unix, כפי שמוחזר על ידי Date.now().

תחביר

getTimestamp();

הרשאות משויכות

ללא.

`getTimestampMillis`

הפונקציה מחזירה מספר שמייצג את השעה הנוכחית באלפיות השנייה מאז ראשית הזמן של Unix, כפי שמוחזר על ידי Date.now().

תחביר

getTimestampMillis();

הרשאות משויכות

ללא.

`getType`

הפונקציה מחזירה מחרוזת שמתארת את סוג הערך שצוין. בניגוד ל-typeof,‏ getType מבחין בין array לבין object.

תחביר

getType(data.someField)

הערות

בטבלה הבאה מפורטות המחרוזות שמוחזרות לכל ערך קלט.

ערך קלט	תוצאה
`undefined`	'undefined'
`null`	'null'
`true`	'boolean'
`12`	'number'
`'string'`	'string'
`{ a: 3 }`	'object'
`[ 1, 3 ]`	'array'
`(x) => x + 1`	‫'function'

הרשאות משויכות

ללא.

`getUrl`

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

תחביר

getUrl(component)

פרמטרים

פרמטר	סוג	תיאור
`component`	מחרוזת	הרכיב שיוחזר מכתובת ה-URL. הערך חייב להיות אחד מהערכים הבאים: `protocol`, `host`, `port`, `path`, `query`, `extension`, `fragment`. אם הרכיב הוא `undefined`,‏ `null` או לא תואם לאחד מהרכיבים האלה, יוחזר הערך המלא של `href`.

הרשאות משויכות

get_url

`gtagSet`

הפקודה gtag set נדחפת אל שכבת הנתונים כדי שהמערכת תעבד אותה בהקדם האפשרי אחרי שהאירוע הנוכחי ותגים שהופעלו על ידו יסיימו את העיבוד (או אחרי שיגיע הזמן הקצוב לתג). העדכון יעבור עיבוד במאגר הזה לפני כל הפריטים שמוצבים בתור בשכבת הנתונים.

לדוגמה, אם הפונקציה מופעלת על ידי תג שמופעל על Consent Initialization (הפעלת הגדרות הסכמה), העדכון יוחל לפני שהאירוע Initialization (הפעלה) יעובד. לדוגמה, אם המדיניות ads_data_redaction מוגדרת לערך true או false, או אם המדיניות url_passthrough מוגדרת לערך true או false.

לדוגמה:

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

תחביר

gtagSet(object)

פרמטרים

פרמטר	סוג	תיאור
`Object`	object	אובייקט שמעדכן את המצב הגלובלי של המאפיינים שהוא מכיל.

הרשאות משויכות

‫write_data_layer בודקת את הרשאת הכתיבה ל-dataLayer עבור כל המפתחות שצוינו. אם הקלט של gtagSet הוא אובייקט פשוט, ה-API יבדוק אם יש הרשאת כתיבה לכל המפתחות המפושטים בתוך האובייקט הזה, למשל, עבור gtagSet({foo: {bar: 'baz'}}), ה-API יבדוק אם יש הרשאת כתיבה ל-foo.bar.

אם הקלט של gtagSet הוא מפתח וערך אובייקט כלשהו שאינו בפורמט רגיל, ה-API יבדוק אם יש הרשאת כתיבה למפתח הזה. לדוגמה, עבור gtagSet('abc', true) , ה-API יבדוק אם יש הרשאת כתיבה ל-'abc'.

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

`injectHiddenIframe`

הוספת iframe בלתי נראה לדף.

הקריאות החוזרות ניתנות כמופעי פונקציות, והן עטופות בפונקציות JavaScript שקוראות דרכן.

תחביר

injectHiddenIframe(url, onSuccess)

פרמטרים

פרמטר	סוג	תיאור
`url`	מחרוזת	כתובת ה-URL שתשמש כערך של מאפיין `src` של ה-iframe.
`onSuccess`	function	מופעל כשהפריים נטען בהצלחה.

הרשאות משויכות

inject_hidden_iframe

`injectScript`

הפונקציה מוסיפה תג script לדף כדי לטעון את כתובת ה-URL שצוינה באופן אסינכרוני. הקריאות החוזרות ניתנות כמופעי פונקציות, והן עטופות בפונקציות JavaScript שקוראות דרכן.

תחביר

injectScript(url, onSuccess, onFailure[, cacheToken])

פרמטרים

פרמטר	סוג	תיאור
`url`	מחרוזת	הכתובת של הסקריפט שרוצים להוסיף.
`onSuccess`	function	מופעל כשהסקריפט נטען בהצלחה.
`onFailure`	function	הפונקציה מופעלת כשהסקריפט לא נטען.
`cacheToken`	מחרוזת	מחרוזת אופציונלית שמשמשת לציון כתובת ה-URL שצריך לשמור במטמון. אם מציינים את הערך הזה, נוצר רק רכיב script אחד כדי לבקש את ה-JavaScript. כל ניסיון נוסף לטעינה יגרום להוספת השיטות `onSuccess` ו-`onFailure` לתור עד שהסקריפט ייטען.

הרשאות משויכות

inject_script

`isConsentGranted`

הפונקציה מחזירה את הערך True אם סוג ההסכמה שצוין ניתן.

ההסכמה לסוג מסוים של הסכמה נחשבת כהסכמה שניתנה אם סוג ההסכמה הוגדר כ 'ניתנה' או שלא הוגדר בכלל. אם סוג ההסכמה מוגדר לערך אחר, הוא ייחשב כלא ניתן.

בממשק המשתמש של Tag Manager, בהגדרות התגים, תהיה אפשרות להפעלה תמיד. אם תג שהאפשרות always fire (הפעלה תמיד) מופעלת בו משתמש ב-API הזה, ההסכמה נחשבת כהסכמה שניתנה והערך true יוחזר, ללא קשר למצב ההסכמה בפועל.

דוגמה:

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

תחביר

isConsentGranted(consentType)

פרמטרים

פרמטר	סוג	תיאור
`consentType`	מחרוזת	סוג ההסכמה שרוצים לבדוק את המצב שלה.

הרשאות משויכות

הרשאה access_consent עם גישת קריאה לסוג ההסכמה.

`JSON`

מחזירה אובייקט שמספק פונקציות JSON.

הפונקציה parse() מנתחת מחרוזת JSON כדי ליצור את הערך או האובייקט שמתוארים במחרוזת. אם אי אפשר לנתח את הערך (למשל, אם הוא לא בפורמט JSON תקין), הפונקציה תחזיר undefined. אם ערך הקלט הוא לא מחרוזת, הקלט יומר למחרוזת.

הפונקציה stringify() ממירה את הקלט למחרוזת JSON. אם אי אפשר לנתח את הערך (למשל, אם האובייקט מכיל מחזור), השיטה תחזיר undefined.

תחביר

JSON.parse(stringInput)
JSON.stringify(value);

פרמטרים

JSON.parse

פרמטר	סוג	תיאור
stringInput	כל	הערך להמרה. אם הערך הוא לא מחרוזת, הקלט יומר למחרוזת.

JSON.stringify

פרמטר	סוג	תיאור
ערך	כל	הערך להמרה.

דוגמה

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

`localStorage`

הפונקציה מחזירה אובייקט עם שיטות לגישה לאחסון מקומי.

תחביר

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

הרשאות משויכות

access_local_storage

דוגמה

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

`logToConsole`

רישום הארגומנטים במסוף הדפדפן.

תחביר

logToConsole(obj1 [, obj2,... objN])

פרמטרים

פרמטר	סוג	תיאור
`obj1 [, obj2,... objN]`	כל	ארגומנטים

הרשאות משויכות

logging

`makeInteger`

הפונקציה ממירה את הערך הנתון למספר (מספר שלם).

תחביר

makeInteger(value)

פרמטרים

פרמטר	סוג	תיאור
`value`	כל	הערך להמרה.

הרשאות משויכות

ללא.

`makeNumber`

הפונקציה ממירה את הערך הנתון למספר.

תחביר

makeNumber(value)

פרמטרים

פרמטר	סוג	תיאור
`value`	כל	הערך להמרה.

הרשאות משויכות

ללא.

`makeString`

הפונקציה מחזירה את הערך הנתון כמחרוזת.

תחביר

makeString(value)

פרמטרים

פרמטר	סוג	תיאור
`value`	כל	הערך להמרה.

הרשאות משויכות

ללא.

`makeTableMap`

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

לדוגמה, הפונקציה הזו יכולה להמיר אובייקט של טבלה:

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

לתוך מפה:

{
  'k1': 'v1',
  'k2': 'v2'
}

מחזירה אובייקט: האובייקט Map שהומר אם נוספו לו צמדי מפתח/ערך, או null אחרת.

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName)

פרמטרים

פרמטר	סוג	תיאור
`tableObj`	רשימה	אובייקט הטבלה שרוצים להמיר. זו רשימה של מפות שבה כל `Map` מייצג שורה בטבלה. כל שם מאפיין באובייקט שורה הוא שם העמודה, וערך המאפיין הוא ערך העמודה בשורה.
`keyColumnName`	מחרוזת	שם העמודה שהערכים שלה יהפכו למפתחות ב-`Map` שהומר.
`valueColumnName`	מחרוזת	שם העמודה שהערכים שלה יהפכו לערכים בעמודה `Map` אחרי ההמרה.

הרשאות משויכות

ללא.

`Math`

אובייקט שמספק פונקציות Math.

תחביר

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

פרמטרים

הפרמטרים של פונקציות מתמטיות מומרים למספרים.

הרשאות משויכות

ללא.

`Object`

מחזירה אובייקט שמספק שיטות Object.

ה-method keys() מספק את ההתנהגות של Object.keys() בספרייה הרגילה. הפונקציה מחזירה מערך של שמות מאפיינים שניתנים לספירה של אובייקט נתון, באותו סדר שבו לולאת for...in... תחזיר אותם. אם ערך הקלט הוא לא אובייקט, הוא יומר לאובייקט.

השיטה values() מספקת את ההתנהגות של Object.values() בספרייה הרגילה. הפונקציה מחזירה מערך של ערכי מאפיינים שניתנים לספירה של אובייקט נתון, באותו סדר שבו לולאת for...in... תחזיר אותם. אם ערך הקלט הוא לא אובייקט, הוא יומר לאובייקט.

ה-method‏ entries() מספק את ההתנהגות של Object.entries() בספרייה הרגילה. הפונקציה מחזירה מערך של זוגות של מאפיינים בני מנייה של אובייקט נתון, באותו סדר שבו לולאת for...in... תחזיר אותם.[key, value] אם ערך הקלט הוא לא אובייקט, הוא יומר לאובייקט.

ה-method‏ freeze() מספקת את ההתנהגות של Object.freeze() בספרייה הרגילה. אי אפשר לשנות אובייקט קפוא. הקפאה של אובייקט מונעת הוספה של מאפיינים חדשים, הסרה של מאפיינים קיימים ושינוי של ערכי מאפיינים קיימים. ‫freeze() מחזירה את אותו אובייקט שהועבר. ארגומנט פרימיטיבי או ארגומנט מסוג null יטופל כאילו הוא אובייקט קפוא, ויוחזר.

השיטה delete() מספקת את ההתנהגות של אופרטור המחיקה בספרייה הרגילה. היא מסירה את המפתח הנתון מהאובייקט, אלא אם האובייקט קפוא. בדומה לאופרטור delete בספרייה הרגילה, הפונקציה מחזירה true אם ערך הקלט הראשון (objectInput) הוא אובייקט שלא הוקפא, גם אם ערך הקלט השני (keyToDelete) מציין מפתח שלא קיים. בכל המקרים האחרים, הפונקציה מחזירה false. עם זאת, יש הבדלים בין האופרטור הזה לבין אופרטור המחיקה בספרייה הרגילה:

‫keyToDelete לא יכול להיות מחרוזת עם נקודות שמציינת מפתח מקונן.
אי אפשר להשתמש ב-delete() כדי להסיר רכיבים ממערך.
אי אפשר להשתמש ב-delete() כדי להסיר נכסים מההיקף הגלובלי.

תחביר

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

פרמטרים

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

פרמטר	סוג	תיאור
objectInput	כל	האובייקט להקפאה. אם הקלט הוא לא אובייקט, הוא ייחשב כאובייקט קפוא.

Object.delete

פרמטר	סוג	תיאור
objectInput	כל	האובייקט שמכיל את המפתח שרוצים למחוק.
keyToDelete	מחרוזת	המפתח ברמה העליונה שרוצים למחוק.

דוגמה

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

`parseUrl`

מחזירה אובייקט שמכיל את כל חלקי הרכיבים של כתובת URL נתונה, בדומה לאובייקט URL.

ה-API הזה יחזיר undefined לכל כתובת URL לא תקינה. אם כתובות ה-URL בפורמט תקין, השדות שלא מופיעים במחרוזת כתובת ה-URL יקבלו ערך של מחרוזת ריקה, או במקרה של searchParams, אובייקט ריק.

האובייקט שמוחזר יכלול את השדות הבאים:

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

דוגמה

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

תחביר

parseUrl(url);

פרמטרים

פרמטר	סוג	תיאור
`url`	מחרוזת	כתובת ה-URL המלאה שתנותח.

הרשאות משויכות

ללא.

`queryPermission`

חיפוש הרשאות מותרות והרשאות מצומצמות. הפונקציה מחזירה ערך בוליאני: true אם ניתנה הרשאה, false אחרת.

תחביר

queryPermission(permission, functionArgs*)

פרמטרים

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

ארגומנטים של פונקציות

‫sendPixel, injectScript, injectHiddenIframe: הפרמטר השני צריך להיות מחרוזת של כתובת URL.

‫writeGlobals, readGlobals: הפרמטר השני צריך להיות המפתח שנכתב או נקרא.

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

if (queryPermission('readUrl','port')) {
  // read the port
}

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

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

הרשאות משויכות

ללא.

`readAnalyticsStorage`

מאחזר את הנתונים שמאוחסנים לצורך ניתוח ומחזיר אובייקט עם client_id ו-sessions.

‫client_id: מחרוזת שמייצגת את מזהה הלקוח שמשמש לניתוח נתונים.
‫sessions: מערך של אובייקטים שמכילים מידע על סשנים נוכחיים. כל אובייקט כולל:
- ‫measurement_id: מחרוזת שמייצגת את מזהה המדידה של יעד Analytics.
- ‫session_id: מחרוזת שמייצגת את חותמת הזמן שמזהה את הסשן הנוכחי.
- ‫session_number: מספר שמייצג את מספר הסשנים שהמשתמש התחיל עד לסשן הנוכחי.

תחביר

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

פרמטרים

פרמטר	סוג	תיאור
`cookieOptions`	object	אופציונלי אפשרויות לקריאת קובצי Cookie עם `cookie_prefix`, `cookie_domain` או `cookie_path` ספציפיים.

הרשאות משויכות

read_analytics_storage

דוגמה

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

`readCharacterSet`

הפונקציה מחזירה את הערך של document.characterSet.

תחביר

readCharacterSet()

פרמטרים

ללא.

הרשאות משויכות

read_character_set

`readTitle`

הפונקציה מחזירה את הערך של document.title.

תחביר

readTitle()

פרמטרים

ללא.

הרשאות משויכות

read_title

`require`

מייבאת פונקציה מובנית לפי שם. הפונקציה מחזירה פונקציה או אובייקט שאפשר לקרוא להם מהתוכנית. הפונקציה מחזירה undefined אם הדפדפן לא תומך בפונקציה המובנית.

תחביר

require(name)

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	השם של הפונקציה לייבוא.

דוגמה

const getUrl = require('getUrl');
const url = getUrl();

הרשאות משויכות

ללא.

`sendPixel`

שליחת בקשת GET לנקודת קצה (endpoint) של כתובת URL שצוינה.

תחביר

sendPixel(url, onSuccess, onFailure)

פרמטרים

פרמטר	סוג	תיאור
`url`	מחרוזת	לאן לשלוח את הפיקסל.
`onSuccess`	function	מופעל כשהפיקסל נטען בהצלחה. הערה: גם אם הבקשה נשלחת בהצלחה, יכול להיות שהדפדפנים ידרשו תגובה של תמונה תקינה כדי להפעיל את onSuccess.
`onFailure`	function	הפונקציה מופעלת אם טעינת הפיקסל נכשלת. הערה: גם אם הבקשה נשלחת בהצלחה, יכול להיות שהפונקציה onFailure תופעל אם השרת לא יחזיר תגובה תקפה של תמונה.

הרשאות משויכות

send_pixel

`setCookie`

הגדרה או מחיקה של קובץ ה-Cookie עם השם, הערך והאפשרויות שצוינו.

תחביר

setCookie(name, value[, options, encode])

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	השם של קובץ ה-Cookie.
`value`	מחרוזת	הערך של קובץ ה-Cookie.
`options`	object	מציין את המאפיינים Domain,‏ Path,‏ Expires,‏ Max-Age,‏ Secure ו-SameSite. (ראו אפשרויות בהמשך).
`encode`	boolean	ההגדרה הזו קובעת אם הערך של קובץ ה-Cookie יוצפן באמצעות `encodeURIComponent()` של JavaScript. ברירת המחדל היא `true`.

אפשרויות

דומיין: מוגדר על ידי המאפיין options['domain'], אם הוא קיים. כדי לנסות לכתוב את קובץ ה-Cookie באמצעות הדומיין הרחב ביותר האפשרי, על סמך מיקום המסמך, צריך להגדיר את הערך הזה ל-'auto'. אם זה לא יצליח, המערכת תנסה להשתמש בתת-דומיינים מצומצמים יותר. אם כל אלה ייכשלו, המערכת תנסה לכתוב את קובץ ה-Cookie ללא דומיין. אם לא מוגדר ערך, המערכת תנסה לכתוב את קובץ ה-Cookie בלי לציין דומיין. הערה: כשקובץ Cookie ללא דומיין מוגדר נכתב ל-document.cookie, סוכן המשתמש יגדיר כברירת מחדל את הדומיין של קובץ ה-Cookie למארח של המיקום הנוכחי של המסמך.
נתיב: מוגדר על ידי options['path'], אם קיים. כשקובץ Cookie ללא נתיב שצוין נכתב אל document.cookie, סוכן המשתמש יגדיר כברירת מחדל את הנתיב של קובץ ה-Cookie לנתיב של המיקום הנוכחי של המסמך.
Max-Age: מוגדר על ידי options['max-age'], אם הוא קיים.
תאריך תפוגה: מוגדר על ידי options['expires'], אם קיים. אם השדה הזה קיים, הוא חייב להיות מחרוזת תאריך בפורמט UTC. אפשר להשתמש ב-Date.toUTCString() כדי לעצב את Date עבור הפרמטר הזה.
מאובטח: מוגדר על ידי options['secure'], אם קיים.
‫SameSite: מוגדר על ידי options['samesite'], אם הוא קיים.

הרשאות משויכות

set_cookies

`setDefaultConsentState`

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

דוגמה:

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

תחביר

setDefaultConsentState(consentSettings)

פרמטרים

פרמטר	סוג	תיאור
`consentSettings`	object	אובייקט שמגדיר את מצב ברירת המחדל לסוגי ההסכמה שצוינו.

האובייקט consentSettings הוא מיפוי של מחרוזות שרירותיות של סוגי הסכמה לאחד מהערכים 'granted' או 'denied'. אפשר להזין בו את הערכים הבאים:

שם מפתח	סוג	תיאור
`consentType`	מחרוזת	הערך של כל סוג הסכמה יכול להיות 'granted' (אושרה) או 'denied' (נדחתה). כל ערך אחר מלבד 'granted' ייחשב כ'denied'. הגדרת הערך כ-undefined לא תשפיע על הערך הקודם שלו.
`region`	מערך	מערך אופציונלי של קודי אזורים שמציין לאילו אזורים חלות הגדרות ההסכמה. קודי האזורים מופיעים בפורמט ISO 3166-2, עם מדינה ו/או חלוקות משנה.
`wait_for_update`	number	מציינת ערך באלפיות שנייה כדי לקבוע כמה זמן להמתין לפני שהנתונים יישלחו. השימוש ב-API הזה מיועד לכלים לניהול הסכמה שנטענים באופן אסינכרוני.

הרשאות משויכות

הרשאה access_consent עם גישת כתיבה לכל סוגי ההסכמה באובייקט consentSettings.

`setInWindow`

מגדירה את הערך הנתון ב-window במפתח הנתון. כברירת מחדל, השיטה הזו לא תגדיר את הערך ב-window אם כבר קיים ערך. ‫Set overrideExisting to true כדי להגדיר את הערך ב-window בלי קשר לנוכחות של ערך קיים. הפונקציה מחזירה ערך בוליאני: true אם הערך הוגדר בהצלחה, ו-false אחרת.

תחביר

setInWindow(key, value, overrideExisting)

פרמטרים

פרמטר	סוג	תיאור
`key`	מחרוזת	המפתח ב-`window` שבו צריך להציב את הערך.
`value`	*	הערך שצריך להגדיר ב-`window`.
`overrideExisting`	boolean	הדגל שמציין שהערך צריך להיות מוגדר ב-`window`, גם אם יש שם ערך וגם אם לא.

הרשאות משויכות

access_globals

`sha256`

מחשבת את הגיבוב SHA-256 של הקלט ומפעילה קריאה חוזרת עם הגיבוב בקידוד base64, אלא אם אובייקט options מציין קידוד פלט שונה.

דוגמה:

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

תחביר

sha256(input, onSuccess, onFailure = undefined, options = undefined)

פרמטרים

פרמטר	סוג	תיאור
`input`	מחרוזת	המחרוזת שעבורה צריך לחשב את הגיבוב.
`onSuccess`	function	הפונקציה נקראת עם התקציר שמתקבל, בקידוד base64, אלא אם אובייקט `options` מציין קידוד פלט שונה.
`onFailure`	function	הפונקציה מופעלת אם מתרחשת שגיאה במהלך חישוב הגיבוב, או אם בדפדפן אין תמיכה מובנית ב-SHA256. הקריאה החוזרת מתבצעת עם אובייקט שמכיל את שם השגיאה וההודעה.
`options`	object	אובייקט אפשרויות אופציונלי לציון קידוד הפלט. אם מציינים את האובייקט, הוא צריך להכיל את המפתח `outputEncoding` עם ערך שהוא אחד מהערכים `base64` או `hex`.

הרשאות משויכות

ללא.

`templateStorage`

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

תחביר

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

// Deletes all stored values for the template.
templateStorage.clear();

הרשאות משויכות

access_template_storage

דוגמה

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

`toBase64`

‫toBase64 API מאפשר לקודד מחרוזת לייצוג base64.

תחביר

toBase64(input)

פרמטרים

פרמטר	סוג	תיאור
`input`	מחרוזת	מחרוזת לקידוד.

דוגמה

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

הרשאות משויכות

ללא

`updateConsentState`

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

דוגמה:

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

תחביר

updateConsentState(consentSettings)

פרמטרים

פרמטר	סוג	תיאור
`consentSettings`	object	אובייקט שמעדכן את המצב של סוגי ההסכמה שצוינו.

שם מפתח	סוג	תיאור
`consentType`	מחרוזת	הערך של כל סוג הסכמה יכול להיות 'אושרה' או 'נדחתה'. כל ערך אחר מלבד 'granted' ייחשב כ 'denied'. הגדרת הערך כ-'undefined' לא תשפיע על הערך הקודם שלו.

הרשאות משויכות

הרשאה access_consent עם גישת כתיבה לכל סוגי ההסכמה באובייקט consentSettings.

ממשקי API לבדיקה

ממשקי ה-API האלה פועלים עם בדיקות JavaScript בארגז חול כדי ליצור בדיקות לתבניות מותאמות אישית ב-Google Tag Manager. לא צריך הצהרה לגבי ממשקי ה-API האלה לבדיקה.require() מידע נוסף על בדיקות של תבניות בהתאמה אישית

`assertApi`

מחזירה אובייקט התאמה שאפשר להשתמש בו כדי ליצור הצהרות בצורה שוטפת לגבי ה-API שצוין.

תחביר

assertApi(apiName)

פרמטרים

פרמטר	סוג	תיאור
`apiName`	מחרוזת	שם ה-API שרוצים לבדוק. זו אותה מחרוזת שמועברת אל `require()`.

Matchers

Subject.wasCalled()
Subject.wasNotCalled()
Subject.wasCalledWith(...expected)
Subject.wasNotCalledWith(...expected)

דוגמאות

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

`assertThat`

ה-API של assertThat מבוסס על ספריית [Truth] של Google. הפונקציה מחזירה אובייקט שאפשר להשתמש בו כדי ליצור הצהרות בצורה שוטפת לגבי הערך של נושא. אם טענת אימות תיכשל, הבדיקה תיפסק באופן מיידי והיא תסומן כנכשלת. עם זאת, כישלון בבדיקה אחת לא ישפיע על תרחישי בדיקה אחרים.

תחביר

assertThat(actual, opt_message)

פרמטרים

פרמטר	סוג	תיאור
`actual`	כל	הערך שבו יש להשתמש בבדיקות השוטפות.
`opt_message`	מחרוזת	הודעה אופציונלית להדפסה אם הטענה נכשלת.

Matchers

Matcher	תיאור
`isUndefined()`	קובע שהנושא הוא `undefined`.
`isDefined()`	מציין שהנושא הוא לא `undefined`.
`isNull()`	קובע שהנושא הוא `null`.
`isNotNull()`	מציין שהנושא הוא לא `null`.
`isFalse()`	קובע שהנושא הוא `false`.
`isTrue()`	קובע שהנושא הוא `true`.
`isFalsy()`	בודקת שהנושא הוא ערך שהוא False. הערכים שהם False הם: `undefined`,‏ `null`,‏ `false`, `NaN`,‏ 0 ו-'' (מחרוזת ריקה).
`isTruthy()`	הטענה שהנושא הוא ערך שהוא true. הערכים שהם False הם: `undefined`,‏ `null`,‏ `false`, `NaN`,‏ 0 ו-'' (מחרוזת ריקה).
`isNaN()`	בודקת אם הנושא הוא הערך NaN.
`isNotNaN()`	הפונקציה קובעת שהנושא הוא כל ערך חוץ מ-NaN.
`isInfinity()`	הפונקציה קובעת שהנושא הוא אינסוף חיובי או שלילי.
`isNotInfinity()`	הפונקציה קובעת שהנושא הוא כל ערך חוץ מאינסוף חיובי או שלילי.
`isEqualTo(expected)`	הפונקציה בודקת אם הנושא שווה לערך הנתון. זו השוואת ערכים, לא השוואת הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`isNotEqualTo(expected)`	הפונקציה בודקת אם הנושא לא שווה לערך שצוין. זו השוואה בין ערכים, ולא השוואה בין הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`isAnyOf(...expected)`	הפונקציה בודקת אם הנושא שווה לאחד מהערכים שצוינו. זו השוואה בין ערכים, ולא השוואה בין הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`isNoneOf(...expected)`	הפונקציה בודקת אם הנושא לא שווה לאף אחד מהערכים שצוינו. זו השוואת ערכים, לא השוואת הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`isStrictlyEqualTo(expected)`	הטענה היא שהנושא שווה בדיוק (`===`) לערך שצוין.
`isNotStrictlyEqualTo(expected)`	הפונקציה בודקת אם הנושא לא שווה בדיוק (`!==`) לערך שצוין.
`isGreaterThan(expected)`	הטענה היא שהנושא גדול יותר (`>`) מהערך הנתון בהשוואה מסודרת.
`isGreaterThanOrEqualTo(expected)`	הפונקציה קובעת שהנושא גדול מהערך הנתון או שווה לו (`>=`) בהשוואה מסודרת.
`isLessThan(expected)`	הטענה היא שהנושא קטן מ- (`<`) הערך הנתון בהשוואה מסודרת.
`isLessThanOrEqualTo(expected)`	הפונקציה בודקת אם הנושא קטן מהערך הנתון או שווה לו (`<=`) בהשוואה מסודרת.
`contains(...expected)`	בודקת שהנושא הוא מערך או מחרוזת שמכילים את כל הערכים הנתונים בכל סדר. זו השוואת ערכים, לא השוואת הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`doesNotContain(...expected)`	הפונקציה בודקת אם הנושא הוא מערך או מחרוזת שלא מכילים אף אחד מהערכים שצוינו. זו השוואה בין ערכים, ולא השוואה בין הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`containsExactly(...expected)`	הפונקציה בודקת שהנושא הוא מערך שמכיל את כל הערכים שצוינו בכל סדר, ושאין בו ערכים אחרים. זו השוואת ערכים, ולא השוואת הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`doesNotContainExactly(...expected)`	בודקת שהנושא הוא מערך שמכיל קבוצה שונה של ערכים מהערכים שצוינו, בכל סדר. זו השוואת ערכים, ולא השוואת הפניות. התוכן של אובייקטים ומערכים מושווה באופן רקורסיבי.
`hasLength(expected)`	בודקת שהנושא הוא מערך או מחרוזת באורך הנתון. הטענה תמיד תיכשל אם הערך הוא לא מערך או מחרוזת.
`isEmpty()`	בודקת שהנושא הוא מערך או מחרוזת ריקים (האורך הוא 0). הטענה תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
`isNotEmpty()`	בודק שהנושא הוא מערך או מחרוזת שלא ריקים (האורך > 0). הטענה תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
`isArray()`	הטענה שהסוג של הנושא הוא מערך.
`isBoolean()`	בודקת שהסוג של הנושא הוא בוליאני.
`isFunction()`	הפונקציה קובעת שהסוג של הנושא הוא פונקציה.
`isNumber()`	הפונקציה בודקת אם סוג הנושא הוא מספר.
`isObject()`	הטענה היא שהסוג של הנושא הוא אובייקט.
`isString()`	הטענה היא שסוג הנושא הוא מחרוזת.

דוגמאות

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

`fail`

מפסיקה מיד את הבדיקה הנוכחית ומדפיסה את ההודעה שצוינה, אם יש כזו.

תחביר

fail(opt_message);

פרמטרים

פרמטר	סוג	תיאור
`opt_message`	מחרוזת	טקסט אופציונלי של הודעת שגיאה.

דוגמה

fail('This test has failed.');

`mock`

‫mock API מאפשר לכם לשנות את ההתנהגות של Sandboxed APIs. אפשר להשתמש ב-API המדומה בקוד תבנית, אבל הוא פועל רק במצב בדיקה. ההדמיות מאופסות לפני כל הרצה של בדיקה.

תחביר

mock(apiName, returnValue);

פרמטרים

פרמטר	סוג	תיאור
`apiName`	מחרוזת	השם של ה-API לסימולציה. זו אותה מחרוזת שמועברת אל `require()`
`returnValue`	כל	הערך שיוחזר עבור ה-API או פונקציה שנקראת במקום ה-API. אם `returnValue` היא פונקציה, המערכת קוראת לפונקציה הזו במקום ל-Sandboxed API. אם `returnValue` הוא כל דבר אחר מלבד פונקציה, המערכת מחזירה את הערך הזה במקום את Sandboxed API.

דוגמאות

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

`mockObject`

‫mockObject API מאפשר לכם לשנות את ההתנהגות של ממשקי Sandboxed API שמחזירים אובייקט. אפשר להשתמש ב-API בקוד תבנית, אבל הוא פועל רק במצב בדיקה. ההדמיות מאופסות לפני כל הרצה של בדיקה.

תחביר

mockObject(apiName, objectMock);

פרמטרים

פרמטר	סוג	תיאור
`apiName`	מחרוזת	השם של ה-API לסימולציה. זו אותה מחרוזת שמועברת אל `require()`
`objectMock`	object	הערך שיוחזר עבור ה-API או פונקציה שנקראת במקום ה-API. חייב להיות אובייקט.

דוגמאות

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

`runCode`

מריץ את הקוד של התבנית, כלומר את התוכן של הכרטיסייה קוד, בסביבת הבדיקה הנוכחית עם אובייקט נתוני קלט נתון.

תחביר

runCode(data)

פרמטרים

פרמטר	סוג	תיאור
`data`	object	אובייקט הנתונים שישמש בבדיקה.

ערך מוחזר

הפונקציה מחזירה את הערך של משתנה בתבניות של משתנים, ומחזירה undefined בכל סוגי התבניות האחרים.

דוגמה

runCode({field1: 123, field2: 'value'});

ממשקי API של תבניות מותאמות אישית קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

ממשקי API מרכזיים

addConsentListener

addEventCallback

aliasInWindow

callInWindow

callLater

copyFromDataLayer

copyFromWindow

createArgumentsQueue

createQueue

decodeUri

decodeUriComponent

encodeUri

encodeUriComponent

fromBase64

generateRandom

getContainerVersion

getCookieValues

getQueryParameters

getReferrerQueryParameters

getReferrerUrl

getTimestamp

getTimestampMillis

getType

getUrl

gtagSet

injectHiddenIframe

injectScript

isConsentGranted

JSON

localStorage

logToConsole

makeInteger

makeNumber

makeString

makeTableMap

Math

Object

parseUrl

queryPermission

readAnalyticsStorage

readCharacterSet

readTitle

require

sendPixel

setCookie

setDefaultConsentState

setInWindow

sha256

templateStorage

toBase64

updateConsentState

ממשקי API לבדיקה

assertApi

assertThat

fail

mock

mockObject

runCode

ממשקי API של תבניות מותאמות אישית

`addConsentListener`

`addEventCallback`

`aliasInWindow`

`callInWindow`

`callLater`

`copyFromDataLayer`

`copyFromWindow`

`createArgumentsQueue`

`createQueue`

`decodeUri`

`decodeUriComponent`

`encodeUri`

`encodeUriComponent`

`fromBase64`

`generateRandom`

`getContainerVersion`

`getCookieValues`

`getQueryParameters`

`getReferrerQueryParameters`

`getReferrerUrl`

`getTimestamp`

`getTimestampMillis`

`getType`

`getUrl`

`gtagSet`

`injectHiddenIframe`

`injectScript`

`isConsentGranted`

`JSON`

`localStorage`

`logToConsole`

`makeInteger`

`makeNumber`

`makeString`

`makeTableMap`

`Math`

`Object`

`parseUrl`

`queryPermission`

`readAnalyticsStorage`

`readCharacterSet`

`readTitle`

`require`

`sendPixel`

`setCookie`

`setDefaultConsentState`

`setInWindow`

`sha256`

`templateStorage`

`toBase64`

`updateConsentState`

`assertApi`

`assertThat`

`fail`

`mock`

`mockObject`

`runCode`