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

פרמטרים

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

ללא.

createRegex

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

הפונקציה מחזירה null אם הביטוי הרגולרי לא תקין או אם Re2 לא זמין בשרת.

ה-API הזה משתמש בהטמעה של Re2. קובץ האימג' של Docker בשרת צריך להיות מגרסה 2.0.0 ואילך.

דוגמה

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

תחביר

createRegex(pattern, flags);

פרמטרים

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

ללא.

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

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

דוגמה

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

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

תחביר

encodeUri(uri);

פרמטרים

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

ללא.

encodeUriComponent

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

דוגמה

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

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

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

תחביר

getGoogleAuth(scopes);

פרמטרים

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

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

getGoogleScript

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

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

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

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

דוגמה

const getGoogleScript = require('getGoogleScript');

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

תחביר

getGoogleScript(script[, options]);

פרמטרים

אפשרויות

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

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

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

תחביר

getTimestamp();

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

ללא.

getTimestampMillis

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

דוגמה

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

תחביר

hmacSha256(data, keyId, options)

פרמטרים

אפשרויות

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

use_custom_private_keys

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

1.0.0

isRequestMpv1

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

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

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

דוגמה

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

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

תחביר

runContainer(event, onComplete, onStart);

פרמטרים

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

run_container

sendEventToGoogleAnalytics

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

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

דוגמה

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

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

תחביר

sendEventToGoogleAnalytics(event);

פרמטרים

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

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

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

sendHttpGet

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

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

דוגמה

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

תחביר

sendHttpGet(url[, options]);

פרמטרים

אפשרויות

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

send_http

sendHttpRequest

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

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

דוגמה

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

תחביר

sendHttpRequest(url[, options[, body]]);

פרמטרים

אפשרויות

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

send_http

sendPixelFromBrowser

שליחת פקודה לדפדפן לטעינת כתובת ה-URL שצוינה כתג <img>. פרוטוקול הפקודות הזה נתמך ב-Google Tag עבור Google Analytics וב-Google Analytics: GA Event web tags. צריך להגדיר את כתובת ה-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: אוסר על 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]);

פרמטרים

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

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

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

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

תחביר

const templateDataStorage = require('templateDataStorage');

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

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

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

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

דוגמה

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

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

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

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

access_template_storage

testRegex

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

ביטוי רגולרי שנוצר עם הדגל הגלובלי הוא בעל מצב (stateful). פרטים נוספים זמינים במאמרי העזרה של RegExp.

דוגמה

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

תחביר

testRegex(regex, string);

פרמטרים

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

ללא.

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 array ו-row object. הדוגמה הבאה היא של תגובת שגיאה מהוספה של שתי שורות, כשבשורה אחת בלבד יש שגיאה:

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

דוגמה

const BigQuery = require('BigQuery');

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

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

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

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

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

access_bigquery

Firestore

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

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

Firestore.read

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

תחביר

Firestore.read(path[, options]);

פרמטרים

אפשרויות

דוגמה

const Firestore = require('Firestore');

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

Firestore.write

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

תחביר

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

פרמטרים

אפשרויות

דוגמה

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

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

תחביר

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

פרמטרים

אפשרויות

דוגמה

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

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

תחביר

Firestore.runTransaction(callback[, options]);

פרמטרים

אפשרויות

דוגמה

const Firestore = require('Firestore');

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

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

דוגמה לשגיאה

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

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

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

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

access_firestore

JSON

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

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

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

דוגמה

const JSON = require('JSON');

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

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

תחביר

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

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

ללא.

Math

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

תחביר

const Math = require('Math');

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

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

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

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

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

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

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

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

פרמטרים

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

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

ללא.

Messages

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

addMessageListener

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

1. messageType:string
2. message:Object

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

תחביר

const addMessageListener = require('addMessageListener');

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

פרמטרים

דוגמה

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

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

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

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

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

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

• הערך של 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

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

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

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

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

דוגמה

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

הפונקציה מחזירה הבטחה שאחת מהאפשרויות הבאות תתקיים:

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

תחביר

Promise.all(inputs);

פרמטרים

דוגמה

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

פרמטרים

דוגמה

const Promise = require('Promise');

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

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

ללא.

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

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

assertApi

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

תחביר

assertApi(apiName)

פרמטרים

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

תחביר

mock(apiName, returnValue);

פרמטרים

דוגמאות

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

mockObject

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

תחביר

mockObject(apiName, objectMock);

פרמטרים