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

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

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

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

const myAPI = require('myAPI');

`addConsentListener`

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

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

דוגמה:

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

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

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

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

הרשאת 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`	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`	פונקציה	הפונקציה שצריך להפעיל.

`copyFromDataLayer`

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

תחביר

copyFromDataLayer(key[, dataLayerVersion])

פרמטרים

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

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

read_data_layer

`copyFromWindow`

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

תחביר

copyFromWindow(key)

פרמטרים

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

דוגמה:

const decode = require('decodeUri');

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

תחביר

decodeUri(encoded_uri)

פרמטרים

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

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

ללא.

`decodeUriComponent`

מפענח כל תווים מקודדים ברכיב ה-URI שסופק. הפונקציה מחזירה את string שמייצג את רכיב ה-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) מקודד באמצעות Escing Special תווים. הפונקציה מחזירה string שמייצגת את המחרוזת שסופקה עם הקידוד של URI. הפונקציה מחזירה את הערך undefined כשהוא סופק עם קלט לא חוקי (משתנה נפרד).

דוגמה:

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

תחביר

encodeUri(uri)

פרמטרים

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

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

ללא.

`encodeUriComponent`

דוגמה:

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

תחביר

encodeUriComponent(str)

פרמטרים

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

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

ללא.

`fromBase64`

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

תחביר

fromBase64(base64EncodedString)

פרמטרים

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

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא

`generateRandom`

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

תחביר

generateRandom(min, max)

פרמטרים

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

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

ללא.

`getContainerVersion`

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

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

דוגמה

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

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

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

תחביר

getContainerVersion();

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

read_container_data

`getCookieValues`

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

תחביר

getCookieValues(name[, decode])

פרמטרים

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

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

get_cookies

`getQueryParameters`

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

תחביר

getQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

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

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

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

`getReferrerQueryParameters`

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

תחביר

getReferrerQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

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

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

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

`getReferrerUrl`

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

תחביר

getReferrerUrl([component])

פרמטרים

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

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

`getTimestamp`

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

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

תחביר

getTimestamp();

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

ללא.

`getTimestampMillis`

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

תחביר

getTimestampMillis();

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

ללא.

`getType`

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

תחביר

getType(data.someField)

הערות

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

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

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

ללא.

`getUrl`

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

תחביר

getUrl(component)

פרמטרים

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

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

get_url

`gtagSet`

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

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

inject_hidden_iframe

`injectScript`

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

תחביר

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

פרמטרים

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

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

inject_script

`isConsentGranted`

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

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

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

דוגמה:

const isConsentGranted = require('isConsentGranted');

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

תחביר

isConsentGranted(consentType)

פרמטרים

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

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

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

`JSON`

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

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

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

תחביר

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

פרמטרים

JSON.parse

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

JSON.stringify

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

דוגמה

const JSON = require('JSON');

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

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

`localStorage`

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

תחביר

const localStorage = require('localStorage');

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

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

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

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

access_local_storage

דוגמה

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

`logToConsole`

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

תחביר

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

פרמטרים

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

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

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`	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 methods.

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

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

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

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

השיטה delete() מספקת את אופרטור המחיקה של הספרייה הרגילה או התנהגות המשתמשים. היא מסירה את המפתח הנתון מהאובייקט, אלא אם הוא מוקפא. בדומה לאופרטור המחיקה בספרייה הרגילה, הוא מחזיר true אם הקלט הראשון value (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	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.

ה-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`

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

תחביר

queryPermission(permission, functionArgs*)

פרמטרים

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

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

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

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

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

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

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

send_pixel

`setCookie`

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

תחביר

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

פרמטרים

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

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

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

set_cookies

`setDefaultConsentState`

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

דוגמה:

const setDefaultConsentState = require('setDefaultConsentState');

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

תחביר

setDefaultConsentState(consentSettings)

פרמטרים

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

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

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

access_globals

`sha256`

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

דוגמה:

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

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

תחביר

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

פרמטרים

פרמטר	סוג	תיאור
`input`	string	המחרוזת שעבורה יש לחשב את ה-hash.
`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`

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

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

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

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

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

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

`assertApi`

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

תחביר

assertApi(apiName)

פרמטרים

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

תחביר

assertThat(actual, opt_message)

פרמטרים

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

התאמות

תואם	תיאור
`isUndefined()`	מצהיר/ה שהנושא הוא `undefined`.
`isDefined()`	מצהיר/ה שהנושא אינו `undefined`.
`isNull()`	מצהיר/ה שהנושא הוא `null`.
`isNotNull()`	מצהיר/ה שהנושא אינו `null`.
`isFalse()`	מצהיר/ה שהנושא הוא `false`.
`isTrue()`	מצהיר/ה שהנושא הוא `true`.
`isFalsy()`	טוען שהנושא הוא חשוד. ערכי Falsy הם `undefined`, `null`, `false` `NaN`, 0 וגם '' (מחרוזת ריקה).
`isTruthy()`	טוען שהנושא ברור. ערכי Falsy הם `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()`	טוענת שהנושא הוא מערך או מחרוזת ריקים (length =) 0). טענת הנכוֹנוּת (assertion) תמיד תיכשל אם הערך הוא לא מערך או String.
`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`	string	טקסט אופציונלי של הודעת שגיאה.

דוגמה

fail('This test has failed.');

`mock`

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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

`mockObject`

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

תחביר

mockObject(apiName, objectMock);

פרמטרים

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

דוגמאות

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

`runCode`

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

תחביר

runCode(data)

פרמטרים

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

ערך החזרה

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

דוגמה

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