ממשקי 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);
});
הרשאות משויכות
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. |
הרשאות משויכות
copyFromWindow
מעתיק משתנה מאובייקט window
. אם לא ניתן למפות את הערך ב-window
ישירות לסוג שנתמך ב-JavaScript בארגז חול, הפונקציה undefined
תחזיר. שמונת הסוגים הנתמכים ב-JavaScript בארגז החול הם null
,
undefined
, boolean
, number
, string
, Array
, Object
ו-function
.
מחזירה את הערך שאוחזר (והכפוף).
תחביר
copyFromWindow(key)
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
key |
מחרוזת | המפתח ב-window שאת הערך שלו רוצים להעתיק. |
הרשאות משויכות
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' , יתקבלו
חריגות. |
הרשאות משויכות
createQueue
הפונקציה יוצרת מערך ב-window
(אם הוא לא קיים) ומחזירה פונקציה שדוחפת ערכים למערך הזה.
כדי להשתמש בפונקציה הזו נדרשת הגדרת הקריאה והכתיבה עבור arrayKey
בהרשאה access_globals
.
דוגמה:
const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});
תחביר
createQueue(arrayKey)
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
arrayKey |
מחרוזת | המפתח ב-window שבו המערך מוגדר, אם הוא לא קיים כבר. הארגומנט הזה תומך בסימון נקודות רגיל. אם הנתיב של המפתח לא קיים, המערכת מפעילה חריג. לדוגמה, אם
arrayKey הוא 'one.two' , ואין אובייקט גלובלי בשם 'one' , הוא יגרום
לחריגה. |
הרשאות משויכות
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();
הרשאות משויכות
getCookieValues
מחזירה את הערכים של כל קובצי ה-Cookie בשם הנתון.
תחביר
getCookieValues(name[, decode])
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
name |
מחרוזת | שם קובץ ה-Cookie. |
decode |
boolean | המדיניות קובעת אם יש לפענח את הערכים של קובצי ה-cookie באמצעות
decodeURIComponent() של JavaScript. ברירת המחדל היא
true . |
הרשאות משויכות
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 . |
הרשאות משויכות
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 |
פונקציה | מתבצעת קריאה כשהמסגרת נטענת בהצלחה. |
הרשאות משויכות
injectScript
הוספת תג סקריפט לדף כדי לטעון את כתובת ה-URL הנתונה באופן אסינכרוני. הקריאות החוזרות (callback) מוצגות כמופעים של פונקציות, והן מוקפות בפונקציות JavaScript שקוראות אליהן.
תחביר
injectScript(url, onSuccess, onFailure[, cacheToken])
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
url |
מחרוזת | כתובת הסקריפט שיש להחדיר. |
onSuccess |
פונקציה | מופעלת כשהסקריפט נטען בהצלחה. |
onFailure |
פונקציה | מופעלת כשטעינת הסקריפט נכשלה. |
cacheToken |
מחרוזת | מחרוזת אופציונלית המשמשת לציון כתובת ה-URL הנתונה. אם מציינים את הערך הזה, המערכת תיצור רק רכיב סקריפט אחד כדי לבקש את ה-JavaScript. כל ניסיון נוסף לטעון יגרום לכך שהשיטות onSuccess ו-onFailure הנתונות
יופיעו בתור עד שהסקריפט ייטען. |
הרשאות משויכות
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);
הרשאות משויכות
דוגמה
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] |
כלשהו | ארגומנטים |
הרשאות משויכות
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()
פרמטרים
ללא.
הרשאות משויכות
readTitle
מחזירה את הערך של document.title
.
תחביר
readTitle()
פרמטרים
ללא.
הרשאות משויכות
require
מייבאת פונקציה מובנית לפי שם. מחזירה פונקציה או אובייקט שאפשר לקרוא להם מהתוכנה. הפונקציה מחזירה את הערך undefined כשהדפדפן לא תומך בפונקציה המובנית.
תחביר
require(name)
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
name |
מחרוזת | שם הפונקציה לייבוא. |
דוגמה
const getUrl = require('getUrl');
const url = getUrl();
הרשאות משויכות
ללא.
sendPixel
שולח בקשת GET לנקודת קצה (endpoint) ספציפית של כתובת URL.
תחביר
sendPixel(url, onSuccess, onFailure)
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
url |
מחרוזת | לאן לשלוח את הפיקסל. |
onSuccess |
פונקציה | היא נקראת כאשר הפיקסל נטען בהצלחה. הערה: גם אם הבקשה נשלחת בהצלחה, יכול להיות שדפדפנים יחייבו תגובת תמונה חוקית כדי לפעול בהצלחה. |
onFailure |
פונקציה | מתבצעת קריאה כשטעינת הפיקסל נכשלה. הערה: גם אם הבקשה נשלחת בהצלחה, onFailure עשוי לרוץ אם השרת לא מחזיר תגובה חוקית של תמונה. |
הרשאות משויכות
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']
, אם קיים.
הרשאות משויכות
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 ,
גם אם קיים ערך וגם לא. |
הרשאות משויכות
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();
הרשאות משויכות
דוגמה
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'});