ממשקי 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 הזה לפני שהוא קורא ל-runContainer API.

דוגמה

const claimRequest = require('claimRequest');

claimRequest();

תחביר

claimRequest();

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

ללא.

`computeEffectiveTldPlusOne`

הפונקציה מחזירה את הדומיין ברמה העליונה (TLD) + 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` (global) וב-`i` (ignore case). המערכת מתעלמת מכל שאר התווים.

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

ללא.

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

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

דוגמה

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

ההבטחה תמומש כאובייקט שמכיל שני מפתחות: 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`

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

דוגמה

const isRequestMpv1 = require('isRequestMpv1');

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

תחביר

isRequestMpv1();

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

ללא.

`isRequestMpv2`

הפונקציה מחזירה את הערך true אם הבקשה הנכנסת היא בקשה של Measurement Protocol V2, או 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`	כל סוג	הערך להמרה.

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

ללא.

`makeNumber`

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

תחביר

makeNumber(value);

פרמטרים

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

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

ללא.

`makeString`

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

תחביר

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` שהומר.

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

ללא.

`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 4, מבוסס על מזהה המדידה בנתוני האירועים.

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

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

התוצאה שמתקבלת היא אובייקט שמכיל שלושה מפתחות: statusCode, headers ו-body. אם הבקשה נכשלה (למשל, כתובת URL לא תקינה, אין נתיב למארח, כשל במשא ומתן של SSL וכו'), ההבטחה תידחה עם: {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 עבור GA4 וב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`	‫string 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.

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

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

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

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

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

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

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

תחביר

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

פרמטרים

Object.keys

פרמטר	סוג	תיאור
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, שמאפשר לבצע פעולה נוספת כש-Promise מסתיים:

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

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

דוגמה

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`

יוצרת הבטחה ששקולה מבחינת הפונקציונליות להבטחה של 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`	כל	הערך שבו יש להשתמש בבדיקות של Fluent.
`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 APIs. אפשר להשתמש ב-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`