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

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

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

const myAPI = require('myAPI');

addConsentListener

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

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

פרמטרים

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

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

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

addEventCallback

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

תחביר

addEventCallback(callback)

פרמטרים

האובייקט eventData מכיל את הנתונים הבאים:

דוגמה

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

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

read_event_metadata

aliasInWindow

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

תחביר

aliasInWindow(toPath, fromPath)

פרמטרים

דוגמה

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

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

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

callInWindow

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

תחביר

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

פרמטרים

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

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

callLater

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

תחביר

callLater(function)

פרמטרים

copyFromDataLayer

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

תחביר

copyFromDataLayer(key[, dataLayerVersion])

פרמטרים

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

read_data_layer

copyFromWindow

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

תחביר

copyFromWindow(key)

פרמטרים

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

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)

פרמטרים

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

access_globals

createQueue

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

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

דוגמה:

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

תחביר

createQueue(arrayKey)

פרמטרים

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

access_globals

decodeUri

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

דוגמה:

const decode = require('decodeUri');

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

תחביר

decodeUri(encoded_uri)

פרמטרים

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

ללא.

decodeUriComponent

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

דוגמה:

const decode = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component)

פרמטרים

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

ללא.

encodeUri

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

דוגמה:

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

תחביר

encodeUri(uri)

פרמטרים

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

ללא.

encodeUriComponent

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

דוגמה:

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

תחביר

encodeUriComponent(str)

פרמטרים

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

ללא.

fromBase64

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

תחביר

fromBase64(base64EncodedString)

פרמטרים

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא

generateRandom

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

תחביר

generateRandom(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])

פרמטרים

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

get_cookies

getQueryParameters

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

תחביר

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

תחביר

getReferrerQueryParameters(queryKey[, retrieveAll])

פרמטרים

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

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

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

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

getReferrerUrl

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

תחביר

getReferrerUrl([component])

פרמטרים

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

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

getTimestamp

הוצא משימוש. מומלץ להשתמש ב-getTimestampMillis.

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

תחביר

getTimestamp();

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

ללא.

getTimestampMillis

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

תחביר

getTimestampMillis();

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

ללא.

getType

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

תחביר

getType(data.someField)

הערות

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

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

ללא.

getUrl

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

תחביר

getUrl(component)

פרמטרים

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

get_url

gtagSet

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

לדוגמה, אם הפונקציה נקראת על ידי תג שמופעל על 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)

פרמטרים

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

‫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)

פרמטרים

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

inject_hidden_iframe

injectScript

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

תחביר

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

פרמטרים

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

inject_script

isConsentGranted

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

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

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

דוגמה:

const isConsentGranted = require('isConsentGranted');

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

תחביר

isConsentGranted(consentType)

פרמטרים

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

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

JSON

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

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

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

תחביר

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

פרמטרים

JSON.parse

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

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

תחביר

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])

פרמטרים

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

logging

makeInteger

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

תחביר

makeInteger(value)

פרמטרים

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

ללא.

makeNumber

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

תחביר

makeNumber(value)

פרמטרים

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

ללא.

makeString

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

תחביר

makeString(value)

פרמטרים

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

ללא.

makeTableMap

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

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

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

לתוך מפה:

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

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

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName)

פרמטרים

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

ללא.

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.

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

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

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

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

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

Object.values

Object.entries

Object.freeze

Object.delete

דוגמה

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);

פרמטרים

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

ללא.

queryPermission

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

תחביר

queryPermission(permission, functionArgs*)

פרמטרים

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

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

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

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

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

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

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

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

ללא.

readAnalyticsStorage

מאחזר את הנתונים שמאוחסנים לצורך ניתוח ומחזיר אובייקט עם client_id ו-sessions.

• ‫client_id: מחרוזת שמייצגת את מזהה הלקוח שמשמש לניתוח נתונים.
• ‫sessions: מערך של אובייקטים שמכילים מידע על סשנים נוכחיים. כל אובייקט כולל:
  • ‫measurement_id: מחרוזת שמייצגת את מזהה המדידה של יעד Analytics.
  • ‫session_id: מחרוזת שמייצגת את חותמת הזמן שמזהה את הסשן הנוכחי.
  • ‫session_number: מספר שמייצג את מספר הסשנים שהמשתמש התחיל עד לסשן הנוכחי.

תחביר

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

פרמטרים

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

read_analytics_storage

דוגמה

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

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

תחביר

readCharacterSet()

פרמטרים

ללא.

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

read_character_set

readTitle

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

תחביר

readTitle()

פרמטרים

ללא.

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

read_title

require

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

תחביר

require(name)

פרמטרים

דוגמה

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

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

ללא.

sendPixel

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

תחביר

sendPixel(url, onSuccess, onFailure)

פרמטרים

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

send_pixel

setCookie

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

תחביר

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

פרמטרים

אפשרויות

• דומיין: מוגדר על ידי המאפיין options['domain'], אם הוא קיים. מגדירים את הערך הזה ל-'auto' כדי לנסות לכתוב את קובץ ה-Cookie באמצעות הדומיין הרחב ביותר האפשרי, על סמך מיקום המסמך. אם זה לא יצליח, המערכת תנסה להשתמש בתת-דומיינים ספציפיים יותר. אם כל אלה ייכשלו, המערכת תנסה לכתוב את קובץ ה-Cookie ללא דומיין. אם לא מוגדר ערך, המערכת תנסה לכתוב את קובץ ה-Cookie בלי לציין דומיין. הערה: כשקובץ Cookie ללא דומיין מוגדר נכתב ל-document.cookie, סוכן המשתמש יגדיר כברירת מחדל את הדומיין של קובץ ה-Cookie למארח של המיקום הנוכחי של המסמך.
• נתיב: מוגדר על ידי options['path'], אם קיים. כשקובץ Cookie ללא נתיב שצוין נכתב אל document.cookie, נתיב קובץ ה-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 הוא מיפוי של מחרוזות שרירותיות של סוגי הסכמה לאחד מהערכים 'granted' או 'denied'. אפשר להזין בו את הערכים הבאים:

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

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

setInWindow

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

תחביר

setInWindow(key, value, overrideExisting)

פרמטרים

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

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)

פרמטרים

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

ללא.

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)

פרמטרים

דוגמה

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 הוא מיפוי של מחרוזות שרירותיות של סוגי הסכמה לאחד מהערכים 'granted' או 'denied'. אפשר להזין בו את הערכים הבאים:

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

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

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

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

assertApi

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

תחביר

assertApi(apiName)

פרמטרים

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)

פרמטרים

Matchers

דוגמאות

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);

פרמטרים

דוגמה

fail('This test has failed.');

mock

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

תחביר

mock(apiName, returnValue);

פרמטרים

דוגמאות

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

mockObject

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

תחביר

mockObject(apiName, objectMock);

פרמטרים

דוגמאות

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

runCode

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

תחביר

runCode(data)

פרמטרים

ערך מוחזר

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

דוגמה

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