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

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

addEventCallback

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

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

תחביר

const addEventCallback = require('addEventCallback');

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

פרמטרים

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

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

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

דוגמה

בתוכנת אימייל:

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

claimRequest();

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

בתג:

const addEventCallback = require('addEventCallback');

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

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

read_event_metadata

callLater

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

דוגמה

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

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

תחביר

callLater(function)

פרמטרים

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

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

ללא.

claimRequest

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

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

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

דוגמה

const claimRequest = require('claimRequest');

claimRequest();

תחביר

claimRequest();

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

ללא.

computeEffectiveTldPlusOne

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

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

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

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

ללא.

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

2.0.0

decodeUri

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

דוגמה

const decodeUri = require('decodeUri');

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

תחביר

decodeUri(encoded_uri);

פרמטרים

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

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

ללא.

decodeUriComponent

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

דוגמה

const decodeUriComponent = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component);

פרמטרים

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

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

ללא.

encodeUri

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

דוגמה

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

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

תחביר

encodeUri(uri);

פרמטרים

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

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

ללא.

encodeUriComponent

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

דוגמה

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

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

תחביר

encodeUriComponent(str);

פרמטרים

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

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

ללא.

extractEventsFromMpv1

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

דוגמה

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

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

תחביר

extractEventsFromMpv1();

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

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

  • body
  • query parameters

extractEventsFromMpv2

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

דוגמה

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

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

תחביר

extractEventsFromMpv2();

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

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

  • body
  • query parameters

fromBase64

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

תחביר

fromBase64(base64EncodedString);

פרמטרים

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

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא.

generateRandom

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

דוגמה

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

תחביר

generateRandom(min, max);

פרמטרים

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

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

ללא.

getAllEventData

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

תחביר

getAllEventData();

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

read_event_data

getAnonymizedIpAddress

מחזירה ייצוג של מחרוזת אנונימית של כתובת ה-IP שממנה הגיעה הבקשה.

בכתובות IPv4, האוקטט האחרון מוסתר ל-0 (לדוגמה, 198.51.100.42 הופכת ל-198.51.100.0). בכתובות IPv6, ‏80 הביטים האחרונים מוסתרים לאפסים, ו-48 הביטים הראשונים נשמרים (לדוגמה, 2001:db8:cafe:1234:5678:90ab:cdef:1234 הופכת ל-2001:db8:cafe::).

הפונקציה מחזירה את הערך "::" אם כתובת ה-IP לא תקינה או שלא ניתן לפתור אותה, כך שתמיד בטוח להשתמש בתוצאה בתור ip_override.

דוגמה

const getAnonymizedIpAddress = require('getAnonymizedIpAddress');

const anonymizedIp = getAnonymizedIpAddress();

תחביר

getAnonymizedIpAddress();

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

user_ip

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

תחביר

getEventData(keyPath);

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

read_event_data

getGoogleAuth

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

דוגמה

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

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

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

תחביר

getGoogleAuth(scopes);

פרמטרים

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

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

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

getGoogleScript

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

ה-promise יחזיר אובייקט שמכיל שני מפתחות: script ו-metadata. אם הבקשה נכשלת, ה-promise יידחה עם מפתח 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 any אם הערך הוא true, המערכת מבקשת ומחזירה את גרסת ניפוי הבאגים של סקריפט המדידה.
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

הפונקציה מחזירה את גוף הבקשה בתור string, אם הוא קיים, או 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

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

תחביר

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 any ערך הקלט.

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

ללא.

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

דוגמה

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 הזה נקרא במהלך הפעלת מאגר, המאגר מופעל שוב.

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

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

run_container

sendEventToGoogleAnalytics

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

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

דוגמה

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

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

תחביר

sendEventToGoogleAnalytics(event);

פרמטרים

פרמטר סוג תיאור
event object האירוע בפורמט סכימה מאוחדת.

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

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

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

sendHttpGet

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

התוצאה שמתקבלת היא אובייקט שמכיל שלושה מפתחות: statusCode,‏ headers ו-body. אם הבקשה נכשלה (למשל, כתובת URL לא חוקית, אין נתיב למארח, כשל במשא ומתן על SSL וכו'), ההבטחה תידחה עם: {reason: 'failed'}. אם האפשרות timeout הוגדרה והבקשה נכשלה בגלל זמן קצוב לתפוגה, ה-promise יידחה עם: {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 שצוינה, והחזרת הבטחה שמתקיימת עם התגובה כשהבקשה מסתיימת או כשהזמן הקצוב לתפוגה חולף.

התוצאה שמתקבלת היא אובייקט שמכיל שלושה מפתחות: statusCode,‏ headers ו-body. אם הבקשה נכשלה (למשל, כתובת URL לא חוקית, אין נתיב למארח, כשל במשא ומתן על SSL וכו'), ההבטחה תידחה עם: {reason: 'failed'}. אם האפשרות timeout הוגדרה והבקשה נכשלה בגלל זמן קצוב לתפוגה, ה-promise יידחה עם: {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 מחרוזת כתובת ה-URL שנכללת בבקשה.
options object אפשרויות בקשה אופציונליות. (ראו אפשרויות בהמשך).
body מחרוזת גוף בקשה אופציונלי.

אפשרויות

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

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

send_http

sendPixelFromBrowser

שליחת פקודה לדפדפן לטעון את כתובת ה-URL שצוינה כתג <img>. פרוטוקול הפקודות הזה נתמך בתג Google Tag ל-Google Analytics ובתגי האינטרנט Google Analytics: GA Event. צריך להגדיר את כתובת ה-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: אם הערך הוא true, אסור ל-JavaScript לגשת לקובץ ה-Cookie.

  • ‫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 מחרוזת הערך שיוגדר כגוף התגובה.
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 או לא מוגדר, הכותרת בעלת השם תימחק מהתגובה שתתקבל.

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

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

  • headers

setResponseStatus

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

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

תחביר

setResponseStatus(statusCode);

פרמטרים

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

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

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

  • status

sha256

מחשב את תקציר SHA-256 של הקלט ומפעיל קריאה חוזרת (callback) עם התקציר המקודד ב-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

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

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

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

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

תחביר

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

פרמטרים

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

אפשרויות

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

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

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

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

[{reason: 'invalid'}]

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

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

דוגמה

const BigQuery = require('BigQuery');

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

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

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

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

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

access_bigquery

Firestore

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

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

Firestore.read

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

תחביר

Firestore.read(path[, options]);

פרמטרים

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

אפשרויות

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

דוגמה

const Firestore = require('Firestore');

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

Firestore.write

הפונקציה Firestore.write כותבת נתונים במסמך או באוסף של Firestore. אם הנתיב הוא לאוסף, ייווצר מסמך עם מזהה שנוצר באופן אקראי. אם הנתיב הוא למסמך והוא לא קיים, הוא ייווצר. ה-API הזה מחזיר הבטחה (promise) שמתקיימת למזהה של המסמך שנוסף או שונה. אם משתמשים באפשרות של טרנזקציה, ה-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. אם אין מסמכים שתואמים לתנאי השאילתה, ה-promise שיוחזר יתקבל כמערך ריק.

תחביר

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 קריאה חוזרת (callback) שמופעלת עם מזהה עסקה מסוג מחרוזת. אפשר להעביר את מזהה העסקה לקריאות ל-API של קריאה/כתיבה/שאילתה. פונקציית הקריאה החוזרת הזו חייבת להחזיר אובייקט promise. הקריאה החוזרת יכולה לפעול עד שלוש פעמים לפני שהיא נכשלת.
options object אפשרויות בקשה אופציונליות. האפשרות היחידה שנתמכת היא projectId. המערכת מתעלמת ממפתחות של אפשרויות לא ידועות. (ראו אפשרויות בהמשך).

אפשרויות

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

דוגמה

const Firestore = require('Firestore');

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

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

דוגמה לשגיאה

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

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

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

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

access_firestore

JSON

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

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

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

דוגמה

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

תחביר

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

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

ללא.

Math

אובייקט שמספק פונקציות של Math.

תחביר

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

פרמטרים

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

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

ללא.

Messages

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

addMessageListener

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

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

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

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

Object

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

ה-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 יטופל כאילו היה אובייקט קפוא, ויוחזר.

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

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

תחביר

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

פרמטרים

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

פרמטר סוג תיאור
objectInput any האובייקט שהמפתח שלו יימחק.
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

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

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

  • .then() – מטפל גם בבקשות שנפתרו וגם בבקשות שנדחו. הוא מקבל שני קריאות חוזרות (callbacks) כפרמטרים: אחת למקרה של הצלחה ואחת למקרה של כישלון.
  • ‫.catch() – מטפל רק בבקשות שנדחו. מקבלת קריאה חוזרת אחת כפרמטר.
  • ‫.finally() – מאפשר להריץ קוד גם אם אובייקט ה-promise הותאם וגם אם הוא נדחה. מקבלת קריאה חוזרת (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) ש:

  • הוא מסתיים כשכל הקלטים מסתיימים, או
  • דחייה כשכל אחד מהקלטים נדחה

תחביר

Promise.all(inputs);

פרמטרים

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

דוגמה

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

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

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

ללא.

Promise.create

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

תחביר

Promise.create(resolver);

פרמטרים

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

דוגמה

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

תחביר

assertThat(actual, opt_message)

פרמטרים

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

Matchers

התאמה תיאור
isUndefined() הצהרה שהנושא הוא undefined.
isDefined() הצהרה שהנושא הוא לא undefined.
isNull() הצהרה שהנושא הוא null.
isNotNull() הצהרה שהנושא הוא לא null.
isFalse() הצהרה שהנושא הוא false.
isTrue() הצהרה שהנושא הוא true.
isFalsy() מצהיר שהנושא הוא falsy. ערכים מסוג Falsy הם undefined, null, false, NaN, 0, ו-'' (מחרוזת ריקה).
isTruthy() קובע שהנושא הוא truthy. ערכים מסוג 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

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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

mockObject

באמצעות ה-API של mockObject אפשר לשנות את ההתנהגות של ממשקי 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'});