דף זה תורגם על ידי Cloud Translation API.

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

ממשקי API ליבה

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

const myAPI = require('myAPI');

`addConsentListener`

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

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

דוגמה:

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`	string	סוג ההסכמה שעבורו רוצים לשמוע על שינויים במצב.
`listener`	function	הפונקציה שתופעל כשהמצב של סוג ההסכמה שצוין ישתנה.

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

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

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

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

`addEventCallback`

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

תחביר

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`

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

תחביר

aliasInWindow(toPath, fromPath)

פרמטרים

פרמטר	סוג	תיאור
`toPath`	string	נתיב שמפרידים אותו בנקודות לאובייקט `window` שאליו צריך להעתיק את הערך. כל הרכיבים בנתיב עד לרכיב האחרון חייבים להיות קיימים כבר באובייקט `window`.
`fromPath`	string	נתיב שמפריד בין הנקודות ב-`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`	string	נתיב לפונקציה ב-`window`, שמופרד בנקודות, כדי להפעיל אותה.
`args`	*	הארגומנטים שיועברו לפונקציה.

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

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

`callLater`

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

תחביר

callLater(function)

פרמטרים

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

`copyFromDataLayer`

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

תחביר

copyFromDataLayer(key[, dataLayerVersion])

פרמטרים

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

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

read_data_layer

`copyFromWindow`

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

תחביר

copyFromWindow(key)

פרמטרים

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

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

access_globals

`createArgumentsQueue`

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

יצירת פונקציה ברמת ה-global (כלומר 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`	string	הנתיב ב-`window` שבו מוגדרת הפונקציה, אם היא עדיין לא קיימת. הארגומנט הזה תומך בסימון נקודה סטנדרטי. אם הנתיב של המפתח לא קיים, מתבצעת הטלת חריגה. כלומר, אם הערך של `fnKey` הוא `'one.two'`, תופיע הודעת שגיאה.
`arrayKey`	string	הנתיב ב-`window` שבו מוגדר המערך, אם הוא עדיין לא קיים. הארגומנט הזה תומך בסימון נקודה סטנדרטי. אם הנתיב של המפתח לא קיים, מתבצעת הטלת חריגה. כלומר, אם `arrayKey` הוא `'one.two'` ואין אובייקט גלובלי בשם `'one'`, תופיע חריגה.

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

access_globals

`createQueue`

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

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

דוגמה:

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

תחביר

createQueue(arrayKey)

פרמטרים

פרמטר	סוג	תיאור
`arrayKey`	string	המפתח ב-`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`	string	URI שקודד באמצעות `encodeUri()` או באמצעים אחרים.

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

ללא.

`decodeUriComponent`

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

דוגמה:

const decode = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component)

פרמטרים

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

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

ללא.

`encodeUri`

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

דוגמה:

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

תחביר

encodeUri(uri)

פרמטרים

פרמטר	סוג	תיאור
`uri`	string	URI מלא.

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

ללא.

`encodeUriComponent`

דוגמה:

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

תחביר

encodeUriComponent(str)

פרמטרים

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

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

ללא.

`fromBase64`

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

תחביר

fromBase64(base64EncodedString)

פרמטרים

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

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא

`generateRandom`

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

תחביר

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`	string	השם של קובץ ה-cookie.
`decode`	בוליאני	קובע אם ערכי קובצי ה-Cookie יפורשו באמצעות `decodeURIComponent()` של JavaScript. ברירת המחדל היא `true`.

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

get_cookies

`getQueryParameters`

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

תחביר

getQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

תחביר

getReferrerQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

לדוגמה, אם כתובת ה-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`	string	הרכיב שצריך להחזיר מכתובת ה-URL. יכול להיות אחד מהערכים הבאים: `protocol`, `host`, `port`, `path`, `query`, `extension`. אם הערך של `component` הוא `undefined`, `null` או שהוא לא תואם לאחד מהרכיבים האלה, כתובת ה-URL כולה תוחזר.

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

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

`getTimestamp`

הוצא משימוש. עדיף להשתמש ב-getTimestampMillis.

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

תחביר

getTimestamp();

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

ללא.

`getTimestampMillis`

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

תחביר

getTimestampMillis();

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

ללא.

`getType`

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

תחביר

getType(data.someField)

הערות

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

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

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

ללא.

`getUrl`

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

תחביר

getUrl(component)

פרמטרים

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

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

get_url

`gtagSet`

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

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

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

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

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

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

`injectHiddenIframe`

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

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

תחביר

injectHiddenIframe(url, onSuccess)

פרמטרים

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

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

inject_hidden_iframe

`injectScript`

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

תחביר

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

פרמטרים

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

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

inject_script

`isConsentGranted`

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

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

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

דוגמה:

const isConsentGranted = require('isConsentGranted');

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

תחביר

isConsentGranted(consentType)

פרמטרים

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

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

הרשאת 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`

מחזירה אובייקט עם methods לגישה לאחסון מקומי.

תחביר

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]`	any	ארגומנטים

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

logging

`makeInteger`

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

תחביר

makeInteger(value)

פרמטרים

פרמטר	סוג	תיאור
`value`	any	הערך שרוצים להמיר.

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

ללא.

`makeNumber`

ממירה את הערך הנתון ל-number.

תחביר

makeNumber(value)

פרמטרים

פרמטר	סוג	תיאור
`value`	any	הערך שרוצים להמיר.

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

ללא.

`makeString`

מחזירה את הערך הנתון כ-string.

תחביר

makeString(value)

פרמטרים

פרמטר	סוג	תיאור
`value`	any	הערך שרוצים להמיר.

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

ללא.

`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`	string	שם העמודה שהערכים שלה יהפכו למפתחות ב-`Map` המומר.
`valueColumnName`	string	שם העמודה שהערכים שלה יהפכו לערכים ב-`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.

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

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

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

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

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

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

תחביר

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

פרמטרים

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

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

דוגמה

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`	string	כתובת ה-URL המלאה שתנותח.

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

ללא.

`queryPermission`

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

תחביר

queryPermission(permission, functionArgs*)

פרמטרים

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

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

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

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

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

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

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

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

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

ללא.

`readCharacterSet`

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

תחביר

readCharacterSet()

פרמטרים

ללא.

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

read_character_set

`readTitle`

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

תחביר

readTitle()

פרמטרים

ללא.

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

read_title

`require`

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

תחביר

require(name)

פרמטרים

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

דוגמה

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

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

ללא.

`sendPixel`

שליחת בקשת GET לנקודת קצה של כתובת URL שהוגדרה.

תחביר

sendPixel(url, onSuccess, onFailure)

פרמטרים

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

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

send_pixel

`setCookie`

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

תחביר

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

פרמטרים

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

אפשרויות

דומיין: מוגדר על ידי המאפיין options['domain'], אם הוא קיים. צריך להגדיר את הערך הזה ל-'auto' כדי לנסות לכתוב את קובץ ה-cookie באמצעות הדומיין הרחב ביותר האפשרי, על סמך מיקום המסמך. אם הניסיון הזה נכשל, המערכת תנסה תת-דומיינים מצומצמים יותר. אם כל הניסיונות האלה ייכשלו, המערכת תנסה לכתוב את קובץ ה-cookie ללא דומיין. אם לא מגדירים ערך, המערכת תנסה לכתוב את קובץ ה-cookie בלי לציין דומיין. הערה: כשקובץ cookie ללא דומיין מצוין נכתב ב-document.cookie, סוכן המשתמש יגדיר כברירת מחדל את הדומיין של קובץ ה-cookie למארח של מיקום המסמך הנוכחי.
Path: מוגדר על ידי options['path'], אם הוא קיים. כאשר קובץ cookie ללא נתיב מצוין נכתב ב-document.cookie, ברירת המחדל של נתיב קובץ ה-cookie תהיה הנתיב של מיקום המסמך הנוכחי.
Max-Age: מוגדר על ידי options['max-age'], אם הוא קיים.
תאריך תפוגה: מוגדר על ידי options['expires'], אם קיים. אם השדה הזה מופיע, הוא חייב להיות מחרוזת תאריך בפורמט UTC. אפשר להשתמש ב-Date.toUTCString() כדי לעצב Date לפרמטר הזה.
Secure: מוגדר על ידי 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`	string	אפשר להגדיר את הערך של כל סוג הסכמה כ-'granted' או כ-'denied'. כל ערך שאינו 'granted' ייחשב כ-'denied'. הגדרת הערך כ-undefined לא תשפיע על הערך הקודם שלו.
`region`	מערך	מערך אופציונלי של קודי אזורים שמציין את האזור שאליו חלות הגדרות ההסכמה. קודי האזורים מפורטים לפי מדינה ו/או חלוקות משנה בפורמט ISO 3166-2.
`wait_for_update`	number	מציינת ערך של אלפית שנייה כדי לקבוע את משך הזמן שיחלוף לפני שהנתונים יישלחו. משמש עם כלים להבעת הסכמה שנטענים באופן אסינכרוני.

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

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

`setInWindow`

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

תחביר

setInWindow(key, value, overrideExisting)

פרמטרים

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

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

access_globals

`sha256`

הפונקציה מחשבת את הגיבוב SHA-256 של הקלט ומפעילה קריאה חוזרת (callback) עם הגיבוב המקודד ב-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`	string	המחרוזת שעבורה מחשבים את הגיבוב.
`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`

ה-API של toBase64 מאפשר לכם לקודד מחרוזת לייצוג base64.

תחביר

toBase64(input)

פרמטרים

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

דוגמה

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`	אובייקט	אובייקט שמעדכן את המצב של סוגי ההסכמה שצוינו.

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

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

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

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

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

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

`assertApi`

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

תחביר

assertApi(apiName)

פרמטרים

פרמטר	סוג	תיאור
`apiName`	string	שם ה-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. היא מחזירה אובייקט שיכול לשמש לטעינת טענות נכונות (assertions) באופן שוטף על ערך של נושא. כשל בטענת הנכוֹנוּת יוביל להפסקה מיידית של הבדיקה ולסימון שלה כ'נכשלה'. עם זאת, כשל בבדיקה אחת לא ישפיע על תרחישי בדיקה אחרים.

תחביר

assertThat(actual, opt_message)

פרמטרים

פרמטר	סוג	תיאור
`actual`	any	הערך שישמש בבדיקות של fluent.
`opt_message`	string	הודעת ברירת מחדל להדפסה אם טענת הנכוֹנוּת נכשלת.

Matchers

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

דוגמאות

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`	string	טקסט אופציונלי של הודעת שגיאה.

דוגמה

fail('This test has failed.');

`mock`

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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

`mockObject`

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

תחביר

mockObject(apiName, objectMock);

פרמטרים

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

דוגמאות

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

`runCode`

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

תחביר

runCode(data)

פרמטרים

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

ערך המוחזר

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

דוגמה

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