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

ממשקי API ליבה

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

const myAPI = require('myAPI');

addConsentListener

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

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

דוגמה:

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

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

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

תחביר

addConsentListener(consentType, listener)

פרמטרים

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

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

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

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

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

addEventCallback

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

תחביר

addEventCallback(callback)

פרמטרים

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

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

דוגמה

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

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

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

callInWindow

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

תחביר

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

פרמטרים

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

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

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

callLater

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

תחביר

callLater(function)

פרמטרים

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

copyFromDataLayer

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

תחביר

copyFromDataLayer(key[, dataLayerVersion])

פרמטרים

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

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

read_data_layer

copyFromWindow

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

תחביר

copyFromWindow(key)

פרמטרים

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

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

access_globals

createArgumentsQueue

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

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

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

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

דוגמה:

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

תחביר

createArgumentsQueue(fnKey, arrayKey)

פרמטרים

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

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

access_globals

createQueue

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

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

דוגמה:

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

תחביר

createQueue(arrayKey)

פרמטרים

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

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

access_globals

decodeUri

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

דוגמה:

const decode = require('decodeUri');

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

תחביר

decodeUri(encoded_uri)

פרמטרים

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

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

ללא.

decodeUriComponent

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

דוגמה:

const decode = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component)

פרמטרים

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

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

ללא.

encodeUri

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

דוגמה:

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

תחביר

encodeUri(uri)

פרמטרים

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

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

ללא.

encodeUriComponent

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

דוגמה:

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

תחביר

encodeUriComponent(str)

פרמטרים

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

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

ללא.

fromBase64

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

תחביר

fromBase64(base64EncodedString)

פרמטרים

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

דוגמה

const fromBase64 = require('fromBase64');

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

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

אין

generateRandom

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

תחביר

generateRandom(min, max)

פרמטרים

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

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

ללא.

getContainerVersion

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

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

דוגמה

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

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

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

תחביר

getContainerVersion();

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

read_container_data

getCookieValues

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

תחביר

getCookieValues(name[, decode])

פרמטרים

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

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

get_cookies

getQueryParameters

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

תחביר

getQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

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

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

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

getReferrerQueryParameters

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

תחביר

getReferrerQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

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

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

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

getReferrerUrl

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

תחביר

getReferrerUrl([component])

פרמטרים

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

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

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

getTimestamp

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

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

תחביר

getTimestamp();

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

ללא.

getTimestampMillis

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

תחביר

getTimestampMillis();

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

ללא.

getType

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

תחביר

getType(data.someField)

הערות

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

ערך קלט תוצאה
undefined לא מוגדר
null 'null'
true 'boolean'
12 'מספר'
'string' 'מחרוזת'
{ a: 3 } אובייקט
[ 1, 3 ] 'מערך'
(x) => x + 1 'function'

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

ללא.

getUrl

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

תחביר

getUrl(component)

פרמטרים

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

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

get_url

gtagSet

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

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

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

inject_hidden_iframe

injectScript

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

תחביר

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

פרמטרים

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

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

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

JSON

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

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

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

תחביר

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

פרמטרים

JSON.parse

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

JSON.stringify

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

דוגמה

const JSON = require('JSON');

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

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

localStorage

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

תחביר

const localStorage = require('localStorage');

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

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

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

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

access_local_storage

דוגמה

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

logToConsole

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

תחביר

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

פרמטרים

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

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

logging

makeInteger

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

תחביר

makeInteger(value)

פרמטרים

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

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

ללא.

makeNumber

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

תחביר

makeNumber(value)

פרמטרים

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

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

ללא.

makeString

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

תחביר

makeString(value)

פרמטרים

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

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

ללא.

makeTableMap

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

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

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

למפה:

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

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

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName)

פרמטרים

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

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

ללא.

Math

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

תחביר

const Math = require('Math');

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

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

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

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

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

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

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

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

פרמטרים

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

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

ללא.

Object

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

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

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

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

דוגמה

const Object = require('Object');

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

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

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

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

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

parseUrl

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

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

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

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

דוגמה

const parseUrl = require('parseUrl');

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

תחביר

parseUrl(url);

פרמטרים

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

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

ללא.

queryPermission

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

תחביר

queryPermission(permission, functionArgs*)

פרמטרים

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

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

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

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

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

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

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

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

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

ללא.

readCharacterSet

מחזירה את הערך של document.characterSet.

תחביר

readCharacterSet()

פרמטרים

ללא.

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

read_character_set

readTitle

מחזירה את הערך של document.title.

תחביר

readTitle()

פרמטרים

ללא.

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

read_title

require

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

תחביר

require(name)

פרמטרים

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

דוגמה

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

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

ללא.

sendPixel

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

תחביר

sendPixel(url, onSuccess, onFailure)

פרמטרים

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

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

send_pixel

setCookie

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

תחביר

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

פרמטרים

פרמטר סוג תיאור
name מחרוזת שם קובץ ה-Cookie.
value מחרוזת הערך של קובץ ה-cookie.
options אובייקט מציינת את המאפיינים 'דומיין', 'נתיב', 'פג תוקף', 'גיל מקסימלי', 'אבטחה' ו-'SameSite'. (ראו אפשרויות בהמשך).
encode boolean המדיניות הזו קובעת אם הערך של קובץ ה-cookie יקודד באמצעות encodeURIComponent() של JavaScript. ברירת המחדל היא true.

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

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

set_cookies

setDefaultConsentState

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

דוגמה:

const setDefaultConsentState = require('setDefaultConsentState');

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

תחביר

setDefaultConsentState(consentSettings)

פרמטרים

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

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

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

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

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

setInWindow

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

תחביר

setInWindow(key, value, overrideExisting)

פרמטרים

פרמטר סוג תיאור
key מחרוזת המפתח ב-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 מחרוזת המחרוזת שעבורה יש לחשב את הגיבוב.
onSuccess פונקציה הוא נקרא עם התקציר שנוצר, והוא מקודד ב-base64, אלא אם האובייקט options מציין קידוד פלט שונה.
onFailure פונקציה היא מוצגת כשמתרחשת שגיאה במהלך חישוב התקציר, או אם אין בדפדפן תמיכה מובנית ב-sha256. הקריאה החוזרת מתבצעת עם אובייקט שמכיל את שם השגיאה ואת ההודעה.
options אובייקט אובייקט אפשרויות אופציונלי לציון קידוד הפלט. אם צוין, האובייקט צריך להכיל את המפתח outputEncoding עם ערך של base64 או hex.

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

ללא.

templateStorage

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

תחביר

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

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

access_template_storage

דוגמה

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

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

templateStorage.setItem('alreadyRan', true);

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

toBase64

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

תחביר

toBase64(input)

פרמטרים

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

דוגמה

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

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

אין

updateConsentState

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

דוגמה:

const updateConsentState = require('updateConsentState');

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

תחביר

updateConsentState(consentSettings)

פרמטרים

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

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

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

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

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

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

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

assertApi

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

תחביר

assertApi(apiName)

פרמטרים

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

התאמות

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

תחביר

assertThat(actual, opt_message)

פרמטרים

פרמטר סוג תיאור
actual כלשהו הערך שיש להשתמש בו בבדיקות שוטפות.
opt_message מחרוזת יש אפשרות להדפיס את ההודעה אם טענת הנכוֹנוּת (assertion) נכשלה.

התאמות

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

דוגמאות

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

fail

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

תחביר

fail(opt_message);

פרמטרים

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

דוגמה

fail('This test has failed.');

mock

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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

runCode

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

תחביר

runCode(data)

פרמטרים

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

הערך המוחזר

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

דוגמה

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