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

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

addEventCallback

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

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

תחביר

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 או בפונקציה onComplete של runContainer).

הלקוח צריך לתבוע בעלות על הבקשה באמצעות ה-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

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

דוגמה

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

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

תחביר

encodeUri(uri);

פרמטרים

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

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

ללא.

encodeUriComponent

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

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

ללא.

getAllEventData

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

תחביר

getAllEventData();

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

read_event_data

getClientName

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

תחביר

getClientName();

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

read_container_data

getContainerVersion

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

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

דוגמה

const getContainerVersion = require('getContainerVersion');

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

תחביר

getContainerVersion();

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

read_container_data

getCookieValues

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

דוגמה

const getCookieValues = require('getCookieValues');

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

תחביר

getCookieValues(name[, noDecode]);

פרמטרים

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

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

get_cookies

getEventData

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

דוגמה

const getEventData = require('getEventData');

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

פרמטרים

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

תחביר

getEventData(keyPath);

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

read_event_data

getGoogleAuth

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

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

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

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

דוגמה

const getGoogleScript = require('getGoogleScript');

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

תחביר

getGoogleScript(script[, options]);

פרמטרים

פרמטר סוג תיאור
script מחרוזת שם הסקריפט. הסקריפטים הנתמכים הם 'ANALYTICS', 'GTAG' ו-'GTM'.

האפשרות 'ANALYTICS' מאחזרת את הסקריפט של Google Analytics מ-https://www.google-analytics.com/analytics.js.

האפשרות 'GTAG' מאחזרת את הסקריפט של תג המעקב ברמת האתר (gtag.js) מ-https://www.googletagmanager.com/gtag/js.

האפשרות 'GTM' מאחזרת את הסקריפט של Google Tag Manager מ-https://www.googletagmanager.com/gtm.js.
options אובייקט אפשרויות אופציונליות לבקשות. למטה מפורטות האפשרויות הנתמכות.

אפשרויות

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

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

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

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

  • התרת השימוש ב-Google Domains

getRemoteAddress

מחזירה ייצוג string של כתובת ה-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

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

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

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

תחביר

getTimestamp();

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

ללא.

getTimestampMillis

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

תחביר

getTimestampMillis();

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

ללא.

getType

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

סוג הקלט הערך שהוחזר
מחרוזת 'string'
מספר 'number'
boolean 'boolean'
null 'null'
לא מוגדר '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 מחרוזת הנתונים לחישוב ערך ה-HMAC.
keyId מחרוזת מזהה מפתח מקובץ מפתח ה-JSON שמתייחס למפתח שבו צריך להשתמש.
options אובייקט הגדרת 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 Console. ב-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 מחרוזת שם העמודה שהערכים שלה יהפכו למפתחות ב-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. ברירת המחדל היא קוד סטטוס 200 של HTTP, גוף ריק וללא כותרות.

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

תחביר

returnResponse();

דוגמה

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

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

return_response

runContainer

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

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

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

run_container

sendEventToGoogleAnalytics

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

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

דוגמה

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();
}, (err) => {
  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 מחרוזת כתובת ה-URL המבוקשת.
options אובייקט אופציונלי אפשרויות של בקשות. (ראו אפשרויות בהמשך).

אפשרויות

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

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

send_http

sendHttpRequest

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

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

אפשרויות

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

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

send_http

sendPixelFromBrowser

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

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

דוגמה:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

תחביר

sendPixelFromBrowser(url)

פרמטרים

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

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

send_pixel_from_browser

setCookie

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

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

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

דוגמה

const setCookie = require('setCookie');

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

תחביר

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

פרמטרים

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

  • domain: המארח שאליו יישלח קובץ ה-cookie. אם מגדירים את הערך המיוחד 'auto', המארח יחושב באופן אוטומטי באמצעות האסטרטגיה הבאה:

    • eTLD+1 של הכותרת Forwarded, אם קיימת.
    • eTLD+1 של הכותרת X-Forwarded-Host, אם קיימת.
    • eTLD+1 מתוך הכותרת Host.

  • expires: משך החיים המקסימלי של קובץ ה-Cookie. זו חייבת להיות מחרוזת תאריך בפורמט UTC, למשל "Sat, 26 Oct 1985 08:21:00 GMT". אם גם expires וגם max-age מוגדרים, ל-max-age יש עדיפות.

  • httpOnly: מונע מ-JavaScript לגשת לקובצי ה-cookie אם true.

  • max-age: מספר השניות עד שתוקף קובץ ה-cookie יפוג. מספר אפס או שלילי יפוג מיד של קובץ ה-cookie. אם גם expires וגם max-age מוגדרים, ל-max-age יש עדיפות.

  • path: נתיב שחייב להימצא בכתובת ה-URL המבוקשת, אחרת הדפדפן לא ישלח את הכותרת של קובץ ה-cookie.

  • secure: אם קובעים את הערך true, קובץ ה-cookie נשלח לשרת רק כשנשלחת בקשה מנקודת קצה של https:.

  • sameSite: מצהירה שאסור לשלוח קובץ Cookie עם בקשות ממקורות שונים. חייב להיות 'strict', 'lax' או 'none'.

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

set_cookie

setPixelResponse

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

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

תחביר

setPixelResponse();

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

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

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

setResponseBody

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

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

תחביר

setResponseBody(body[, encoding]);

פרמטרים

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

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

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

  • body

setResponseHeader

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

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

תחביר

setResponseHeader(name, value);

פרמטרים

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

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

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

  • headers

setResponseStatus

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

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

תחביר

setResponseStatus(statusCode);

פרמטרים

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

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

ללא.

templateDataStorage

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

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

תחביר

const templateDataStorage = require('templateDataStorage');

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

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

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

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

דוגמה

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

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

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

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

access_template_storage

testRegex

בודקת מחרוזת מול ביטוי רגולרי (regex) שנוצר באמצעות 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 מחרוזת מחרוזת בדיקה לבדיקה.

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

ללא.

toBase64

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

תחביר

toBase64(input, options);

פרמטרים

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

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

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

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

Firestore.read

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

תחביר

Firestore.read(path[, options]);

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

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

דוגמה

const Firestore = require('Firestore');

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

Firestore.write

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

תחביר

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

פרמטרים

פרמטר סוג תיאור
path מחרוזת הנתיב למסמך או לאוסף. לא יכול להתחיל או להסתיים ב-'/'.
input אובייקט הערך שיש לכתוב במסמך. אם אפשרות המיזוג מוגדרת, ה-API ימזג את המפתחות מהקלט למסמך.
options אובייקט אופציונלי אפשרויות של בקשות. האפשרויות הנתמכות הן: 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 שולחת שאילתה לאוסף הנתון ומחזירה הבטחה שתואמת למערך של מסמכי Firestore שתואמים לתנאי השאילתה. אובייקט המסמך של Firestore זהה לזה שצוין למעלה ב-Firestore.read. אם אין מסמכים שתואמים לתנאי השאילתה, ההבטחה שמוחזרת תקבל מערך ריק.

תחביר

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

פרמטר סוג תיאור
collection מחרוזת הנתיב לאוסף. לא יכול להתחיל או להסתיים ב-'/'.
queryConditions מערך מערך של תנאי שאילתות. כל שאילתה מגיעה בצורת מערך עם שלושה ערכים: key, operator ו-expectedValue. E.g.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

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

תחביר

Firestore.runTransaction(callback[, options]);

פרמטרים

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

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

  1. messageType:string
  2. message:Object

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

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

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

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

Object

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

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

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

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

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

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

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

תחביר

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

פרמטרים

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

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

דוגמה

const Object = require('Object');

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

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

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

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

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

Promise

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

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

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

משתנה שמחזיר להבטיח שווה לערך המתוקן של ההבטחה, או 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

הפונקציה מחזירה אובייקט תואם שאפשר להשתמש בו כדי לנסח טענות נכוֹנוּת (assertions) בצורה שוטפת על ה-API הנתון.

תחביר

assertApi(apiName)

פרמטרים

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

התאמות

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

דוגמאות

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

assertThat

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

תחביר

assertThat(actual, opt_message)

פרמטרים

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

התאמות

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

דוגמאות

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

fail

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

תחביר

fail(opt_message);

פרמטרים

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

דוגמה

fail('This test has failed.');

mock

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

תחביר

mock(apiName, returnValue);

פרמטרים

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

דוגמאות

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

runCode

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

תחביר

runCode(data)

פרמטרים

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

הערך המוחזר

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

דוגמה

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