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

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

---

addEventCallback

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

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

תחביר

const addEventCallback = require('addEventCallback');

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

פרמטרים

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

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

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

ללא.

---

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 הוא בדרך כלל הדומיין ברמה הגבוהה ביותר שבו ניתן להגדיר .

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

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

ללא.

---

createRegex

יצירת מכונה של ביטוי רגולרי (regex) חדש ומחזירה אותו בתוך אובייקט. אי אפשר לגשת ישירות לביטוי הרגולרי. עם זאת, אפשר להעביר אותו ל-API של testRegex, 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	string	הטקסט של הביטוי הרגולרי.
flags	string	מחרוזת אופציונלית שמכילה את הדגלים של הביטוי הרגולרי שנוצר. המערכת תומכת ב-'g' (גלובלי) וב-'i' (לא תלוי-רישיות). כל שאר התווים מתעלמים ממנו בשקט.

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

ללא.

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

2.0.0

---

decodeUri

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

דוגמה

const decodeUri = require('decodeUri');

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

תחביר

decodeUri(encoded_uri);

פרמטרים

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

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

ללא.

---

decodeUriComponent

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

דוגמה

const decodeUriComponent = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component);

פרמטרים

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

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

ללא.

---

encodeUri

פונקציה זו מחזירה מזהה משאבים אחיד (URI) מקודד באמצעות Escing Special תווים. הפונקציה מחזירה string שמייצגת את המחרוזת שצוינה בקידוד בתור URI.

דוגמה

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

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

תחביר

encodeUri(uri);

פרמטרים

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

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

ללא.

---

encodeUriComponent

פונקציה זו מחזירה מזהה משאבים אחיד (URI) מקודד באמצעות Escing Special תווים. הפונקציה מחזירה string שמייצגת את המחרוזת שסופקה עם הקידוד של URI.

דוגמה

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

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

תחביר

encodeUriComponent(str);

פרמטרים

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

דוגמה

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	string	מחרוזת בקידוד Base64.

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא.

---

generateRandom

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

דוגמה

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

תחביר

generateRandom(min, max);

פרמטרים

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

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

ללא.

---

getAllEventData

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

תחביר

getAllEventData();

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

read_event_data

---

getClientName

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

תחביר

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	string	השם של קובץ ה-cookie.
noDecode	בוליאני	אם הערך שלו הוא 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 API כדי בקשת גישה עבור.

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

נדרשת ההרשאה use_google_credentials. ההרשאה חייבת להיות מוגדר עם היקף מותר אחד או יותר.

---

getGoogleScript

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

אפשרויות

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

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

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

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

• מתן הרשאה ל-Google Domains

---

getRemoteAddress

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

תחביר

getRemoteAddress();

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

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

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

---

getRequestBody

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

תחביר

getRequestBody();

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

read_request

---

getRequestHeader

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

דוגמה

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

תחביר

getRequestHeader(headerName);

פרמטרים

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

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

read_request

---

getRequestMethod

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

דוגמה

const getRequestMethod = require('getRequestMethod');

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

תחביר

getRequestMethod();

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

ללא.

---

getRequestPath

מחזירה את נתיב הבקשה בלי מחרוזת השאילתה. לדוגמה, אם כתובת האתר היא '/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

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

דוגמה

const getRequestQueryParameter = require('getRequestQueryParameter');

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

תחביר

getRequestQueryParameter(name);

פרמטרים

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

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

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.

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

תחביר

getTimestamp();

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

ללא.

---

getTimestampMillis

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

תחביר

getTimestampMillis();

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

ללא.

---

getType

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

סוג הקלט	הערך שהוחזר
string	'string'
number	'number'
בוליאני	'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, בפורמט הבא:

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

הערכים הם מפתחות HMAC בקידוד base64.

דוגמה

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	string	הנתונים לחישוב ערך ה-HMAC.
keyId	string	מזהה מפתח מקובץ מפתח ה-JSON שמפנה אל .
options	אובייקט	הגדרה אופציונלית של ה-API. (ראו אפשרויות שמופיעות למטה.)

אפשרויות

אפשרות	סוג	תיאור
outputEncoding	string	מציינת את פורמט הקידוד של של הערך המוחזר. הפורמטים הנתמכים הם 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. ב-Logs Explorer, מריצים את השאילתה logName =~ "stdout" כדי לראות את רשומות היומן שנוצר על ידי ה-API הזה.

דוגמה

const logToConsole = require('logToConsole');

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

תחביר

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

פרמטרים

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

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

logging

---

makeInteger

ממירה את הערך הנתון ל-number (שלם).

תחביר

makeInteger(value);

פרמטרים

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

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

ללא.

---

makeNumber

ממירה את הערך הנתון ל-number.

תחביר

makeNumber(value);

פרמטרים

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

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

ללא.

---

makeString

מחזירה את הערך הנתון כ-string.

תחביר

makeString(value);

פרמטרים

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

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

ללא.

---

makeTableMap

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

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

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

למפה:

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

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

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName);

פרמטרים

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

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

ללא.

---

parseUrl

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

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

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

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

דוגמה

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

תחביר

parseUrl(url);

פרמטרים

פרמטר	סוג	תיאור
url	string	כתובת ה-URL המלאה שתנותח.

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

ללא.

---

returnResponse

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

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

תחביר

returnResponse();

דוגמה

אפשר לעיין בדוגמה של runContainer.

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

return_response

---

runContainer

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

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

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

run_container

---

sendEventToGoogleAnalytics

שולחת אירוע יחיד באמצעות Common Event Data ל-Google Analytics ומחזירה הבטחה שמפנה לאובייקט עם מפתח location או דוחה לאובייקט עם מפתח reason. היעד, אוניברסלי מערכת Analytics או 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	אובייקט	האירוע בפורמט סכימה מאוחדת.

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

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

• מתן הרשאה ל-Google Domains

---

sendHttpGet

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

התוצאה שטופלה היא אובייקט שמכיל שלושה מפתחות: 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	string	כתובת ה-URL המבוקשת.
options	אובייקט	אפשרויות אופציונליות לבקשות. (ראו אפשרויות שמופיעות למטה.)

אפשרויות

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

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

send_http

---

sendHttpRequest

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

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

דוגמה

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	string	כתובת ה-URL המבוקשת.
options	אובייקט	אפשרויות אופציונליות לבקשות. (ראו אפשרויות שמופיעות למטה.)
body	string	גוף הבקשה אופציונלי.

אפשרויות

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

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

send_http

---

sendPixelFromBrowser

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

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

דוגמה:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

תחביר

sendPixelFromBrowser(url)

פרמטרים

פרמטר	סוג	תיאור
url	string	כתובת ה-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	string	שם קובץ ה-cookie. השם לא תלוי-רישיות.
value	string	הערך של קובץ ה-cookie
options	אובייקט	מאפיינים אופציונליים של קובצי Cookie:דומיין, יפוג, fallbackDomain,httpOnly, max- גיל, path, מאובטח, ו-sameSite. (ראו אפשרויות, למטה.)
noEncode	בוליאני	אם הערך הוא 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 נשלח לשרת רק כאשר נשלחת מנקודת קצה (endpoint) 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	string	הערך שיש להגדיר כגוף התגובה.
encoding	string	קידוד התווים של גוף התגובה (ברירת המחדל היא 'utf8'). הערכים הנתמכים כוללים את 'ascii', 'utf8', 'utf16le', 'ucs2' 'base64', 'latin1', 'binary', ו-'hex'.

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

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

• body

---

setResponseHeader

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

לתשומת ליבך, צריך לקרוא ל-returnResponse לצורך התגובה ל- יישלחו בחזרה ללקוח.

תחביר

setResponseHeader(name, value);

פרמטרים

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

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

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

• headers

---

setResponseStatus

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

לתשומת ליבך, צריך לקרוא ל-returnResponse לצורך התגובה ל- יישלחו בחזרה ללקוח.

תחביר

setResponseStatus(statusCode);

פרמטרים

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

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

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

• status

---

sha256

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

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

דוגמה

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

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

ללא.

---

templateDataStorage

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

ה"נתונים" בשם '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

בדיקת מחרוזת מול ביטוי רגולרי שנוצר באמצעות API של createRegex. הפונקציה מחזירה את הערך 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	string	מחרוזת בדיקה לבדיקה.

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

ללא.

---

toBase64

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

תחביר

toBase64(input, options);

פרמטרים

פרמטר	סוג	תיאור
input	string	המחרוזת לקידוד.
options	אובייקט	הגדרה אופציונלית של ה-API. (ראו אפשרויות שמופיעות למטה.)

אפשרויות

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

דוגמה

const toBase64 = require('toBase64');

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

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

ללא.

---

BigQuery

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

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

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

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

תחביר

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

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

פרמטר	סוג	תיאור
ignoreUnknownValues	בוליאני	אם המדיניות מוגדרת לערך true, צריך לקבל שורות שמכילות ערכים שלא תואמים לסכימה. המערכת מתעלמת מהערכים הלא ידועים. ברירות מחדל אל false.
skipInvalidRows	בוליאני	אם המדיניות מוגדרת לערך 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 in מצב מאגר נתונים. בנוסף, ה-API תומך רק בשימוש במסד הנתונים שמוגדר כברירת מחדל.

Firestore.read

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

תחביר

Firestore.read(path[, options]);

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

פרמטר	סוג	תיאור
projectId	string	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא צוין, המאפיין הערך projectId אוחזר ממשתנה הסביבה GOOGLE_CLOUD_PROJECT כל עוד access_firestore הגדרת ההרשאה עבור מזהה הפרויקט היא * או GOOGLE_CLOUD_PROJECT. אם מאגר התגים בצד השרת פועל Google Cloud, GOOGLE_CLOUD_PROJECT כבר מוגדר בתור את המזהה של הפרויקט ב-Google Cloud.
disableCache	בוליאני	אופציונלי. המדיניות קובעת אם להשבית את המטמון או לא. השמירה במטמון מופעלת כברירת מחדל, והיא שומרת במטמון את התוצאות משך הזמן של הבקשה.
transaction	string	אופציונלי. הערך שאוחזר מ- 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	string	הנתיב למסמך או לאוסף. לא יכול להתחיל או להסתיים ב- '/'.
input	אובייקט	הערך שיש לכתוב במסמך. אם אפשרות המיזוג מוגדרת, ה-API ימזג את המפתחות מהקלט עם המסמך.
options	אובייקט	אפשרויות אופציונליות לבקשות. האפשרויות הנתמכות הן: projectId, Merge עסקה. המערכת מתעלמת ממפתחות של אפשרויות לא מוכרים. (ראו אפשרויות, למטה.)

פרמטר	סוג	תיאור
projectId	string	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא צוין, המאפיין הערך projectId אוחזר ממשתנה הסביבה GOOGLE_CLOUD_PROJECT כל עוד access_firestore הגדרת ההרשאה עבור מזהה הפרויקט היא * או GOOGLE_CLOUD_PROJECT. אם מאגר התגים בצד השרת פועל Google Cloud, GOOGLE_CLOUD_PROJECT כבר מוגדר בתור את המזהה של הפרויקט ב-Google Cloud.
merge	בוליאני	אופציונלי. אם מוגדר true, לאחר מכן ממזגים את המפתחות מהקלט עם המסמך, אחרת, השיטה תבטל את המסמך כולו. ברירת המחדל היא false
transaction	string	אופציונלי. הערך שאוחזר מ- 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 מפעילה שאילתה על האוסף הנתון ומחזירה מבטיח למערך מסמכי Firestore שתואמים לשאילתה את התנאים וההגבלות. אובייקט המסמך של Firestore זהה לזה שצוין למעלה ב- Firestore.read אם אין מסמכים שתואמים לתנאי השאילתה, ההבטחה שמוחזרת תהפוך למערך ריק.

תחביר

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

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

פרמטר	סוג	תיאור
projectId	string	אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא צוין, המאפיין הערך projectId אוחזר ממשתנה הסביבה GOOGLE_CLOUD_PROJECT כל עוד access_firestore הגדרת ההרשאה עבור מזהה הפרויקט היא * או GOOGLE_CLOUD_PROJECT. אם מאגר התגים בצד השרת פועל Google Cloud, GOOGLE_CLOUD_PROJECT כבר מוגדר בתור את המזהה של הפרויקט ב-Google Cloud.
disableCache	בוליאני	אופציונלי. המדיניות קובעת אם להשבית את המטמון או לא. השמירה במטמון מופעלת כברירת מחדל, והיא שומרת במטמון את התוצאות משך הזמן של הבקשה.
limit	number	אופציונלי. שינוי המספר המקסימלי של תוצאות שהוחזרו על ידי ברירת המחדל של השאילתה היא 5.
transaction	string	אופציונלי. הערך שאוחזר מ- 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 הזה מחזיר הבטחה שמפנה למערך של מזהי מסמכים, לכל פעולת כתיבה, אם העסקה בוצעה בהצלחה, והיא תידחה עם השגיאה אם היא תיכשל.

תחביר

Firestore.runTransaction(callback[, options]);

פרמטרים

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

פרמטר	סוג	תיאור
projectId	string	אופציונלי. מזהה הפרויקט ב-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.
  }
});

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

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

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

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

1. messageType:string
2. message:Object

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

תחביר

const addMessageListener = require('addMessageListener');

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

פרמטרים

פרמטר	סוג	תיאור
messageType	string	סוג ההודעה להאזנה. אם הערך אינו מחרוזת, הוא יהיה שנכפה למחרוזת.
callback	פונקציה	הקריאה החוזרת (callback) שתרוץ כאשר הודעה מסוג ההודעה הרלוונטי היא נשלח. אם הקריאה החוזרת היא לא פונקציה, ה-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	string	סוג ההודעה שצריך לשלוח. אם הערך אינו מחרוזת, הוא יאופס למחרוזת.
message	אובייקט	ההודעה שצריך לשלוח. אם ההודעה היא לא אובייקט, ה-API לא יבצע כל פעולה.

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

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

• סוג הודעה עם Usage מתוך listen_and_send או send.

---

Object

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

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

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

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

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

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

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

תחביר

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

פרמטרים

Object.keys

פרמטר	סוג	תיאור
objectInput	כלשהו	האובייקט שהמפתחות שלו לספירה. אם הקלט הוא לא אובייקט, יאולץ לאובייקט.

Object.values

פרמטר	סוג	תיאור
objectInput	כלשהו	האובייקט שאת הערכים שלו לספירה. אם הקלט אינו אובייקט, הוא ייאכף לאובייקט.

Object.entries

פרמטר	סוג	תיאור
objectInput	כלשהו	האובייקט שיש לספור צמדי מפתח/ערך שלו. אם הקלט לא הוא ייאכף לאובייקט.

Object.freeze

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

Object.delete

פרמטר	סוג	תיאור
objectInput	כלשהו	האובייקט שאת המפתח שלו צריך למחוק.
keyToDelete	string	המפתח ברמה העליונה למחיקה.

דוגמה

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

---

Promise

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

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

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

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

דוגמה

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	string	שם ה-API לבדיקה. אותה מחרוזת שהועברה אל require()

התאמות

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

דוגמאות

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

---

assertThat

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

תחביר

assertThat(actual, opt_message)

פרמטרים

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

התאמות

תואם	תיאור
isUndefined()	מצהיר/ה שהנושא הוא undefined.
isDefined()	מצהיר/ה שהנושא אינו undefined.
isNull()	מצהיר/ה שהנושא הוא null.
isNotNull()	מצהיר/ה שהנושא אינו null.
isFalse()	מצהיר/ה שהנושא הוא false.
isTrue()	מצהיר/ה שהנושא הוא true.
isFalsy()	טוען שהנושא הוא חשוד. ערכי Falsy הם undefined, null, false NaN, 0 וגם '' (מחרוזת ריקה).
isTruthy()	טוען שהנושא ברור. ערכי Falsy הם undefined, null, false NaN, 0 וגם '' (מחרוזת ריקה).
isNaN()	מצהירה שהנושא הוא הערך NaN.
isNotNaN()	מצהירה שהנושא הוא כל ערך מלבד NaN.
isInfinity()	מצהיר שהנושא הוא אינסוף חיובי או שלילי.
isNotInfinity()	מצהיר/ה שהנושא הוא כל ערך מלבד חיובי או שלילי אינסוף.
isEqualTo(expected)	מצהירה שהנושא שווה לערך הנתון. זהו ערך ולא השוואה בין הפניות. התוכן של אובייקטים ומערכים בהשוואה באופן רקורסיבי.
isNotEqualTo(expected)	מצהירה שהנושא לא שווה לערך הנתון. זהו השוואת ערכים, ולא השוואה של הפניות. התוכן של אובייקטים השוואה בין מערכים באופן רקורסיבי.
isAnyOf(...expected)	מצהירה שהנושא שווה לאחד מהערך הנתון. זהו השוואת ערכים, ולא השוואה של הפניות. התוכן של אובייקטים השוואה בין מערכים באופן רקורסיבי.
isNoneOf(...expected)	מצהירה שהנושא לא שווה לאף אחד מהערכים הנתונים. הזה היא השוואת ערכים, ולא השוואה של הפניות. תוכן של אובייקטים ומערכים מושוכים באופן רקורסיבי.
isStrictlyEqualTo(expected)	מצהיר/ה שהנושא שווה לחלוטין (===) בערך הנתון.
isNotStrictlyEqualTo(expected)	מצהיר/ה שהנושא לא שווה לחלוטין (!==) ל- בערך הנתון.
isGreaterThan(expected)	מצהיר/ה שהנושא גדול מ (>) הנתון בהשוואה לפי סדר מסוים.
isGreaterThanOrEqualTo(expected)	מצהיר/ה שהנושא גדול מ- או שווה ל- (>=) הערך הנתון בהשוואה לפי סדר.
isLessThan(expected)	מצהיר/ה שהנושא קטן מהערך (<) שצוין בהשוואה לפי סדר מסוים.
isLessThanOrEqualTo(expected)	מצהירה שהנושא קטן מ- או שווה לו (<=) בערך הנתון בהשוואה לפי סדר.
contains(...expected)	מצהירה שהנושא הוא מערך או מחרוזת שמכילים את כל של הערכים הנתונים בכל סדר שהוא. זוהי השוואת ערכים, לא הפניה להשוואה. מתבצעת השוואה בין התוכן של אובייקטים ומערכים רקורסיביות.
doesNotContain(...expected)	מצהירה שהנושא הוא מערך או מחרוזת שלא מכילים אף אחד בין הערכים הנתונים. זוהי השוואת ערכים, ולא השוואת ערכים. מתבצעת השוואה רקורסיבית בין התוכן של אובייקטים ומערכים.
containsExactly(...expected)	מצהירה שהנושא הוא מערך שמכיל את כל הערכים בכל סדר שהוא. ללא ערכים אחרים. זוהי השוואת ערכים, ולא השוואה בין הפניות. מתבצעת השוואה בין התוכן של אובייקטים ומערכים רקורסיביות.
doesNotContainExactly(...expected)	מצהירה שהנושא הוא מערך שמכיל קבוצה אחרת של ערכים מהערכים הנתונים בכל סדר שהוא. זוהי השוואת ערכים, ולא השוואה של הפניות. התוכן של אובייקטים ומערכים באופן רקורסיבי.
hasLength(expected)	מצהירה שהנושא הוא מערך או מחרוזת באורך הנתון. טענת הנכוֹנוּת (assertion) תמיד תיכשל אם הערך הוא לא מערך או מחרוזת.
isEmpty()	טוענת שהנושא הוא מערך או מחרוזת ריקים (length =) 0). טענת הנכוֹנוּת (assertion) תמיד תיכשל אם הערך הוא לא מערך או String.
isNotEmpty()	מצהירה שהנושא הוא מערך או מחרוזת לא ריקה (אורך > 0). טענת הנכוֹנוּת (assertion) תמיד תיכשל אם הערך הוא לא מערך או מחרוזת.
isArray()	מצהירה שסוג הנושא הוא מערך.
isBoolean()	מצהירה שסוג הנושא הוא בוליאני.
isFunction()	מצהיר/ה שסוג הנושא הוא פונקציה.
isNumber()	מצהיר/ה שסוג הנושא הוא מספר.
isObject()	מצהיר/ה שסוג הנושא הוא אובייקט.
isString()	מצהיר/ה שסוג הנושא הוא מחרוזת.

דוגמאות

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

---

fail

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

תחביר

fail(opt_message);

פרמטרים

פרמטר	סוג	תיאור
opt_message	string	טקסט אופציונלי של הודעת שגיאה.

דוגמה

fail('This test has failed.');

---

mock

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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

---

mockObject

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

תחביר

mockObject(apiName, objectMock);

פרמטרים

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

דוגמאות

const storage = {};
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	אובייקט	אובייקט נתונים לשימוש בבדיקה.

ערך החזרה

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

דוגמה

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

---