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

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

addEventCallback

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

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

תחביר

const addEventCallback = require('addEventCallback');

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

פרמטרים

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

דוגמה

בלקוח:

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)

פרמטרים

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

ללא.

claimRequest

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

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

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

דוגמה

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

פרמטרים

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

ללא.

createRegex

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

הפונקציה מחזירה את הערך null אם ביטוי ה-regex לא תקין או אם 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);

פרמטרים

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

ללא.

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

2.0.0

decodeUri

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

דוגמה

const decodeUri = require('decodeUri');

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

תחביר

decodeUri(encoded_uri);

פרמטרים

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

ללא.

decodeUriComponent

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

דוגמה

const decodeUriComponent = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component);

פרמטרים

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

ללא.

encodeUri

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

דוגמה

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

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

תחביר

encodeUri(uri);

פרמטרים

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

ללא.

encodeUriComponent

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

דוגמה

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

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

תחביר

encodeUriComponent(str);

פרמטרים

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

ללא.

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

פרמטרים

דוגמה

const fromBase64 = require('fromBase64');

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

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

ללא.

generateRandom

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

דוגמה

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

תחביר

generateRandom(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]);

פרמטרים

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

get_cookies

getEventData

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

דוגמה

const getEventData = require('getEventData');

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

פרמטרים

תחביר

getEventData(keyPath);

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

read_event_data

getGoogleAuth

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

פרמטרים

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

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

getGoogleScript

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

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

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

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

דוגמה

const getGoogleScript = require('getGoogleScript');

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

תחביר

getGoogleScript(script[, options]);

פרמטרים

אפשרויות

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

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

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

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

getRemoteAddress

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

תחביר

getRemoteAddress();

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

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

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

getRequestBody

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

תחביר

getRequestBody();

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

read_request

getRequestHeader

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

דוגמה

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

תחביר

getRequestHeader(headerName);

פרמטרים

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

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

פרמטרים

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

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, כפי שמוחזר על ידי Date.now().

תחביר

getTimestamp();

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

ללא.

getTimestampMillis

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

תחביר

getTimestampMillis();

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

ללא.

getType

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

דוגמה

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

פרמטרים

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

ללא.

hmacSha256

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

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

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

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

דוגמה

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)

פרמטרים

אפשרויות

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

use_custom_private_keys

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

1.0.0

isRequestMpv1

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

דוגמה

const isRequestMpv1 = require('isRequestMpv1');

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

תחביר

isRequestMpv1();

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

ללא.

isRequestMpv2

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

דוגמה

const isRequestMpv2 = require('isRequestMpv2');

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

תחביר

isRequestMpv2();

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

ללא.

logToConsole

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

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

דוגמה

const logToConsole = require('logToConsole');

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

תחביר

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

פרמטרים

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

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

logging

makeInteger

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

תחביר

makeInteger(value);

פרמטרים

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

ללא.

makeNumber

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

תחביר

makeNumber(value);

פרמטרים

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

ללא.

makeString

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

תחביר

makeString(value);

פרמטרים

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

ללא.

makeTableMap

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

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

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

למפה:

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

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

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName);

פרמטרים

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

ללא.

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

פרמטרים

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

ללא.

returnResponse

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

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

תחביר

returnResponse();

דוגמה

לדוגמה של runContainer

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

return_response

runContainer

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

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

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

דוגמה

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

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

תחביר

runContainer(event, onComplete, onStart);

פרמטרים

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

run_container

sendEventToGoogleAnalytics

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

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

דוגמה

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

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

תחביר

sendEventToGoogleAnalytics(event);

פרמטרים

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

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

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

sendHttpGet

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

התוצאה שמוחזרת היא אובייקט שמכיל שלושה מפתחות: statusCode,‏ headers ו-body. אם הבקשה נכשלה (למשל, כתובת URL לא חוקית, אין מסלול למארח, ‎SSL negotiation failure וכו'), ההתחייבות תידחה עם הערך: {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]);

פרמטרים

אפשרויות

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

send_http

sendHttpRequest

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

התוצאה שמוחזרת היא אובייקט שמכיל שלושה מפתחות: statusCode,‏ headers ו-body. אם הבקשה נכשלה (למשל, כתובת URL לא חוקית, אין מסלול למארח, ‎SSL negotiation failure וכו'), ההתחייבות תידחה עם הערך: {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]]);

פרמטרים

אפשרויות

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

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)

פרמטרים

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

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

פרמטרים

אפשרויות

• 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 נשלח לשרת רק כשמתבצעת בקשה מנקודת קצה מסוג 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]);

פרמטרים

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

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

• body

setResponseHeader

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

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

תחביר

setResponseHeader(name, value);

פרמטרים

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

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

• headers

setResponseStatus

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

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

תחביר

setResponseStatus(statusCode);

פרמטרים

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

נדרשת ההרשאה 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);

פרמטרים

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

ללא.

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

פרמטרים

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

ללא.

templateDataStorage

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

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

תחביר

const templateDataStorage = require('templateDataStorage');

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

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

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

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

דוגמה

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

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

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

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

access_template_storage

testRegex

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

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

פרמטרים

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

ללא.

toBase64

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

תחביר

toBase64(input, options);

פרמטרים

אפשרויות

דוגמה

const toBase64 = require('toBase64');

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

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

ללא.

BigQuery

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

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

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

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

תחביר

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

פרמטרים

אפשרויות

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

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

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

[{reason: 'invalid'}]

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

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

דוגמה

const BigQuery = require('BigQuery');

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

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

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

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

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

access_bigquery

Firestore

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

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

Firestore.read

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

תחביר

Firestore.read(path[, options]);

פרמטרים

אפשרויות

דוגמה

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

פרמטרים

אפשרויות

דוגמה

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

פרמטרים

אפשרויות

דוגמה

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

פרמטרים

אפשרויות

דוגמה

const Firestore = require('Firestore');

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

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

דוגמה לשגיאה

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

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

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

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

access_firestore

JSON

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

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

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

דוגמה

const JSON = require('JSON');

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

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

תחביר

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

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

ללא.

Math

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

תחביר

const Math = require('Math');

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

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

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

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

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

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

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

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

פרמטרים

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

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

ללא.

Messages

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

addMessageListener

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

1. messageType:string
2. message:Object

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

תחביר

const addMessageListener = require('addMessageListener');

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

פרמטרים

דוגמה

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

פרמטרים

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

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

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

תחביר

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

פרמטרים

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

דוגמה

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

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

פרמטרים

דוגמה

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

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

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

ללא.

Promise.create

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

תחביר

Promise.create(resolver);

פרמטרים

דוגמה

const Promise = require('Promise');

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

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

ללא.

ממשקי API לבדיקה

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

assertApi

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

תחביר

assertApi(apiName)

פרמטרים

Matchers

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

דוגמאות

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

assertThat

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

תחביר

assertThat(actual, opt_message)

פרמטרים

Matchers

דוגמאות

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

פרמטרים

דוגמה

fail('This test has failed.');

mock

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

תחביר

mock(apiName, returnValue);

פרמטרים

דוגמאות

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

mockObject

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

תחביר

mockObject(apiName, objectMock);

פרמטרים