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

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

תחביר

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

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

get_cookies

`getQueryParameters`

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

תחביר

getQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

תחביר

getReferrerQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

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

`getTimestamp`

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

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

תחביר

getTimestamp();

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

ללא.

`getTimestampMillis`

תחביר

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`	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`	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`	string	כתובת ה-URL שישמש כערך של המאפיין `src` של ה-iframe.
`onSuccess`	function	הקריאה מתבצעת כשהפריים נטען בהצלחה.

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

inject_hidden_iframe

`injectScript`

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

תחביר

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

פרמטרים

פרמטר	סוג	תיאור
`url`	string	הכתובת של הסקריפט שרוצים להחדיר.
`onSuccess`	function	הקריאה מתבצעת כשהסקריפט נטען בהצלחה.
`onFailure`	function	הפונקציה נקראת כשהסקריפט לא נטען.
`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	any	הערך שרוצים להמיר. אם הערך הוא לא מחרוזת, הקלט יאולץ להיות מחרוזת.

JSON.stringify

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

דוגמה

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

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

logging

`makeInteger`

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

תחביר

makeInteger(value)

פרמטרים

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

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

ללא.

`makeNumber`

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

תחביר

makeNumber(value)

פרמטרים

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

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

ללא.

`makeString`

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

תחביר

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 יטופלו כאילו הם אובייקט קפוא, והם יחזרו.

השיטה 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	any	האובייקט שרוצים להכין לו את רשימת המפתחות. אם הקלט הוא לא אובייקט, הוא יומר לאובייקט.

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

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

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

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	הקריאה מתבצעת כשהפיסקל נטען בהצלחה. הערה: גם אם הבקשה נשלחת בהצלחה, יכול להיות שבדפדפנים תידרש תגובה תקינה של תמונה כדי להפעיל את onSuccess.
`onFailure`	function	הקריאה מתבצעת כשהפיxel לא נטען. הערה: גם אם הבקשה נשלחת בהצלחה, יכול להיות שהפונקציה 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'], אם הוא קיים.
Expires: מוגדר על ידי 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 במפתח הנתון. כברירת מחדל, השיטה הזו לא תגדיר את הערך ב-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. פונקציית ה-callback תופעל עם אובייקט שמכיל את שם השגיאה ואת ההודעה.
`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`	object	אובייקט שמעדכן את המצב של סוגי ההסכמה שצוינו.

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

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

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

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

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

`assertApi`

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

תחביר

assertThat(actual, opt_message)

פרמטרים

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

Matchers

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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`	object	הערך להחזרה עבור ה-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'});