‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

ממשקי API לתיוג בצד השרת

במסמך הזה מפורטים ממשקי ה-API לתיוג בצד השרת.

`addEventCallback`

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

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

תחביר

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

פרמטרים

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

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

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

דוגמה

בלקוח:

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

בתג:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

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

read_event_metadata

`callLater`

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

דוגמה

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

תחביר

callLater(function)

פרמטרים

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

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

ללא.

`claimRequest`

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

ה-API הזה מעלה חריגה אם הוא מופעל בתג או במשתנה. ה-API הזה יוצר חריגה אם הוא מופעל אחרי שהלקוח חוזר (לדוגמה, אם הוא מופעל בקריאה חוזרת אסינכרונית כמו ב-callLater או בפונקציה runContainer onComplete).

לקוח צריך לשלוח בקשה באמצעות ה-API הזה לפני שהוא קורא ל-API‏ runContainer.

דוגמה

const claimRequest = require('claimRequest');

claimRequest();

תחביר

claimRequest();

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

ללא.

`computeEffectiveTldPlusOne`

הפונקציה מחזירה את הדומיין האפקטיבי ברמה העליונה + 1 (eTLD+1) של הדומיין או כתובת ה-URL שצוינו. החישוב של eTLD+1 מתבצע על ידי בדיקת הדומיין בהתאם לכללים של רשימת הסיומות הציבוריות. בדרך כלל, eTLD+1 הוא הדומיין ברמה הכי גבוהה שאפשר להגדיר בו קובץ Cookie.

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

דוגמה

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

תחביר

computeEffectiveTldPlusOne(domainOrUrl);

פרמטרים

פרמטר	סוג	תיאור
`domainOrUrl`	מחרוזת	דומיין או כתובת URL שרוצים לחשב את ה-eTLD+1 שלהם.

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

ללא.

`createRegex`

יוצרת מופע חדש של ביטוי רגולרי ומחזירה אותו עטוף באובייקט. אי אפשר לגשת ישירות לביטוי הרגולרי. עם זאת, אפשר להעביר אותו אל testRegex API, String.replace(), String.match() ו-String.search().

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

ב-API הזה נעשה שימוש בהטמעה של Re2. קובץ האימג' של Docker בשרת צריך להיות מגרסה 2.0.0 ואילך.

דוגמה

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

תחביר

createRegex(pattern, flags);

פרמטרים

פרמטר	סוג	תיאור
`pattern`	מחרוזת	הטקסט של הביטוי הרגולרי.
`flags`	מחרוזת	מחרוזת אופציונלית שמכילה את הדגלים של הביטוי הרגולרי שנוצר. יש תמיכה ב-`g` (כללי) וב-`i` (התעלמות מסוג האותיות). המערכת מתעלמת מכל שאר התווים.

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

ללא.

גרסת התמונה המינימלית

2.0.0

`decodeUri`

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

דוגמה

const decodeUri = require('decodeUri');

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

תחביר

decodeUri(encoded_uri);

פרמטרים

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

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

ללא.

`decodeUriComponent`

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

דוגמה

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

תחביר

decodeUriComponent(encoded_uri_component);

פרמטרים

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

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

ללא.

`encodeUri`

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

דוגמה

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

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

תחביר

encodeUri(uri);

פרמטרים

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

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

ללא.

`encodeUriComponent`

דוגמה

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

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

תחביר

encodeUriComponent(str);

פרמטרים

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

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

ללא.

`extractEventsFromMpv1`

מתרגם בקשה נכנסת מ-Measurement Protocol V1 לרשימת אירועים בפורמט Unified Schema. מחזירה את רשימת האירועים שחולצו. אם הבקשה לא בפורמט הנכון, תוחזר שגיאה.

דוגמה

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

תחביר

extractEventsFromMpv1();

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

נדרשת הרשאה ל-read_request. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

body
query parameters

`extractEventsFromMpv2`

מתרגם בקשה נכנסת של Measurement Protocol V2 לרשימה של אירועים בפורמט Unified Schema. מחזירה את רשימת האירועים שחולצו. אם הבקשה לא בפורמט הנכון, תוחזר שגיאה.

דוגמה

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

תחביר

extractEventsFromMpv2();

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

נדרשת הרשאה ל-read_request. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

body
query parameters

`fromBase64`

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

תחביר

fromBase64(base64EncodedString);

פרמטרים

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

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא.

`generateRandom`

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

דוגמה

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

תחביר

generateRandom(min, max);

פרמטרים

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

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

ללא.

`getAllEventData`

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

תחביר

getAllEventData();

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

read_event_data

`getClientName`

הפונקציה מחזירה מחרוזת שמכילה את השם של הלקוח הנוכחי.

תחביר

getClientName();

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

read_container_data

`getContainerVersion`

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

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

דוגמה

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

תחביר

getContainerVersion();

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

read_container_data

`getCookieValues`

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

דוגמה

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

תחביר

getCookieValues(name[, noDecode]);

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	השם של קובץ ה-Cookie.
`noDecode`	boolean	אם `true`, הערכים של קובצי ה-Cookie לא יפוענחו לפני שהם יוחזרו. ברירת המחדל היא `false`.

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

get_cookies

`getEventData`

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

דוגמה

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

פרמטרים

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

תחביר

getEventData(keyPath);

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

read_event_data

`getGoogleAuth`

הפונקציה מחזירה אובייקט הרשאה, שאם משתמשים בו עם sendHttpGet או sendHttpRequest, יכלול כותרת הרשאה ל-Google Cloud APIs. ממשק ה-API הזה משתמש בApplication Default Credentials כדי למצוא באופן אוטומטי פרטי כניסה מסביבת השרת.

דוגמה

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

תחביר

getGoogleAuth(scopes);

פרמטרים

פרמטר	סוג	תיאור
`scopes`	מערך	מערך של היקפי הרשאות של OAuth 2.0 ל-Google APIs שרוצים לבקש גישה אליהם.

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

נדרשת הרשאה ל-use_google_credentials. צריך להגדיר את ההרשאה עם היקף אחד או יותר של הרשאות.

`getGoogleScript`

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

ה-promise יותאם לאובייקט שמכיל שני מפתחות: script ו-metadata. אם הבקשה נכשלת, ההבטחה תידחה עם מפתח reason.

אובייקט metadata יכיל את מטא-נתוני הקאשינג הבאים על סמך כותרות התגובה של המשאב. כל שדה יופיע רק אם הכותרת המתאימה מופיעה בתגובת המשאב.

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

דוגמה

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

תחביר

getGoogleScript(script[, options]);

פרמטרים

פרמטר	סוג	תיאור
`script`	מחרוזת	שם הסקריפט. הסקריפטים הנתמכים הם `'ANALYTICS'`,‏ `'GTAG'` ו-`'GTM'`. האפשרות `'ANALYTICS'` מאחזרת את הסקריפט של Google Analytics מכתובת `https://www.google-analytics.com/analytics.js`. האפשרות `'GTAG'` מאחזרת את הסקריפט של תג המעקב ברמת האתר (gtag.js) מ-`https://www.googletagmanager.com/gtag/js`. האפשרות `'GTM'` מאחזרת את הסקריפט של Google Tag Manager מכתובת `https://www.googletagmanager.com/gtm.js`.
`options`	object	אפשרויות אופציונליות לבקשה. אפשרויות התמיכה הזמינות מפורטות בהמשך.

אפשרויות

אפשרות	סוג	תיאור
`id`	מחרוזת	רלוונטי ל-`'GTAG'` עם מזהה המדידה של gtag ול-`'GTM'` עם מזהה מאגר תגים באינטרנט (לדוגמה, GTM-XXXX).
`debug`	כל	אם הערך הוא truthy, הפונקציה שולחת בקשה לגרסת הניפוי באגים של סקריפט המדידה ומחזירה אותה.
`timeout`	number	זמן הקצוב לתפוגה של הבקשה באלפיות השנייה. המערכת מתעלמת מערכים לא חיוביים. אם חלף הזמן הקצוב לתגובה של הבקשה, הקריאה החוזרת תופעל עם הערך `undefined` עבור ערך הסקריפט ועם הערך `{}` עבור אובייקט המטא-נתונים.

המערכת מתעלמת ממפתחות של אפשרויות לא מזוהות.

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

נדרשת הרשאה ל-send_http. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

אפשר להשתמש ב-Google Domains

`getRemoteAddress`

הפונקציה מחזירה מחרוזת שמייצגת את כתובת ה-IP שממנה נשלחה הבקשה, למשל 12.345.67.890 עבור IPv4 או 2001:0db8:85a3:0:0:8a2e:0370:7334 עבור IPv6, על ידי קריאת כותרות הבקשה כמו Forwarded ו-X-Forwarded-For. הערה: ה-API הזה מנסה לגלות את כתובת ה-IP המקורית, אבל הוא לא יכול להבטיח שהתוצאה מדויקת.

תחביר

getRemoteAddress();

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

נדרשת הרשאה ל-read_request. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

כותרות Forwarded ו-X-Forwarded-For
כתובת IP מרוחקת

`getRequestBody`

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

תחביר

getRequestBody();

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

read_request

`getRequestHeader`

הפונקציה מחזירה את הערך של request header שצוין השם שלה כמחרוזת, אם היא קיימת, או undefined אם היא לא קיימת. אם הכותרת חוזרת על עצמה, הערכים שמוחזרים מצורפים זה לזה עם ', '.

דוגמה

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

תחביר

getRequestHeader(headerName);

פרמטרים

פרמטר	סוג	תיאור
`headerName`	מחרוזת	שם הכותרת. הערך הזה לא תלוי באותיות רישיות.

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

read_request

`getRequestMethod`

הפונקציה מחזירה את שיטת הבקשה, למשל 'GET' או 'POST', בתור מחרוזת.

דוגמה

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

תחביר

getRequestMethod();

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

ללא.

`getRequestPath`

הפונקציה מחזירה את נתיב הבקשה בלי מחרוזת השאילתה. לדוגמה, אם כתובת ה-URL היא '/foo?id=123', הפונקציה תחזיר '/foo'. הוא מסיר אוטומטית את התחילית של כתובת ה-URL של מאגר התגים בצד השרת מהנתיב. לדוגמה, אם כתובת ה-URL של מאגר תגים בצד השרת היא https://example.com/analytics ונתיב הבקשה הוא '/analytics/foo', הפונקציה מחזירה '/foo'.

דוגמה

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

תחביר

getRequestPath();

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

read_request

`getRequestQueryParameter`

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

דוגמה

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

תחביר

getRequestQueryParameter(name);

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	השם של פרמטר השאילתה.

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

read_request

`getRequestQueryParameters`

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

דוגמה

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

תחביר

getRequestQueryParameters();

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

read_request

`getRequestQueryString`

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

דוגמה

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

תחביר

getRequestQueryString();

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

read_request

`getTimestamp`

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

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

תחביר

getTimestamp();

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

ללא.

`getTimestampMillis`

תחביר

getTimestampMillis();

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

ללא.

`getType`

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

סוג קלט	הערך שמוחזר
מחרוזת	`'string'`
number	`'number'`
boolean	`'boolean'`
null	`'null'`
undefined	`'undefined'`
מערך	`'array'`
אובייקט	`'object'`
פעולה	`'function'`

דוגמה

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

תחביר

getType(value);

פרמטרים

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

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

ללא.

`hmacSha256`

חישוב חתימה מקודדת באמצעות קוד אימות הודעות המבוסס על גיבוב (HMAC) עם SHA-256. ברירת המחדל היא קידוד base64url.

כדי להשתמש ב-API הזה, צריך להגדיר את משתנה הסביבה SGTM_CREDENTIALS בשרת לנתיב של קובץ מפתח JSON עם קידוד UTF-8 בפורמט הבא:

{
  "keys": {
    "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
    "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
    ...
  }
}

הערכים הם מפתחות HMAC בקידוד Base64. טקסט ה-JSON לא יכול להתחיל בסימן לסדר בתים (BOM).

דוגמה

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

תחביר

hmacSha256(data, keyId, options)

פרמטרים

פרמטר	סוג	תיאור
`data`	מחרוזת	הנתונים לחישוב ערך ה-HMAC.
`keyId`	מחרוזת	מזהה מפתח מקובץ מפתח JSON שמתייחס למפתח שבו רוצים להשתמש.
`options`	object	אופציונלי: הגדרת API. (ראו אפשרויות בהמשך).

אפשרויות

אפשרות	סוג	תיאור
`outputEncoding`	מחרוזת	מציין את פורמט הקידוד של ערך ההחזרה. הפורמטים הנתמכים הם `hex`,‏ `base64` או `base64url`. אם לא מציינים ערך, ברירת המחדל היא `base64url`.

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

use_custom_private_keys

גרסת התמונה המינימלית

‫1.0.0

`isRequestMpv1`

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

דוגמה

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

תחביר

isRequestMpv1();

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

ללא.

`isRequestMpv2`

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

דוגמה

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

תחביר

isRequestMpv2();

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

ללא.

`logToConsole`

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

אפשר לראות את היומנים האלה בLogs Explorer במסוף Google Cloud. מריצים את השאילתה logName =~ "stdout" ב-Logs Explorer כדי לראות את רשומות היומן שנוצרו על ידי ה-API הזה.

דוגמה

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

תחביר

logToConsole(argument1[, argument2, ...]);

פרמטרים

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

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

logging

`makeInteger`

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

תחביר

makeInteger(value);

פרמטרים

פרמטר	סוג	תיאור
`value`	any type	הערך להמרה.

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

ללא.

`makeNumber`

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

תחביר

makeNumber(value);

פרמטרים

פרמטר	סוג	תיאור
`value`	any type	הערך להמרה.

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

ללא.

`makeString`

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

תחביר

makeString(value);

פרמטרים

פרמטר	סוג	תיאור
`value`	any type	הערך להמרה.

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

ללא.

`makeTableMap`

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

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

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

לתוך מפה:

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

מחזירה Object: הערך Map אחרי שנוספו לו צמדי מפתח/ערך, או null אחרת.

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName);

פרמטרים

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

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

ללא.

`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 המלאה שתנותח.

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

ללא.

`returnResponse`

מנקה את התגובה שהוגדרה קודם על ידי תבניות אחרות באמצעות ממשקי ה-API שמשנים את התגובה, כולל setCookie,‏ setPixelResponse,‏ setResponseBody,‏ setResponseHeader ו-setResponseStatus. ברירת המחדל היא קוד סטטוס של HTTP‏ 200, גוף ריק וללא כותרות.

מומלץ להשתמש ב-API הזה מתבנית לקוח.

תחביר

returnResponse();

דוגמה

runContainerדוגמה

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

return_response

`runContainer`

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

הקריאות החוזרות onComplete ו-onStart מקבלות פונקציה בשם bindToEvent. אפשר להשתמש ב-bindToEvent כדי להפעיל API בהקשר של האירוע. פרטים נוספים מופיעים בדוגמה של addEventCallback.

מומלץ להשתמש ב-API הזה מתבנית לקוח.

דוגמה

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

תחביר

runContainer(event, onComplete, onStart);

פרמטרים

פרמטר	סוג	תיאור
`event`	object	הפרמטרים של האירוע.
`onComplete`	function	קריאה חוזרת שמופעלת אחרי שכל התגים מסיימים את ההפעלה.
`onStart`	function	פונקציית קריאה חוזרת שמופעלת באופן מיידי, לפני שהתגים מתחילים לפעול.

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

run_container

`sendEventToGoogleAnalytics`

שולחת אירוע יחיד באמצעות Common Event Data אל Google Analytics ומחזירה promise שמוביל לאובייקט עם מפתח location או לאובייקט עם מפתח reason. יעד הנתונים, Google Analytics, מבוסס על מזהה המדידה בנתוני האירועים.

השדה location מוגדר לכותרת location, אם היא קיימת.

דוגמה

const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

תחביר

sendEventToGoogleAnalytics(event);

פרמטרים

פרמטר	סוג	תיאור
`event`	object	האירוע בפורמט Unified Schema.

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

נדרשת הרשאה ל-send_http. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

אפשר להשתמש ב-Google Domains

`sendHttpGet`

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

התוצאה שמתקבלת היא אובייקט שמכיל שלושה מפתחות: statusCode, headers ו-body. אם הבקשה נכשלה (למשל, כתובת URL לא חוקית, אין נתיב למארח, כשל במשא ומתן של SSL וכו'), אובייקט promise יידחה עם: {reason: 'failed'}. אם האפשרות timeout הוגדרה והבקשה הגיעה לזמן קצוב לתפוגה, ההבטחה תידחה עם: {reason: 'timed_out'}

דוגמה

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

תחביר

sendHttpGet(url[, options]);

פרמטרים

פרמטר	סוג	תיאור
`url`	מחרוזת	כתובת ה-URL שנכללת בבקשה.
`options`	object	אפשרויות בקשה אופציונליות. (ראו אפשרויות בהמשך).

אפשרויות

אפשרות	סוג	תיאור
`headers`	מחרוזת	כותרות בקשה נוספות.
`timeout`	number	זמן הקצוב לתפוגה, באלפיות השנייה, לפני שהבקשה מבוטלת. ברירת המחדל היא `15000`.
`authorization`	object	אובייקט הרשאה אופציונלי מהקריאה אל `getGoogleAuth` לצורך הכללה של כותרות הרשאה כששולחים בקשות אל `googleapis.com`.

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

send_http

`sendHttpRequest`

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

דוגמה

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

תחביר

sendHttpRequest(url[, options[, body]]);

פרמטרים

פרמטר	סוג	תיאור
`url`	מחרוזת	כתובת ה-URL שנכללת בבקשה.
`options`	object	אפשרויות בקשה אופציונליות. (ראו אפשרויות בהמשך).
`body`	מחרוזת	גוף הבקשה אופציונלי.

אפשרויות

אפשרות	סוג	תיאור
`headers`	מחרוזת	כותרות בקשה נוספות.
`method`	object	שיטת הבקשה. ברירת המחדל היא `GET`.
`timeout`	number	זמן הקצוב לתפוגה, באלפיות השנייה, לפני שהבקשה מבוטלת. ברירת המחדל היא `15000`.
`authorization`	object	אובייקט הרשאה אופציונלי מהקריאה אל `getGoogleAuth` לצורך הכללה של כותרות הרשאה כששולחים בקשות אל `googleapis.com`.

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

send_http

`sendPixelFromBrowser`

שליחת פקודה לדפדפן לטעינת כתובת ה-URL שצוינה כתג <img>. פרוטוקול הפקודות הזה נתמך ב-Google Tag ל-Google Analytics וב-Google Analytics: תגי אירוע GA לאינטרנט. חובה להגדיר את כתובת ה-URL של מאגר התגים בצד השרת. פרטים נוספים מופיעים בהוראות.

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

דוגמה:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

תחביר

sendPixelFromBrowser(url)

פרמטרים

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

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

send_pixel_from_browser

`setCookie`

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

כדי למחוק קובץ Cookie, צריך להגדיר קובץ Cookie עם אותה נתיב ודומיין שבהם נוצר קובץ ה-Cookie, ולהקצות לו ערך תפוגה מהעבר, למשל "Thu, 01 Jan 1970 00:00:00 GMT".

הערה: צריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

דוגמה

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

תחביר

setCookie(name, value[, options[, noEncode]]);

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	שם קובץ ה-Cookie. השם לא תלוי-רישיות.
`value`	מחרוזת	הערך של קובץ ה-Cookie.
`options`	object	מאפייני Cookie אופציונליים:domain, expires, fallbackDomain,httpOnly, max- age, path, secure, ו-sameSite. (ראו אפשרויות בהמשך).
`noEncode`	boolean	אם הערך הוא true, הערך של קובץ ה-Cookie לא יקודד. ברירת המחדל היא `false`.

אפשרויות

‫domain: המארח שקובץ ה-Cookie יישלח אליו. אם ממלאים בשדה את הערך המיוחד auto, המארח נקבע באופן אוטומטי באמצעות האסטרטגיה הבאה:
- ‫eTLD+1 של הכותרת Forwarded, אם היא קיימת.
- ‫eTLD+1 של הכותרת X-Forwarded-Host, אם היא קיימת.
- ‫eTLD+1 של הכותרת Host.
‫expires: משך החיים המקסימלי של קובץ ה-Cookie. הערך צריך להיות מחרוזת תאריך בפורמט UTC, למשל 'Sat, 26 Oct 1985 08:21:00 GMT'. אם גם expires וגם max-age מוגדרים, max-age מקבל עדיפות.
‫httpOnly: אוסר על JavaScript לגשת לקובץ ה-Cookie אם true.
‫max-age: מספר השניות עד שתוקף קובץ ה-Cookie יפוג. אם תזינו אפס או מספר שלילי, תוקף קובץ ה-Cookie יפוג באופן מיידי. אם גם expires וגם max-age מוגדרות, max-age מקבלת עדיפות.
‫path: נתיב שחייב להיות קיים בכתובת ה-URL המבוקשת, אחרת הדפדפן לא ישלח את כותרת ה-Cookie.
‫secure: אם הערך מוגדר ל-true, קובץ ה-Cookie נשלח לשרת רק כשמתבצעת בקשה מנקודת קצה מסוג https:.
‫sameSite: קובע שקובץ Cookie לא יישלח עם בקשות חוצות מקור. הערך חייב להיות 'strict', ‏'lax' או 'none'.

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

set_cookie

`setPixelResponse`

מגדיר את גוף התגובה ל-GIF בגודל 1x1, מגדיר את הכותרת Content-Type ל-image/gif, מגדיר כותרות של שמירת נתונים במטמון כך שסוכני משתמש לא ישמרו את התגובה במטמון, ומגדיר את סטטוס התגובה ל-200.

הערה: צריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setPixelResponse();

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

נדרשת הרשאה ל-access_response. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

‫headers – חובה לאפשר את המפתחות הבאים
- content-type
- cache-control
- expires
- pragma
body
status

`setResponseBody`

מגדיר את גוף התגובה לארגומנט.

הערה: צריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setResponseBody(body[, encoding]);

פרמטרים

פרמטר	סוג	תיאור
`body`	מחרוזת	הערך שיוגדר כגוף התגובה.
`encoding`	מחרוזת	קידוד התווים של גוף התגובה (ברירת המחדל היא `'utf8'`). הערכים הנתמכים כוללים `'ascii'`,‏ `'utf8'`,‏ `'utf16le'`,‏ `'ucs2'`,‏ `'base64'`,‏ `'latin1'`,‏ `'binary'` ו-`'hex'`.

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

נדרשת הרשאה ל-access_response. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

body

`setResponseHeader`

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

הערה: צריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setResponseHeader(name, value);

פרמטרים

פרמטר	סוג	תיאור
`name`	מחרוזת	שם הכותרת. שמות של כותרות HTTP הם לא תלויי אותיות רישיות, ולכן שם הכותרת יהיה באותיות קטנות.
`value`	מחרוזת undefined	ערך הכותרת. אם הערך הוא null או undefined, הכותרת בעלת השם מוסרת מהתשובה שתוחזר.

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

נדרשת הרשאה ל-access_response. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

headers

`setResponseStatus`

ההגדרה הזו קובעת את קוד הסטטוס של HTTP בתגובה שתוחזר.

הערה: צריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setResponseStatus(statusCode);

פרמטרים

פרמטר	סוג	תיאור
`statusCode`	number	קוד הסטטוס של HTTP שיוחזר.

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

נדרשת הרשאה ל-access_response. צריך להגדיר את ההרשאה כך שתאפשר גישה לפחות ל:

status

`sha256`

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

החתימה וההתנהגות של ה-API הזה זהות לאלה של API‏ sha256 למאגרי תגים באינטרנט. עם זאת, בתבניות בהתאמה אישית במאגרי תגים בצד השרת מומלץ להשתמש ב-API‏ sha256Sync כדי לפשט את הקוד.

דוגמה

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

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

תחביר

sha256(input, onSuccess, options = undefined);

פרמטרים

פרמטר	סוג	תיאור
`input`	מחרוזת	המחרוזת ליצירת הגיבוב.
`onSuccess`	function	הפונקציה נקראת עם התקציר שמתקבל, בקידוד base64, אלא אם אובייקט `options` מציין קידוד פלט שונה.
`options`	object	אובייקט אפשרויות אופציונלי לציון קידוד הפלט. אם מציינים את האובייקט, הוא צריך להכיל את המפתח `outputEncoding` עם ערך שהוא אחד מהערכים `base64` או `hex`.

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

ללא.

`sha256Sync`

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

דוגמה

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

תחביר

sha256Sync(input, options = undefined);

פרמטרים

פרמטר	סוג	תיאור
`input`	מחרוזת	המחרוזת ליצירת הגיבוב.
`options`	object	אובייקט אפשרויות אופציונלי לציון קידוד הפלט. אם מציינים את האובייקט, הוא צריך להכיל את המפתח `outputEncoding` עם ערך שהוא אחד מהערכים `base64` או `hex`.

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

ללא.

`templateDataStorage`

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

המונח 'data' (נתונים) בשם 'templateDataStorage' מתייחס לעובדה שאפשר לאחסן באמצעות ה-API הזה רק סוגי נתונים פשוטים שאינם פונקציות. כל הפונקציות או ההפניות לפונקציות שמועברות ל-API יישמרו במקום זאת כ-null.

תחביר

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

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

דוגמה

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

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

access_template_storage

`testRegex`

בודק מחרוזת מול ביטוי רגולרי שנוצר באמצעות createRegex API. הפונקציה מחזירה את הערך true אם יש התאמה לביטוי הרגולרי. אחרת, הפונקציה מחזירה את הערך false.

ביטוי רגולרי שנוצר עם הדגל הגלובלי הוא בעל מצב. פרטים נוספים זמינים במאמר בנושא RegExp.

דוגמה

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

תחביר

testRegex(regex, string);

פרמטרים

פרמטר	סוג	תיאור
`regex`	אובייקט	הביטוי הרגולרי לבדיקה, שמוחזר מ-createRegex API.
`string`	מחרוזת	מחרוזת לבדיקה.

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

ללא.

`toBase64`

מקודד מחרוזת כ-base64 או base64url. ברירת המחדל היא קידוד base64.

תחביר

toBase64(input, options);

פרמטרים

פרמטר	סוג	תיאור
`input`	מחרוזת	מחרוזת לקידוד.
`options`	object	אופציונלי: הגדרת API. (ראו אפשרויות בהמשך).

אפשרויות

אפשרות	סוג	תיאור	גירסת מינימום
`urlEncoding`	boolean	אם הערך הוא true, התוצאה תהיה מקודדת בפורמט `base64url`.	‫1.0.0

דוגמה

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

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

ללא.

`BigQuery`

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

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

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

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

תחביר

BigQuery.insert(connectionInfo, rows[, options]);

פרמטרים

פרמטר	סוג	תיאור
`connectionInfo`	object	הגדרה של המידע שנדרש כדי להתחבר לטבלת BigQuery. יש פרמטר אופציונלי אחד ושני פרמטרים שחובה להשתמש בהם: ‫`projectId` – אופציונלי מזהה הפרויקט ב-Google Cloud Platform. אם לא מציינים את `projectId`, הוא מאוחזר ממשתנה הסביבה `GOOGLE_CLOUD_PROJECT`, בתנאי שהגדרת ההרשאה `access_bigquery` למזהה הפרויקט מוגדרת ל-`*` או ל-`GOOGLE_CLOUD_PROJECT`. אם מאגר התגים בצד השרת פועל ב-Google Cloud, הערך של `GOOGLE_CLOUD_PROJECT` כבר יהיה מוגדר כמזהה הפרויקט ב-Google Cloud. ‫`datasetId` – מזהה קבוצת הנתונים ב-BigQuery. ‫`tableId` – מזהה הטבלה ב-BigQuery.
`rows`	מערך	השורות שרוצים להוסיף לטבלה.
`options`	object	אפשרויות אופציונליות לבקשה. האפשרויות הנתמכות הן: ignoreUnknownValues ו- skipInvalidRows. המערכת מתעלמת ממפתחות לא מוכרים של אפשרויות. (ראו אפשרויות בהמשך).

אפשרויות

פרמטר	סוג	תיאור
`ignoreUnknownValues`	boolean	אם הערך הוא `true`, המערכת מקבלת שורות שמכילות ערכים שלא תואמים לסכימה. המערכת מתעלמת מהערכים הלא מוכרים. ברירת המחדל היא `false`.
`skipInvalidRows`	boolean	אם הערך הוא `true`, כל השורות התקינות בבקשה יוכנסו, גם אם יש שורות לא תקינות. ברירת המחדל היא `false`.

דוגמאות לשגיאות

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

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

[{reason: 'invalid'}]

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

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

דוגמה

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

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

access_bigquery

`Firestore`

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

ה-API הזה תומך רק ב-Firestore במצב Native, ולא ב-Firestore במצב Datastore. בנוסף, ה-API תומך רק בשימוש במסד הנתונים שמוגדר כברירת מחדל.

`Firestore.read`

הפונקציה Firestore.read קוראת נתונים ממסמך Firestore ומחזירה promise שמוביל לאובייקט שמכיל שני מפתחות: id ו-data. אם המסמך לא קיים, אובייקט ה-promise נדחה עם אובייקט שמכיל מפתח reason ששווה ל-not_found.

תחביר

Firestore.read(path[, options]);

פרמטרים

פרמטר	סוג	תיאור
`path`	מחרוזת	הנתיב למסמך או לאוסף. השם לא יכול להתחיל או להסתיים ב-'/'.
`options`	object	אפשרויות בקשה אופציונליות. האפשרויות הנתמכות הן: projectId,‏ disableCache ו-transaction. המערכת מתעלמת ממפתחות לא מוכרים של אפשרויות. (ראו אפשרויות בהמשך).

אפשרויות

פרמטר	סוג	תיאור
`projectId`	מחרוזת	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מציינים את `projectId`, המערכת מאחזרת אותו ממשתנה הסביבה `GOOGLE_CLOUD_PROJECT`, בתנאי שהגדרת ההרשאה `access_firestore` למזהה הפרויקט מוגדרת ל-`*` או ל-`GOOGLE_CLOUD_PROJECT`. אם מאגר התגים בצד השרת פועל ב-Google Cloud, הערך של `GOOGLE_CLOUD_PROJECT` כבר יהיה מוגדר כמזהה הפרויקט ב-Google Cloud.
`disableCache`	boolean	אופציונלי. ההגדרה קובעת אם להשבית את המטמון. המטמון מופעל כברירת מחדל, והתוצאות יישמרו במטמון למשך משך הבקשה.
`transaction`	מחרוזת	אופציונלי. הערך שאוחזר מ-Firestore.runTransaction(). מציין שהפעולה תשמש בתוך טרנזקציה.

דוגמה

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

`Firestore.write`

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

תחביר

Firestore.write(path, input[, options]);

פרמטרים

פרמטר	סוג	תיאור
`path`	מחרוזת	הנתיב למסמך או לאוסף. השם לא יכול להתחיל או להסתיים ב-'/'.
`input`	object	הערך שייכתב במסמך. אם אפשרות המיזוג מוגדרת, ה-API ימזג את המפתחות מהקלט לתוך המסמך.
`options`	object	אפשרויות בקשה אופציונליות. האפשרויות הנתמכות הן: projectId,‏ merge ו-transaction. המערכת מתעלמת ממפתחות לא מוכרים של אפשרויות. (ראו אפשרויות בהמשך).

אפשרויות

פרמטר	סוג	תיאור
`projectId`	מחרוזת	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מציינים את `projectId`, המערכת מאחזרת אותו ממשתנה הסביבה `GOOGLE_CLOUD_PROJECT`, בתנאי שהגדרת ההרשאה `access_firestore` למזהה הפרויקט מוגדרת ל-`*` או ל-`GOOGLE_CLOUD_PROJECT`. אם מאגר התגים בצד השרת פועל ב-Google Cloud, הערך של `GOOGLE_CLOUD_PROJECT` כבר יהיה מוגדר כמזהה הפרויקט ב-Google Cloud.
`merge`	boolean	אופציונלי. אם הערך הוא `true`, המפתחות מהקלט ימוזגו עם המסמך. אחרת, השיטה תחליף את כל המסמך. ברירת המחדל היא `false`.
`transaction`	מחרוזת	אופציונלי. הערך שאוחזר מ-Firestore.runTransaction(). מציין שהפעולה תשמש בתוך טרנזקציה.

דוגמה

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

`Firestore.query`

הפונקציה Firestore.query שולחת שאילתה לאוסף הנתון ומחזירה אובייקט promise שמוביל למערך של מסמכי Firestore שתואמים לתנאי השאילתה. אובייקט המסמך של Firestore זהה לזה שמופיע למעלה בFirestore.read. אם אין מסמכים שתואמים לתנאי השאילתה, ההבטחה שמוחזרת תתממש כמערך ריק.

תחביר

Firestore.query(collection, queryConditions[, options]);

פרמטרים

פרמטר	סוג	תיאור
`collection`	מחרוזת	הנתיב לאוסף. השם לא יכול להתחיל או להסתיים ב-'/'.
`queryConditions`	מערך	מערך של תנאי שאילתה. כל שאילתה מגיעה בצורה של מערך עם שלושה ערכים: key,‏ operator ו-expectedValue. E.g.: ‪[[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. התנאים מחוברים באמצעות AND כדי ליצור את תוצאת השאילתה. רשימה של אופרטורים תואמים של שאילתות זמינה במאמר אופרטורים של שאילתות ב-Firestore.
`options`	object	אפשרויות בקשה אופציונליות. האפשרויות הנתמכות הן: projectId,‏ disableCache, limit ו-transaction. המערכת מתעלמת ממפתחות לא מוכרים של אפשרויות. (ראו אפשרויות בהמשך).

אפשרויות

פרמטר	סוג	תיאור
`projectId`	מחרוזת	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מציינים את `projectId`, המערכת מאחזרת אותו ממשתנה הסביבה `GOOGLE_CLOUD_PROJECT`, בתנאי שהגדרת ההרשאה `access_firestore` למזהה הפרויקט מוגדרת ל-`*` או ל-`GOOGLE_CLOUD_PROJECT`. אם מאגר התגים בצד השרת פועל ב-Google Cloud, הערך של `GOOGLE_CLOUD_PROJECT` כבר יהיה מוגדר כמזהה הפרויקט ב-Google Cloud.
`disableCache`	boolean	אופציונלי. ההגדרה קובעת אם להשבית את המטמון. המטמון מופעל כברירת מחדל, והתוצאות יישמרו במטמון למשך משך הבקשה.
`limit`	number	אופציונלי. משנה את המספר המקסימלי של התוצאות שמוחזרות על ידי השאילתה. ברירת המחדל היא 5.
`transaction`	מחרוזת	אופציונלי. הערך שאוחזר מ-Firestore.runTransaction(). מציין שהפעולה תשמש בתוך טרנזקציה.

דוגמה

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

`Firestore.runTransaction`

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

תחביר

Firestore.runTransaction(callback[, options]);

פרמטרים

פרמטר	סוג	תיאור
`callback`	function	פונקציית קריאה חוזרת שמופעלת עם מזהה עסקה מסוג מחרוזת. אפשר להעביר את מזהה העסקה לקריאות API מסוג קריאה, כתיבה או שאילתה. פונקציית הקריאה החוזרת הזו חייבת להחזיר אובייקט promise. הקריאה החוזרת עשויה לפעול עד שלוש פעמים לפני שהיא תיכשל.
`options`	object	אפשרויות בקשה אופציונליות. האפשרות הנתמכת היחידה היא projectId. המערכת מתעלמת ממפתחות לא מוכרים של אפשרויות. (ראו אפשרויות בהמשך).

אפשרויות

פרמטר	סוג	תיאור
`projectId`	מחרוזת	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מציינים את `projectId`, המערכת מאחזרת אותו ממשתנה הסביבה `GOOGLE_CLOUD_PROJECT`, בתנאי שהגדרת ההרשאה `access_firestore` למזהה הפרויקט מוגדרת ל-`*` או ל-`GOOGLE_CLOUD_PROJECT`. אם מאגר התגים בצד השרת פועל ב-Google Cloud, הערך של `GOOGLE_CLOUD_PROJECT` כבר יהיה מוגדר כמזהה הפרויקט ב-Google Cloud.

דוגמה

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

דוגמה לשגיאה

שגיאות זמינות בכל פונקציה של Firestore יידחו עם אובייקט שמכיל מפתח reason:

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

הסיבות לשגיאה יכולות לכלול, בין היתר, קודי שגיאה של Firestore API בארכיטקטורת REST.

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

access_firestore

`JSON`

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

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

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

דוגמה

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

תחביר

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

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

ללא.

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

פרמטרים

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

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

ללא.

`Messages`

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

`addMessageListener`

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

messageType:string
message:Object

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

תחביר

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

פרמטרים

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

דוגמה

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

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

נדרשת הרשאה ל-use_message. צריך להגדיר את ההרשאה כך שתאפשר לפחות:

סוג הודעה עם Usage של listen או listen_and_send.

`hasMessageListener`

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

תחביר

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

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

ללא.

`sendMessage`

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

תחביר

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

פרמטרים

פרמטר	סוג	תיאור
`messageType`	מחרוזת	סוג ההודעה שרוצים לשלוח. אם הערך הוא לא מחרוזת, הוא יומר למחרוזת.
`message`	object	ההודעה לשליחה. אם ההודעה לא תהיה אובייקט, ה-API לא יעשה שום דבר.

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

נדרשת הרשאה ל-use_message. צריך להגדיר את ההרשאה כך שתאפשר לפחות:

סוג הודעה עם Usage של listen_and_send או send.

`Object`

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

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

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

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

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

ה-method‏ 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

פרמטר	סוג	תיאור
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.

`Promise`

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

הפונקציונליות של הבטחות זהה לזו של הבטחות JavaScript. לכל מופע יש שלוש שיטות שמחזירות הבטחה (Promise) שמאפשרת פעולה נוספת כשההבטחה מתקיימת:

‫.then() – מטפל בפניות שנסגרו ובפניות שנדחו. הפונקציה מקבלת שני קולבקים כפרמטרים: אחד למקרה של הצלחה ואחד למקרה של כשל.
‫.catch() – מטפל רק בפניות שנדחו. מקבלת קריאה חוזרת אחת כפרמטר.
‫.finally() – מאפשרת להריץ קוד גם אם ה-Promise הותאם וגם אם הוא נדחה. מקבלת קריאה חוזרת אחת כפרמטר שמופעל ללא ארגומנט.

משתנה שמחזיר אובייקט promise שווה לערך שהאובייקט promise מחזיר, או לערך false אם האובייקט promise נדחה.

דוגמה

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

`Promise.all`

הפונקציה מחזירה הבטחה שאחת מהאפשרויות הבאות תתקיים:

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

תחביר

Promise.all(inputs);

פרמטרים

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

דוגמה

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

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

ללא.

`Promise.create`

יוצר אובייקט promise ששקול מבחינת הפונקציונליות לאובייקט promise של JavaScript.

תחביר

Promise.create(resolver);

פרמטרים

פרמטר	סוג	תיאור
`resolver`	function	פונקציה שמופעלת עם שתי פונקציות – resolve ו-reject. ההבטחה שמוחזרת תתממש או תידחה כשהפרמטר המתאים יופעל. הפונקציה מחזירה שגיאה אם resolver הוא לא פונקציה.

דוגמה

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

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

ללא.

בדיקת ממשקי API

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

`assertApi`

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

תחביר

assertApi(apiName)

פרמטרים

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

Matchers

Subject.wasCalled()
Subject.wasNotCalled()
Subject.wasCalledWith(...expected)
Subject.wasNotCalledWith(...expected)

דוגמאות

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

`assertThat`

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

תחביר

assertThat(actual, opt_message)

פרמטרים

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

Matchers

Matcher	תיאור
`isUndefined()`	מציין שהנושא הוא `undefined`.
`isDefined()`	מציין שהנושא הוא לא `undefined`.
`isNull()`	מציין שהנושא הוא `null`.
`isNotNull()`	מציין שהנושא הוא לא `null`.
`isFalse()`	מציין שהנושא הוא `false`.
`isTrue()`	מציין שהנושא הוא `true`.
`isFalsy()`	בודקת שהנושא הוא ערך שהוא false. הערכים שהמערכת מחשיבה כ-falsy הם: `undefined`,‏ `null`,‏ `false`, `NaN`,‏ 0 ו-'' (מחרוזת ריקה).
`isTruthy()`	הפונקציה מאמתת שהנושא הוא ערך שהוא true. הערכים שהמערכת מחשיבה כ-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)`	הפונקציה בודקת אם הנושא הוא מערך או מחרוזת באורך הנתון. ההצהרה תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
`isEmpty()`	בודקת שהנושא הוא מערך או מחרוזת ריקים (האורך הוא 0). ההצהרה תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
`isNotEmpty()`	הטענה היא שהנושא הוא מערך או מחרוזת שלא ריקים (האורך גדול מ-0). הטענה תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
`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` הוא כל דבר אחר מלבד פונקציה, המערכת מחזירה את הערך הזה במקום את Sandboxed API.

דוגמאות

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

`mockObject`

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

תחביר

mockObject(apiName, objectMock);

פרמטרים

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

דוגמאות

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

`runCode`

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

תחביר

runCode(data)

פרמטרים

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

ערך מוחזר

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

דוגמה

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

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

addEventCallback

callLater

claimRequest

computeEffectiveTldPlusOne

createRegex

decodeUri

decodeUriComponent

encodeUri

encodeUriComponent

extractEventsFromMpv1

extractEventsFromMpv2

fromBase64

generateRandom

getAllEventData

getClientName

getContainerVersion

getCookieValues

getEventData

getGoogleAuth

getGoogleScript

getRemoteAddress

getRequestBody

getRequestHeader

getRequestMethod

getRequestPath

getRequestQueryParameter

getRequestQueryParameters

getRequestQueryString

getTimestamp

getTimestampMillis

getType

hmacSha256

isRequestMpv1

isRequestMpv2

logToConsole

makeInteger

makeNumber

makeString

makeTableMap

parseUrl

returnResponse

runContainer

sendEventToGoogleAnalytics

sendHttpGet

sendHttpRequest

sendPixelFromBrowser

setCookie

setPixelResponse

setResponseBody

setResponseHeader

setResponseStatus

sha256

sha256Sync

templateDataStorage

testRegex

toBase64

BigQuery

Firestore

Firestore.read

Firestore.write

Firestore.query

Firestore.runTransaction

JSON

Math

Messages

addMessageListener

hasMessageListener

sendMessage

Object

Promise

Promise.all

Promise.create

בדיקת ממשקי API

assertApi

assertThat

fail

mock

mockObject

runCode

ממשקי API לתיוג בצד השרת

`addEventCallback`

`callLater`

`claimRequest`

`computeEffectiveTldPlusOne`

`createRegex`

`decodeUri`

`decodeUriComponent`

`encodeUri`

`encodeUriComponent`

`extractEventsFromMpv1`

`extractEventsFromMpv2`

`fromBase64`

`generateRandom`

`getAllEventData`

`getClientName`

`getContainerVersion`

`getCookieValues`

`getEventData`

`getGoogleAuth`

`getGoogleScript`

`getRemoteAddress`

`getRequestBody`

`getRequestHeader`

`getRequestMethod`

`getRequestPath`

`getRequestQueryParameter`

`getRequestQueryParameters`

`getRequestQueryString`

`getTimestamp`

`getTimestampMillis`

`getType`

`hmacSha256`

`isRequestMpv1`

`isRequestMpv2`

`logToConsole`

`makeInteger`

`makeNumber`

`makeString`

`makeTableMap`

`parseUrl`

`returnResponse`

`runContainer`

`sendEventToGoogleAnalytics`

`sendHttpGet`

`sendHttpRequest`

`sendPixelFromBrowser`

`setCookie`

`setPixelResponse`

`setResponseBody`

`setResponseHeader`

`setResponseStatus`

`sha256`

`sha256Sync`

`templateDataStorage`

`testRegex`

`toBase64`

`BigQuery`

`Firestore`

`Firestore.read`

`Firestore.write`

`Firestore.query`

`Firestore.runTransaction`

`JSON`

`Math`

`Messages`

`addMessageListener`

`hasMessageListener`

`sendMessage`

`Object`

`Promise`

`Promise.all`

`Promise.create`

`assertApi`

`assertThat`

`fail`

`mock`

`mockObject`

`runCode`