ממשקי 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

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

דוגמה:

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

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

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

שם מפתח סוג תיאור
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'});