APIهای قالب سفارشی

API های اصلی

این APIها با جاوا اسکریپتِ سندباکس‌شده کار می‌کنند تا قالب‌های سفارشی را در گوگل تگ منیجر بسازند. هر API با یک دستور require() اضافه می‌شود، مثلاً:

const myAPI = require('myAPI');

addConsentListener

یک تابع شنونده (listener) ثبت می‌کند تا زمانی که وضعیت نوع رضایت مشخص شده تغییر کند، اجرا شود.

شنونده‌ی داده شده هر بار که وضعیت نوع رضایت مشخص شده از رد شده به اعطا شده یا از اعطا شده به رد شده تغییر کند، فراخوانی می‌شود. نوع رضایتی که هیچ وضعیتی نداشته باشد، اعطا شده در نظر گرفته می‌شود، بنابراین اگر نوع رضایتی که تنظیم نشده است به اعطا شده به‌روزرسانی شود، شنونده فراخوانی نخواهد شد. توابع شنونده مسئول اطمینان از اجرای کد خود به تعداد دفعات مناسب هستند.

مثال:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

نحو

addConsentListener(consentType, listener)

پارامترها

پارامتر نوع توضیحات
consentType رشته نوع رضایتی که باید به تغییرات وضعیت آن گوش دهید.
listener تابع تابعی که هنگام تغییر وضعیت نوع رضایت مشخص شده، اجرا می‌شود.

وقتی یک شنونده فراخوانی می‌شود، نوع رضایتی که تغییر می‌کند و مقدار جدید آن نوع رضایت به آن ارسال می‌شود:

پارامتر نوع توضیحات
consentType رشته نوع رضایتی که در حال تغییر است.
granted بولی یک مقدار بولی که اگر نوع رضایت مشخص شده به اعطا شده تغییر کند، مقدار آن درست (true) است.

مجوزهای مرتبط

مجوز access_consent به همراه دسترسی خواندن برای نوع رضایت.

addEventCallback

API addEventCallback به شما امکان می‌دهد یک تابع فراخوانی ثبت کنید که در پایان یک رویداد فراخوانی می‌شود. این فراخوانی زمانی فراخوانی می‌شود که تمام تگ‌های رویداد اجرا شده باشند، یا اگر زمان انقضای رویداد در صفحه فرا رسیده باشد. به این فراخوانی دو مقدار ارسال می‌شود، یکی شناسه‌ی کانتینری که تابع را فراخوانی می‌کند و دیگری یک شیء که حاوی اطلاعاتی در مورد رویداد است.

نحو

addEventCallback(callback)

پارامترها

پارامتر نوع توضیحات
callback تابع تابعی که قرار است در پایان رویداد فراخوانی شود.

شیء eventData شامل داده‌های زیر است:

نام کلید نوع توضیحات
tags آرایه آرایه‌ای از اشیاء داده تگ. هر تگی که در طول رویداد اجرا شود، یک ورودی در این آرایه خواهد داشت. شیء داده تگ شامل شناسه تگ ( id )، وضعیت اجرای آن ( status ) و زمان اجرای آن ( executionTime ) است. داده‌های تگ همچنین شامل فراداده‌های اضافی تگ که روی تگ پیکربندی شده‌اند، خواهد بود.

مثال

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

مجوزهای مرتبط

read_event_metadata

aliasInWindow

API aliasInWindow به شما امکان می‌دهد یک نام مستعار ایجاد کنید (مثلاً window.foo = window.bar )، که به پشتیبانی از تگ‌های خاصی که نیاز به نام مستعار دارند کمک می‌کند. مقداری را که در شیء window در fromPath یافت می‌شود، به کلید شیء window در toPath اختصاص می‌دهد. در صورت موفقیت، true و در غیر این صورت false را برمی‌گرداند.

نحو

aliasInWindow(toPath, fromPath)

پارامترها

پارامتر نوع توضیحات
toPath رشته یک مسیر جدا شده با نقطه به درون شیء window که یک مقدار باید در آن کپی شود. تمام اجزای موجود در مسیر تا آخرین جزء باید از قبل در شیء window وجود داشته باشند.
fromPath رشته یک مسیر جدا شده با نقطه به window که مقداری را برای کپی کردن نشان می‌دهد. اگر مقدار وجود نداشته باشد، عملیات با شکست مواجه خواهد شد.

مثال

aliasInWindow('foo.bar', 'baz.qux')

مجوزهای مرتبط

access_globals هم برای toPath و هم برای fromPath ضروری است؛ toPath نیاز به دسترسی نوشتن و fromPath نیاز به دسترسی خواندن دارد.

callInWindow

به شما امکان می‌دهد توابع را از مسیری خارج از شیء window ، به روشی که توسط سیاست کنترل می‌شود، فراخوانی کنید. تابع را در مسیر داده شده در window با آرگومان‌های داده شده فراخوانی می‌کند و مقدار را برمی‌گرداند. اگر نوع بازگشتی را نتوان مستقیماً به نوعی که در جاوا اسکریپت sandboxed پشتیبانی می‌شود، نگاشت کرد، مقدار undefined برگردانده می‌شود. هشت نوع پشتیبانی شده در جاوا اسکریپت sandboxed عبارتند از null ، undefined ، boolean ، number ، string ، Array ، Object و function . اگر مسیر داده شده وجود نداشته باشد یا به تابعی ارجاع ندهد، undefined برگردانده می‌شود.

نحو

callInWindow(pathToFunction, argument [, argument2,... argumentN])

پارامترها

پارامتر نوع توضیحات
pathToFunction رشته مسیری که با نقطه از هم جدا شده و به تابعی در window که قرار است فراخوانی شود، اشاره دارد.
args * آرگومان‌هایی که باید به تابع ارسال شوند.

مجوزهای مرتبط

access_globals با مجوز execute فعال.

callLater

فراخوانی یک تابع را به صورت غیرهمزمان برنامه‌ریزی می‌کند. تابع پس از بازگشت کد فعلی فراخوانی می‌شود. این معادل setTimeout(<function>, 0) است.

نحو

callLater(function)

پارامترها

پارامتر نوع توضیحات
function تابع تابعی که باید فراخوانی شود.

copyFromDataLayer

مقداری که در حال حاضر به کلید داده شده در لایه داده اختصاص داده شده است را برمی‌گرداند: مقداری که در کلید داده شده یافت می‌شود اگر یک نوع داده اولیه، تابع یا شیء تحت‌اللفظی باشد، و در غیر این صورت undefined .

نحو

copyFromDataLayer(key[, dataLayerVersion])

پارامترها

پارامتر نوع توضیحات
key رشته کلید با فرمت "abc".
dataLayerVersion شماره نسخه لایه داده اختیاری. مقدار پیش‌فرض ۲ است. استفاده از مقدار ۱ اکیداً توصیه نمی‌شود.

مجوزهای مرتبط

read_data_layer

copyFromWindow

یک متغیر را از شیء window کپی می‌کند. اگر مقدار موجود در window نتواند مستقیماً به نوعی که در جاوا اسکریپت sandboxed پشتیبانی می‌شود، نگاشت شود، مقدار undefined برگردانده می‌شود. هشت نوع داده‌ای که در جاوا اسکریپت sandboxed پشتیبانی می‌شوند عبارتند از null ، undefined ، boolean ، number ، string ، Array ، Object و function . مقدار واکشی شده (و اجباری) را برمی‌گرداند.

نحو

copyFromWindow(key)

پارامترها

پارامتر نوع توضیحات
key رشته کلید موجود در window برای کپی کردن مقدار.

مجوزهای مرتبط

access_globals

createArgumentsQueue

صفی ایجاد می‌کند که با اشیاء آرگومان پر شده است، تا از راه‌حل‌های برچسب‌گذاری که به آن نیاز دارند، پشتیبانی کند.

با استفاده از آرگومان fnKey (همان معنای createQueue ) یک تابع در محدوده سراسری (مثلاً window ) ایجاد می‌کند. پس از ایجاد تابع، این API سپس با استفاده از آرگومان arrayKey یک آرایه در window (اگر از قبل وجود نداشته باشد) ایجاد می‌کند.

وقتی تابعی که تحت fnKey ایجاد شده است فراخوانی می‌شود، شیء آرگومان‌های خود را به آرایه‌ای که تحت arrayKey ایجاد شده است، ارسال می‌کند. مقدار بازگشتی API، تابعی است که تحت fnKey ایجاد شده است.

این تابع نیاز به تنظیمات خواندن و نوشتن برای fnKey و arrayKey در مجوز access_globals دارد.

مثال:

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

نحو

createArgumentsQueue(fnKey, arrayKey)

پارامترها

پارامتر نوع توضیحات
fnKey رشته مسیر در window که تابع در آن تنظیم شده است، اگر از قبل وجود نداشته باشد. این آرگومان از نمادگذاری نقطه استاندارد پشتیبانی می‌کند. اگر مسیر کلید وجود نداشته باشد، یک استثنا ایجاد می‌شود. یعنی اگر fnKey برابر با 'one.two' باشد، یک استثنا ایجاد می‌شود.
arrayKey رشته مسیر در window که آرایه در آن تنظیم شده است، اگر از قبل وجود نداشته باشد. این آرگومان از نمادگذاری نقطه استاندارد پشتیبانی می‌کند. اگر مسیر کلید وجود نداشته باشد، یک استثنا ایجاد می‌شود. یعنی اگر arrayKey برابر با 'one.two' باشد و هیچ شیء سراسری به نام 'one' وجود نداشته باشد، یک استثنا ایجاد می‌شود.

مجوزهای مرتبط

access_globals

createQueue

یک آرایه در window ایجاد می‌کند (اگر از قبل وجود نداشته باشد) و تابعی را برمی‌گرداند که مقادیر را به آن آرایه ارسال می‌کند.

این تابع به تنظیمات خواندن و نوشتن برای arrayKey در سطح دسترسی access_globals نیاز دارد.

مثال:

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

نحو

createQueue(arrayKey)

پارامترها

پارامتر نوع توضیحات
arrayKey رشته کلید موجود در window که آرایه در آن تنظیم شده است، اگر از قبل وجود نداشته باشد. این آرگومان از نمادگذاری نقطه استاندارد پشتیبانی می‌کند. اگر مسیر کلید وجود نداشته باشد، یک استثنا ایجاد می‌شود. برای مثال، اگر arrayKey برابر با 'one.two' باشد و هیچ شیء سراسری به نام 'one' وجود نداشته باشد، یک استثنا ایجاد می‌شود.

مجوزهای مرتبط

access_globals

decodeUri

هر کاراکتر رمزگذاری شده در URI ارائه شده را رمزگشایی می‌کند. رشته‌ای را برمی‌گرداند که نشان دهنده URI رمزگشایی شده است. در صورت ارائه ورودی نامعتبر، undefined را برمی‌گرداند.

مثال:

const decode = require('decodeUri');

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

نحو

decodeUri(encoded_uri)

پارامترها

پارامتر نوع توضیحات
encoded_uri رشته یک URI که توسط encodeUri() یا به روش‌های دیگر کدگذاری شده است.

مجوزهای مرتبط

هیچ کدام.

decodeUriComponent

هر کاراکتر رمزگذاری شده در مؤلفه URI ارائه شده را رمزگشایی می‌کند. رشته‌ای را برمی‌گرداند که نشان دهنده مؤلفه URI رمزگشایی شده است. در صورت ارائه ورودی نامعتبر undefined را برمی‌گرداند.

مثال:

const decode = require('decodeUriComponent');

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

نحو

decodeUriComponent(encoded_uri_component)

پارامترها

پارامتر نوع توضیحات
encoded_uri_component رشته یک کامپوننت URI که توسط encodeUriComponent() یا به روش‌های دیگر کدگذاری شده است.

مجوزهای مرتبط

هیچ کدام.

encodeUri

با حذف کاراکترهای خاص، یک شناسه منبع یکسان (URI) کدگذاری شده را برمی‌گرداند. رشته‌ای را برمی‌گرداند که نشان دهنده رشته ارائه شده کدگذاری شده به عنوان یک URI است. در صورت ارائه ورودی نامعتبر (یک جایگزین تنها)، undefined برمی‌گرداند.

مثال:

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

نحو

encodeUri(uri)

پارامترها

پارامتر نوع توضیحات
uri رشته یک URI کامل.

مجوزهای مرتبط

هیچ کدام.

encodeUriComponent

با حذف کاراکترهای خاص، یک شناسه منبع یکسان (URI) کدگذاری شده را برمی‌گرداند. رشته‌ای را برمی‌گرداند که نشان دهنده رشته ارائه شده کدگذاری شده به عنوان یک URI است. در صورت ارائه ورودی نامعتبر (یک جایگزین تنها)، undefined برمی‌گرداند.

مثال: 

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

نحو

encodeUriComponent(str)

پارامترها

پارامتر نوع توضیحات
str رشته یک جزء از یک URI.

مجوزهای مرتبط

هیچ کدام.

fromBase64

رابط برنامه‌نویسی کاربردی fromBase64 به شما امکان می‌دهد رشته‌ها را از نمایش base64 آنها رمزگشایی کنید. در صورت ارائه ورودی نامعتبر undefined را برمی‌گرداند.

نحو

fromBase64(base64EncodedString)

پارامترها

پارامتر نوع توضیحات
base64EncodedString رشته رشته کدگذاری شده با Base64.

مثال 

const fromBase64 = require('fromBase64');

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

مجوزهای مرتبط

هیچکدام

generateRandom

یک عدد تصادفی (عدد صحیح) را در محدوده داده شده برمی‌گرداند.

نحو

generateRandom(min, max)

پارامترها

پارامتر نوع توضیحات
min شماره حداقل مقدار بالقوه عدد صحیح برگردانده شده.
max شماره حداکثر مقدار بالقوه عدد صحیح برگردانده شده.

مجوزهای مرتبط

هیچ کدام.

getContainerVersion

یک شیء حاوی داده‌های مربوط به کانتینر فعلی را برمی‌گرداند. شیء برگردانده شده دارای فیلدهای زیر است: 

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

مثال 

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

نحو

getContainerVersion();

مجوزهای مرتبط

read_container_data

getCookieValues

مقادیر همه کوکی‌ها با نام داده شده را برمی‌گرداند.

نحو

getCookieValues(name[, decode])

پارامترها

پارامتر نوع توضیحات
name رشته نام کوکی.
decode بولی کنترل می‌کند که آیا مقادیر کوکی با decodeURIComponent() جاوا اسکریپت رمزگشایی شوند یا خیر. مقدار پیش‌فرض true است.

مجوزهای مرتبط

get_cookies

getQueryParameters

اولین یا تمام پارامترهای queryKey آدرس فعلی را برمی‌گرداند. اولین مقدار را از queryKey یا آرایه‌ای از مقادیر را از queryKey برمی‌گرداند.

نحو

getQueryParameters(queryKey[, retrieveAll])

پارامترها

پارامتر نوع توضیحات
queryKey رشته کلید خواندن از پارامترهای پرس و جو.
retrieveAll بولی آیا همه مقادیر بازیابی شوند یا خیر.

برای مثال، اگر آدرس اینترنتی فعلی https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo باشد، آنگاه:

  • getQueryParameters('var') == 'foo'
  • getQueryParameters('var', false) == 'foo'
  • getQueryParameters('var', null) == 'foo'
  • getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

مجوزهای مرتبط

get_url باید کامپوننت query را مجاز بداند، و باید queryKey در کلیدهای پرس‌وجوی مجاز مشخص کند (یا هر کلید پرس‌وجویی را مجاز بداند.)

getReferrerQueryParameters

API getReferrerQueryParameters همانند getQueryParameters عمل می‌کند، با این تفاوت که به جای URL فعلی، روی ارجاع‌دهنده عمل می‌کند. اولین یا تمام پارامترهای queryKey ارجاع‌دهنده داده شده را برمی‌گرداند. اولین مقدار را از queryKey یا آرایه‌ای از مقادیر را از queryKey برمی‌گرداند.

نحو

getReferrerQueryParameters(queryKey[, retrieveAll])

پارامترها

پارامتر نوع توضیحات
queryKey رشته کلید خواندن از پارامترهای پرس و جو.
retrieveAll بولی آیا همه مقادیر بازیابی شوند یا خیر.

برای مثال، اگر آدرس اینترنتی ارجاع‌دهنده https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo باشد، آنگاه:

  • getReferrerQueryParameters('var') == 'foo'
  • getReferrerQueryParameters('var', false) == 'foo'
  • getReferrerQueryParameters('var', null) == 'foo'
  • getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

مجوزهای مرتبط

get_referrer باید کامپوننت query را مجاز بداند، و باید queryKey در کلیدهای پرس‌وجوی مجاز مشخص کند (یا هر کلید پرس‌وجویی را مجاز بداند.)

getReferrerUrl

با توجه به نوع کامپوننت، API شیء سند مربوط به ارجاع‌دهنده را می‌خواند و رشته‌ای را برمی‌گرداند که نشان‌دهنده بخشی از ارجاع‌دهنده است. اگر هیچ کامپوننتی مشخص نشده باشد، URL کامل ارجاع‌دهنده بازگردانده می‌شود.

نحو

getReferrerUrl([component])

پارامترها

پارامتر نوع توضیحات
component رشته کامپوننتی که از URL برگردانده می‌شود. می‌تواند یکی از موارد زیر باشد: protocol ، host ، port ، path ، query ، extension . اگر component undefined ، null باشد یا با یکی از این کامپوننت‌ها مطابقت نداشته باشد، کل URL برگردانده می‌شود.

مجوزهای مرتبط

get_referrer باید کامپوننت query را مجاز بداند، و باید queryKey در کلیدهای پرس‌وجوی مجاز مشخص کند (یا هر کلید پرس‌وجویی را مجاز بداند.)

getTimestamp

منسوخ شده. getTimestampMillis را ترجیح دهید.

عددی را برمی‌گرداند که زمان فعلی را بر حسب میلی‌ثانیه از زمان آغاز یونیکس نشان می‌دهد، همانطور که توسط Date.now() برگردانده می‌شود.

نحو

getTimestamp();

مجوزهای مرتبط

هیچ کدام.

getTimestampMillis

عددی را برمی‌گرداند که زمان فعلی را بر حسب میلی‌ثانیه از زمان آغاز یونیکس نشان می‌دهد، همانطور که توسط Date.now() برگردانده می‌شود.

نحو

getTimestampMillis();

مجوزهای مرتبط

هیچ کدام.

getType

رشته‌ای را برمی‌گرداند که نوع مقدار داده شده را توصیف می‌کند. برخلاف typeof ، getType بین array و object تفاوت قائل می‌شود.

نحو

getType(data.someField)

یادداشت‌ها

جدول زیر رشته‌های برگردانده شده برای هر مقدار ورودی را فهرست می‌کند.

مقدار ورودی نتیجه
undefined 'تعریف نشده'
null 'تهی'
true 'بولی'
12 'شماره'
'string' 'رشته'
{ a: 3 } 'شی'
[ 1, 3 ] 'آرایه'
(x) => x + 1 «تابع»

مجوزهای مرتبط

هیچ کدام.

getUrl

رشته‌ای را برمی‌گرداند که نشان‌دهنده‌ی تمام یا بخشی از URL فعلی است، با توجه به نوع کامپوننت و برخی پارامترهای پیکربندی.

نحو

getUrl(component)

پارامترها

پارامتر نوع توضیحات
component رشته کامپوننتی که قرار است از URL برگردانده شود. باید یکی از موارد زیر باشد: protocol ، host ، port ، path ، query ، extension ، fragment . اگر کامپوننت undefined ، null باشد یا با یکی از این کامپوننت‌ها مطابقت نداشته باشد، کل مقدار href برگردانده خواهد شد.

مجوزهای مرتبط

get_url

gtagSet

دستور gtag set را به لایه داده ارسال می‌کند تا در اسرع وقت پس از اتمام پردازش رویداد فعلی و هر تگی که فعال شده است (یا رسیدن به زمان پایان پردازش تگ) پردازش شود. تضمین می‌شود که به‌روزرسانی در این کانتینر قبل از هر آیتم صف‌بندی شده در صف لایه داده پردازش شود.

برای مثال، اگر توسط تگی که در Consent Initialization فعال شده است فراخوانی شود، به‌روزرسانی قبل از پردازش رویداد Initialization اعمال خواهد شد. برای مثال می‌توان به تنظیم ads_data_redaction روی true یا false یا تنظیم url_passthrough روی true یا false اشاره کرد.

مثال‌ها: 

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

نحو

gtagSet(object)

پارامترها

پارامتر نوع توضیحات
Object شیء شیء‌ای که وضعیت سراسری (global state) را برای ویژگی‌های (property) حاوی خود به‌روزرسانی می‌کند.

مجوزهای مرتبط

تابع write_data_layer مجوز نوشتن در dataLayer را برای تمام کلیدهای مشخص شده بررسی می‌کند. اگر ورودی به gtagSet یک شیء ساده باشد، API مجوز نوشتن در تمام کلیدهای مسطح شده درون آن شیء را بررسی می‌کند، به عنوان مثال برای gtagSet({foo: {bar: 'baz'}}) ، API مجوز نوشتن در foo.bar را بررسی می‌کند.

اگر ورودی gtagSet یک کلید و مقداری غیرساده از شیء باشد، API مجوز نوشتن روی آن کلید را بررسی می‌کند، مثلاً برای gtagSet('abc', true) ، API مجوز نوشتن روی 'abc' را بررسی می‌کند.

توجه داشته باشید که اگر در شیء ورودی چرخه‌ای وجود داشته باشد، فقط کلیدهایی قبل از رسیدن به همان شیء بررسی می‌شوند.

injectHiddenIframe

یک iframe نامرئی به صفحه اضافه می‌کند.

فراخوانی‌های برگشتی به عنوان نمونه‌های تابع ارائه می‌شوند و در توابع جاوا اسکریپتی که آنها را فراخوانی می‌کنند، قرار می‌گیرند.

نحو

injectHiddenIframe(url, onSuccess)

پارامترها

پارامتر نوع توضیحات
url رشته آدرس اینترنتی (URL) که قرار است به عنوان مقدار ویژگی src مربوط به iframe استفاده شود.
onSuccess تابع زمانی که فریم با موفقیت بارگذاری شود، فراخوانی می‌شود.

مجوزهای مرتبط

inject_hidden_iframe

injectScript

یک تگ اسکریپت به صفحه اضافه می‌کند تا URL داده شده را به صورت غیرهمزمان بارگذاری کند. فراخوانی‌های برگشتی به عنوان نمونه‌های تابع ارائه می‌شوند و در توابع جاوا اسکریپتی که آنها را فراخوانی می‌کنند، قرار می‌گیرند.

نحو

injectScript(url, onSuccess, onFailure[, cacheToken])

پارامترها

پارامتر نوع توضیحات
url رشته آدرس اسکریپتی که قرار است تزریق شود.
onSuccess تابع زمانی که اسکریپت با موفقیت بارگذاری شود، فراخوانی می‌شود.
onFailure تابع زمانی فراخوانی می‌شود که اسکریپت بارگذاری نشود.
cacheToken رشته رشته‌ی اختیاری که برای نشان دادن ذخیره شدن URL داده شده استفاده می‌شود. اگر این مقدار مشخص شود، فقط یک عنصر اسکریپت برای درخواست جاوا اسکریپت ایجاد می‌شود. هرگونه تلاش اضافی برای بارگذاری منجر به قرار گرفتن متدهای onSuccess و onFailure داده شده تا زمان بارگذاری اسکریپت در صف می‌شود.

مجوزهای مرتبط

inject_script

isConsentGranted

اگر نوع رضایت مشخص شده اعطا شود، مقدار true را برمی‌گرداند.

رضایت برای یک نوع رضایت خاص، در صورتی اعطا شده تلقی می‌شود که نوع رضایت روی «اعطا شده» تنظیم شده باشد یا اصلاً تنظیم نشده باشد. اگر نوع رضایت روی هر مقدار دیگری تنظیم شده باشد، رضایت اعطا نشده تلقی خواهد شد.

رابط کاربری Tag Manager برای تنظیمات تگ، گزینه‌ای برای فعال بودن همیشگی تگ ارائه می‌دهد. اگر تگی با فعال بودن همیشگی از این API استفاده کند، صرف نظر از وضعیت واقعی رضایت، رضایت اعطا شده تلقی شده و true برگردانده می‌شود.

مثال: 

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

نحو

isConsentGranted(consentType)

پارامترها

پارامتر نوع توضیحات
consentType رشته نوع رضایت برای بررسی وضعیت.

مجوزهای مرتبط

مجوز access_consent به همراه دسترسی خواندن برای نوع رضایت.

JSON

یک شیء را برمی‌گرداند که توابع JSON را ارائه می‌دهد.

تابع parse() parse یک رشته JSON را تجزیه می‌کند تا مقدار یا شیء توصیف شده توسط رشته را بسازد. اگر مقدار قابل تجزیه نباشد (مثلاً JSON ناقص باشد)، تابع مقدار undefined برمی‌گرداند. اگر مقدار ورودی رشته نباشد، ورودی به یک رشته تبدیل می‌شود.

تابع stringify() ورودی را به یک رشته JSON تبدیل می‌کند. اگر مقدار قابل تجزیه نباشد (مثلاً شیء دارای یک چرخه باشد)، متد مقدار undefined برمی‌گرداند.

نحو 

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

پارامترها

تجزیه JSON

پارامتر نوع توضیحات
ورودی رشته‌ای هر مقداری که باید تبدیل شود. اگر مقدار رشته نباشد، ورودی به اجبار به یک رشته تبدیل می‌شود.

رشته‌ای‌سازی JSON

پارامتر نوع توضیحات
ارزش هر مقداری که باید تبدیل شود.

مثال 

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

localStorage

یک شیء با متدهایی برای دسترسی به فضای ذخیره‌سازی محلی برمی‌گرداند.

نحو 

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

مجوزهای مرتبط

access_local_storage

مثال 

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

آرگومان‌ها را در کنسول مرورگر ثبت می‌کند.

نحو

logToConsole(obj1 [, obj2,... objN])

پارامترها

پارامتر نوع توضیحات
obj1 [, obj2,... objN] هر استدلال‌ها

مجوزهای مرتبط

logging

makeInteger

مقدار داده شده را به یک عدد (عدد صحیح) تبدیل می‌کند.

نحو

makeInteger(value)

پارامترها

پارامتر نوع توضیحات
value هر مقداری که باید تبدیل شود.

مجوزهای مرتبط

هیچ کدام.

makeNumber

مقدار داده شده را به عدد تبدیل می‌کند.

نحو

makeNumber(value)

پارامترها

پارامتر نوع توضیحات
value هر مقداری که باید تبدیل شود.

مجوزهای مرتبط

هیچ کدام.

makeString

مقدار داده شده را به صورت یک رشته برمی‌گرداند.

نحو

makeString(value)

پارامترها

پارامتر نوع توضیحات
value هر مقداری که باید تبدیل شود.

مجوزهای مرتبط

هیچ کدام.

makeTableMap

یک شیء جدول ساده با دو ستون را به یک Map تبدیل می‌کند. این برای تغییر یک فیلد قالب SIMPLE_TABLE با دو ستون به قالبی قابل مدیریت‌تر استفاده می‌شود.

برای مثال، این تابع می‌تواند یک شیء جدول را تبدیل کند: 

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

به یک نقشه: 

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

یک شیء را برمی‌گرداند: اگر جفت‌های کلید-مقدار به Map تبدیل شده اضافه شده باشند، و در غیر این صورت null .

نحو

makeTableMap(tableObj, keyColumnName, valueColumnName)

پارامترها

پارامتر نوع توضیحات
tableObj فهرست شیء جدول برای تبدیل. این فهرستی از نقشه‌ها است که در آن هر Map نشان دهنده یک ردیف در جدول است. نام هر ویژگی در یک شیء ردیف، نام ستون است و مقدار ویژگی، مقدار ستون در ردیف است.
keyColumnName رشته نام ستونی که مقادیر آن در Map تبدیل‌شده به کلید تبدیل خواهند شد.
valueColumnName رشته نام ستونی که مقادیر آن به مقادیر موجود در Map تبدیل شده تبدیل خواهند شد.

مجوزهای مرتبط

هیچ کدام.

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

پارامترها

پارامترهای توابع ریاضی به اعداد تبدیل می‌شوند.

مجوزهای مرتبط

هیچ کدام.

Object

یک شیء را برمی‌گرداند که متدهای Object methods) را ارائه می‌دهد.

متد keys() رفتار کتابخانه استاندارد Object.keys() را ارائه می‌دهد. این متد آرایه‌ای از نام‌های ویژگی‌های قابل شمارش یک شیء داده شده را به همان ترتیبی که یک حلقه for...in... برمی‌گرداند، برمی‌گرداند. اگر مقدار ورودی یک شیء نباشد، به یک شیء منتقل می‌شود.

متد values() رفتار کتابخانه استاندارد Object.values() را ارائه می‌دهد. این متد آرایه‌ای از مقادیر ویژگی‌های قابل شمارش یک شیء داده شده را به همان ترتیبی که یک حلقه for...in... برمی‌گرداند، برمی‌گرداند. اگر مقدار ورودی یک شیء نباشد، به یک شیء منتقل می‌شود.

متد entries() رفتار کتابخانه استاندارد Object.entries() را ارائه می‌دهد. این متد آرایه‌ای از جفت‌های ویژگی قابل شمارش [key, value] یک شیء داده شده را به همان ترتیبی که یک حلقه for...in... انجام می‌دهد، برمی‌گرداند. اگر مقدار ورودی یک شیء نباشد، به یک شیء منتقل می‌شود.

متد freeze() رفتار کتابخانه استاندارد Object.freeze() را ارائه می‌دهد. یک شیء منجمد دیگر قابل تغییر نیست؛ منجمد کردن یک شیء از اضافه شدن ویژگی‌های جدید به آن، حذف ویژگی‌های موجود و تغییر مقادیر ویژگی‌های موجود جلوگیری می‌کند. freeze() همان شیء ارسال شده را برمی‌گرداند. یک آرگومان اولیه یا تهی مانند یک شیء منجمد رفتار می‌شود و بازگردانده می‌شود.

متد delete() رفتار عملگر حذف کتابخانه استاندارد را ارائه می‌دهد. این متد کلید داده شده را از شیء حذف می‌کند، مگر اینکه شیء فریز شده باشد. مانند عملگر حذف کتابخانه استاندارد، اگر مقدار ورودی اول ( objectInput ) شیء‌ای باشد که فریز نشده باشد، حتی اگر مقدار ورودی دوم ( keyToDelete ) کلیدی را مشخص کند که وجود ندارد، true true را برمی‌گرداند. در سایر موارد مقدار false را برمی‌گرداند. با این حال، این متد از جهات زیر با عملگر حذف کتابخانه استاندارد متفاوت است:

  • keyToDelete نمی‌تواند یک رشته‌ی جدا شده با نقطه باشد که یک کلید تو در تو را مشخص می‌کند.
  • delete() نمی‌توان برای حذف عناصر از یک آرایه استفاده کرد.
  • delete() cannot be used to remove any properties from the global scope.

نحو 

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

پارامترها

کلیدهای شیء

پارامتر نوع توضیحات
ورودی شیء هر شیء‌ای که کلیدهای آن شمارش می‌شوند. اگر ورودی یک شیء نباشد، به یک شیء تحمیل می‌شود.

مقادیر شیء

پارامتر نوع توضیحات
ورودی شیء هر شیء‌ای که مقادیر آن شمارش می‌شوند. اگر ورودی یک شیء نباشد، به یک شیء تحمیل می‌شود.

ورودی‌های شیء

پارامتر نوع توضیحات
ورودی شیء هر شیء که جفت‌های کلید/مقدار آن برای شمارش استفاده می‌شوند. اگر ورودی یک شیء نباشد، به یک شیء تحمیل می‌شود.

شیء.متوقف کردن

پارامتر نوع توضیحات
ورودی شیء هر شیء مورد نظر برای فریز کردن. اگر ورودی یک شیء نباشد، به عنوان یک شیء فریز شده در نظر گرفته می‌شود.

حذف شیء

پارامتر نوع توضیحات
ورودی شیء هر شیء که کلید آن حذف می‌شود.
کلید برای حذف رشته کلید سطح بالا برای حذف.

مثال 

const Object = require('Object');

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

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

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

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

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

parseUrl

شیء‌ای را برمی‌گرداند که شامل تمام اجزای یک URL مشخص است، مشابه شیء URL .

این API برای هر URL ناقص، undefined برمی‌گرداند. برای URLهای با فرمت صحیح، فیلدهایی که در رشته URL وجود ندارند، مقدار یک رشته خالی یا در مورد searchParams ، یک شیء خالی خواهند داشت.

شیء برگشتی فیلدهای زیر را خواهد داشت: 

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

مثال 

const parseUrl = require('parseUrl');

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

نحو

parseUrl(url);

پارامترها

پارامتر نوع توضیحات
url رشته آدرس اینترنتی کاملی که تجزیه و تحلیل خواهد شد.

مجوزهای مرتبط

هیچ کدام.

queryPermission

پرس و جو در مورد مجوزهای مجاز و محدود شده. یک مقدار بولی برمی‌گرداند: اگر مجوزی اعطا شده باشد، true و در غیر این صورت false .

نحو

queryPermission(permission, functionArgs*)

پارامترها

پارامتر نوع توضیحات
permission رشته نام مجوز.
functionArgs هر آرگومان‌های تابع بر اساس مجوزی که درخواست می‌شود متفاوت هستند. به آرگومان‌های تابع در زیر مراجعه کنید.

آرگومان‌های تابع

sendPixel ، injectScript ، injectHiddenIframe : پارامتر دوم باید یک رشته URL باشد.

writeGlobals , readGlobals : پارامتر دوم باید کلیدی باشد که نوشته یا خوانده می‌شود.

readUrl : برای بررسی اینکه آیا کل URL قابل خواندن است یا خیر، هیچ آرگومان اضافی لازم نیست. برای بررسی اینکه آیا یک کامپوننت مشخص قابل خواندن است یا خیر، نام کامپوننت را به عنوان آرگومان دوم ارسال کنید: 

if (queryPermission('readUrl','port')) {
  // read the port
}

برای بررسی اینکه آیا یک کلید پرس‌وجوی خاص قابل خواندن است یا خیر، کلید پرس‌وجو را به عنوان پارامتر سوم ارسال کنید: 

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

مجوزهای مرتبط

هیچ کدام.

readAnalyticsStorage

داده‌های ذخیره شده برای تجزیه و تحلیل را بازیابی می‌کند و یک شیء با client_id و sessions را برمی‌گرداند.

  • client_id : رشته‌ای که نشان‌دهنده‌ی شناسه‌ی کلاینت مورد استفاده برای تجزیه و تحلیل است.
  • sessions : آرایه‌ای از اشیاء که حاوی اطلاعاتی در مورد sessionهای فعلی هستند. هر شیء شامل موارد زیر است:
    • measurement_id : رشته‌ای که نشان‌دهنده‌ی شناسه‌ی اندازه‌گیریِ Analytics Destination است.
    • session_id : رشته‌ای که نشان‌دهنده‌ی مهر زمانی است که جلسه‌ی فعلی را مشخص می‌کند.
    • session_number : عددی که تعداد جلساتی را که کاربر تا جلسه فعلی شروع کرده است، نشان می‌دهد.

نحو 

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

پارامترها

پارامتر نوع توضیحات
cookieOptions شیء گزینه‌های اختیاری برای خواندن کوکی‌ها با cookie_prefix ، cookie_domain یا cookie_path خاص.

مجوزهای مرتبط

read_analytics_storage

مثال 

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

مقدار document.characterSet را برمی‌گرداند.

نحو

readCharacterSet()

پارامترها

هیچ کدام.

مجوزهای مرتبط

read_character_set

readTitle

مقدار document.title را برمی‌گرداند.

نحو

readTitle()

پارامترها

هیچ کدام.

مجوزهای مرتبط

read_title

require

یک تابع داخلی را با نام وارد می‌کند. یک تابع یا شیء را که می‌تواند از برنامه شما فراخوانی شود، برمی‌گرداند. وقتی مرورگر از تابع داخلی پشتیبانی نمی‌کند، مقدار undefined را برمی‌گرداند.

نحو

require(name)

پارامترها

پارامتر نوع توضیحات
name رشته نام تابعی که قرار است وارد شود.

مثال 

const getUrl = require('getUrl');
const url = getUrl();

مجوزهای مرتبط

هیچ کدام.

sendPixel

یک درخواست GET به یک نقطه انتهایی URL مشخص شده ارسال می‌کند.

نحو

sendPixel(url, onSuccess, onFailure)

پارامترها

پارامتر نوع توضیحات
url رشته پیکسل را به کجا ارسال کنیم.
onSuccess تابع وقتی پیکسل با موفقیت بارگذاری می‌شود، فراخوانی می‌شود. توجه: حتی اگر درخواست با موفقیت ارسال شود، مرورگرها ممکن است برای اجرای onSuccess به یک پاسخ تصویر معتبر نیاز داشته باشند.
onFailure تابع زمانی فراخوانی می‌شود که پیکسل بارگذاری نشود. توجه: حتی اگر درخواست با موفقیت ارسال شود، اگر سرور پاسخ معتبری برای تصویر برنگرداند، ممکن است onFailure اجرا شود.

مجوزهای مرتبط

send_pixel

setCookie

کوکی را با نام، مقدار و گزینه‌های مشخص شده تنظیم یا حذف می‌کند.

نحو

setCookie(name, value[, options, encode])

پارامترها

پارامتر نوع توضیحات
name رشته نام کوکی.
value رشته ارزش کوکی.
options شیء ویژگی‌های دامنه (Domain)، مسیر (Path)، انقضا (Expires)، حداکثر سن (Max-Age)، امن (Secure) و سایت مشابه (SameSite ) را مشخص می‌کند. (به بخش گزینه‌ها (Options) در زیر مراجعه کنید.)
encode بولی کنترل می‌کند که آیا مقدار کوکی با encodeURIComponent() جاوااسکریپت کدگذاری شود یا خیر. مقدار پیش‌فرض true است.

گزینه‌ها

  • دامنه: در صورت وجود، توسط ویژگی options['domain'] تنظیم می‌شود. این مقدار را روی 'auto' تنظیم کنید تا سعی کند کوکی را با استفاده از وسیع‌ترین دامنه ممکن، بر اساس مکان سند، بنویسد. اگر این کار ناموفق باشد، زیردامنه‌های باریک‌تر را امتحان می‌کند. اگر همه آنها ناموفق باشند، سعی می‌کند کوکی را بدون دامنه بنویسد. اگر مقداری تنظیم نشود، این دستور سعی می‌کند کوکی را بدون دامنه مشخص شده بنویسد. توجه: وقتی یک کوکی بدون دامنه مشخص شده در document.cookie نوشته می‌شود، عامل کاربر دامنه کوکی را به طور پیش‌فرض روی میزبان مکان سند فعلی قرار می‌دهد.
  • مسیر: در صورت وجود، توسط options['path'] تنظیم می‌شود. وقتی یک کوکی بدون مسیر مشخص شده در document.cookie نوشته می‌شود، عامل کاربر مسیر کوکی را به طور پیش‌فرض به مسیر محل سند فعلی تغییر می‌دهد.
  • حداکثر سن: در صورت وجود، توسط options['max-age'] تنظیم می‌شود.
  • تاریخ انقضا: در صورت وجود، توسط options['expires'] تنظیم می‌شود. در صورت وجود، این باید یک رشته تاریخ با فرمت UTC باشد. می‌توان از Date.toUTCString() برای قالب‌بندی Date برای این پارامتر استفاده کرد.
  • امن: در صورت وجود، توسط options['secure'] تنظیم می‌شود.
  • SameSite: در صورت وجود، توسط options['samesite'] تنظیم می‌شود.

مجوزهای مرتبط

set_cookies

setDefaultConsentState

یک به‌روزرسانی پیش‌فرض رضایت‌نامه را به لایه داده ارسال می‌کند تا در اسرع وقت پس از اتمام پردازش رویداد فعلی و هر تگی که فعال شده است (یا رسیدن به زمان پایان پردازش تگ) پردازش شود. تضمین می‌شود که به‌روزرسانی در این کانتینر قبل از هر آیتم صف‌بندی شده در لایه داده پردازش شود. درباره رضایت‌نامه بیشتر بدانید .

مثال: 

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

نحو

setDefaultConsentState(consentSettings)

پارامترها

پارامتر نوع توضیحات
consentSettings شیء شیء‌ای که حالت پیش‌فرض را برای انواع رضایت مشخص‌شده تعریف می‌کند.

شیء consentSettings نگاشتی از رشته‌های نوع رضایت دلخواه به یکی از 'granted' یا 'denied' است. این شیء از مقادیر زیر پشتیبانی می‌کند:

نام کلید نوع توضیحات
consentType رشته مقدار هر نوع رضایت را می‌توان روی «اعطا شده» یا «رد شده» تنظیم کرد. هر مقداری غیر از «اعطا شده» به عنوان «رد شده» در نظر گرفته می‌شود. تنظیم مقدار روی «تعریف نشده» هیچ تاثیری روی مقدار قبلی آن نخواهد داشت.
region آرایه یک آرایه اختیاری از کدهای منطقه‌ای که مشخص می‌کند تنظیمات رضایت‌نامه برای کدام منطقه اعمال می‌شود. کدهای منطقه‌ای با استفاده از کشور و/یا تقسیمات کشوری در قالب ISO 3166-2 بیان می‌شوند.
wait_for_update شماره مقداری در میلی‌ثانیه برای کنترل مدت زمان انتظار قبل از ارسال داده‌ها مشخص می‌کند. با ابزارهای رضایت که به صورت ناهمزمان بارگذاری می‌شوند، استفاده می‌شود.

مجوزهای مرتبط

access_consent permission with write access for all consent types in the consentSettings object.

setInWindow

مقدار داده شده در window را در کلید داده شده تنظیم می‌کند. به طور پیش‌فرض، اگر مقداری از قبل در پنجره وجود داشته باشد، این متد مقدار را در window تنظیم نمی‌کند. overrideExisting را روی true تنظیم کنید تا مقدار در window صرف نظر از وجود مقدار موجود تنظیم شود. یک مقدار بولی برمی‌گرداند: اگر مقدار با موفقیت تنظیم شده باشد، true و در غیر این صورت false .

نحو

setInWindow(key, value, overrideExisting)

پارامترها

پارامتر نوع توضیحات
key رشته کلید موجود در window برای قرار دادن مقدار در آن.
value * مقداری که باید در window تنظیم شود.
overrideExisting بولی پرچمی که نشان می‌دهد آن مقدار باید در window تنظیم شود، صرف نظر از اینکه مقداری در آنجا وجود دارد یا خیر.

مجوزهای مرتبط

access_globals

sha256

خلاصه SHA-256 ورودی را محاسبه می‌کند و یک فراخوانی برگشتی با خلاصه کدگذاری شده در base64 فراخوانی می‌کند، مگر اینکه شیء options کدگذاری خروجی متفاوتی را مشخص کند.

مثال: 

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

نحو

sha256(input, onSuccess, onFailure = undefined, options = undefined)

پارامترها

پارامتر نوع توضیحات
input رشته رشته‌ای که هش برای آن محاسبه می‌شود.
onSuccess تابع با خلاصه‌ی حاصل که با base64 کدگذاری شده است، فراخوانی می‌شود، مگر اینکه شیء options کدگذاری خروجی متفاوتی را مشخص کند.
onFailure تابع اگر هنگام محاسبه خلاصه خطا خطایی رخ دهد، یا اگر مرورگر پشتیبانی بومی از sha256 نداشته باشد، فراخوانی می‌شود. تابع فراخوانی با یک شیء حاوی نام خطا و پیام فراخوانی می‌شود.
options شیء گزینه‌های اختیاری شیء برای مشخص کردن کدگذاری خروجی. در صورت مشخص شدن، شیء باید حاوی کلید outputEncoding با مقدار یکی از base64 یا hex باشد.

مجوزهای مرتبط

هیچ کدام.

templateStorage

یک شیء با متدهایی برای دسترسی به فضای ذخیره‌سازی الگو برمی‌گرداند. فضای ذخیره‌سازی الگو امکان اشتراک‌گذاری داده‌ها را در طول اجرای یک الگوی واحد فراهم می‌کند. داده‌های ذخیره‌شده در فضای ذخیره‌سازی الگو در طول عمر صفحه باقی می‌مانند.

نحو 

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

مجوزهای مرتبط

access_template_storage

مثال 

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

رابط برنامه‌نویسی کاربردی toBase64 به شما امکان می‌دهد یک رشته را به صورت نمایش base64 کدگذاری کنید.

نحو

toBase64(input)

پارامترها

پارامتر نوع توضیحات
input رشته رشته برای رمزگذاری.

مثال 

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

مجوزهای مرتبط

هیچکدام

updateConsentState

یک به‌روزرسانی رضایت‌نامه را به لایه داده ارسال می‌کند تا در اسرع وقت پس از اتمام پردازش رویداد فعلی و هر تگی که فعال شده است (یا رسیدن به زمان پایان پردازش تگ) پردازش شود. تضمین می‌شود که به‌روزرسانی در این کانتینر قبل از هر آیتم صف‌بندی شده در لایه داده پردازش شود. درباره رضایت‌نامه بیشتر بدانید .

مثال: 

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

نحو

updateConsentState(consentSettings)

پارامترها

پارامتر نوع توضیحات
consentSettings شیء شیء‌ای که وضعیت را برای انواع رضایت مشخص‌شده به‌روزرسانی می‌کند.

شیء consentSettings نگاشتی از رشته‌های نوع رضایت دلخواه به یکی از 'granted' یا 'denied' است. این شیء از مقادیر زیر پشتیبانی می‌کند:

نام کلید نوع توضیحات
consentType رشته مقدار هر نوع رضایت را می‌توان روی «اعطا شده» یا «رد شده» تنظیم کرد. هر مقداری غیر از «اعطا شده» به عنوان «رد شده» در نظر گرفته می‌شود. تنظیم مقدار روی «تعریف نشده» هیچ تاثیری روی مقدار قبلی آن نخواهد داشت.

مجوزهای مرتبط

مجوز access_consent با دسترسی نوشتن برای همه انواع رضایت‌نامه در شیء consentSettings.

API های تست

این APIها با تست‌های جاوا اسکریپتِ سندباکس‌شده کار می‌کنند تا تست‌هایی برای قالب‌های سفارشی در گوگل تگ منیجر بسازند. این APIهای تست نیازی به دستور require() ندارند. درباره تست‌های قالب سفارشی بیشتر بدانید .

assertApi

یک شیء تطبیق‌دهنده را برمی‌گرداند که می‌تواند برای ایجاد عبارات شرطی (assertions) در مورد API داده شده مورد استفاده قرار گیرد.

نحو

assertApi(apiName)

پارامترها

پارامتر نوع توضیحات
apiName رشته نام API که باید بررسی شود؛ همان رشته‌ای که به require() ارسال شده است.

تطبیق‌دهنده‌ها

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

مثال‌ها 

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

assertThat

رابط برنامه‌نویسی کاربردی assertThat از کتابخانه [Truth] گوگل الگوبرداری شده است. این رابط، شیء‌ای را برمی‌گرداند که می‌تواند برای ایجاد روانِ ادعاها (assertions) در مورد مقدار یک موضوع (subject) مورد استفاده قرار گیرد. شکست در ادعا، بلافاصله آزمون را متوقف کرده و آن را به عنوان شکست خورده علامت‌گذاری می‌کند. با این حال، شکست در یک آزمون، سایر موارد آزمون را تحت تأثیر قرار نمی‌دهد.

نحو

assertThat(actual, opt_message)

پارامترها

پارامتر نوع توضیحات
actual هر مقداری که در بررسی‌های fluent استفاده می‌شود.
opt_message رشته پیام اختیاری که در صورت عدم موفقیت در تأیید، چاپ می‌شود.

تطبیق‌دهنده‌ها

تطبیق دهنده توضیحات
isUndefined() ادعا می‌کند که موضوع undefined است.
isDefined() ادعا می‌کند که موضوع undefined نیست.
isNull() ادعا می‌کند که موضوع null است.
isNotNull() ادعا می‌کند که موضوع null نیست.
isFalse() ادعا می‌کند که موضوع false است.
isTrue() ادعا می‌کند که موضوع true است.
isFalsy() ادعا می‌کند که موضوع نادرست است. مقادیر نادرست عبارتند از undefined ، null ، false ، NaN ، 0 و '' (رشته خالی).
isTruthy() ادعا می‌کند که موضوع درست است. مقادیر نادرست عبارتند از undefined ، null ، false ، NaN ، 0 و '' (رشته خالی).
isNaN() ادعا می‌کند که موضوع، مقدار NaN است.
isNotNaN() ادعا می‌کند که موضوع هر مقداری غیر از NaN است.
isInfinity() ادعا می‌کند که موضوع، مثبت یا منفی بی‌نهایت است.
isNotInfinity() ادعا می‌کند که موضوع، هر مقداری علاوه بر بی‌نهایت مثبت یا منفی است.
isEqualTo(expected) ادعا می‌کند که موضوع برابر با مقدار داده شده است. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
isNotEqualTo(expected) ادعا می‌کند که موضوع با مقدار داده شده برابر نیست. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
isAnyOf(...expected) ادعا می‌کند که موضوع برابر با یکی از مقادیر داده شده است. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
isNoneOf(...expected) ادعا می‌کند که موضوع با هیچ یک از مقادیر داده شده برابر نیست. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
isStrictlyEqualTo(expected) ادعا می‌کند که موضوع کاملاً برابر ( === ) با مقدار داده شده است.
isNotStrictlyEqualTo(expected) ادعا می‌کند که موضوع کاملاً برابر ( !== ) با مقدار داده شده نیست.
isGreaterThan(expected) ادعا می‌کند که موضوع از ( > ) مقدار داده شده در یک مقایسه مرتب بزرگتر است.
isGreaterThanOrEqualTo(expected) ادعا می‌کند که موضوع در یک مقایسه ترتیبی، بزرگتر یا مساوی ( >= ) مقدار داده شده است.
isLessThan(expected) ادعا می‌کند که موضوع در یک مقایسه مرتب، کوچکتر از ( < ) مقدار داده شده است.
isLessThanOrEqualTo(expected) ادعا می‌کند که موضوع در یک مقایسه ترتیبی، کوچکتر یا مساوی ( <= ) مقدار داده شده است.
contains(...expected) ادعا می‌کند که موضوع یک آرایه یا رشته است که شامل تمام مقادیر داده شده به هر ترتیبی است. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
doesNotContain(...expected) ادعا می‌کند که موضوع یک آرایه یا رشته است که هیچ یک از مقادیر داده شده را شامل نمی‌شود. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
containsExactly(...expected) ادعا می‌کند که موضوع، آرایه‌ای است که شامل تمام مقادیر داده شده به هر ترتیبی است و هیچ مقدار دیگری ندارد. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
doesNotContainExactly(...expected) ادعا می‌کند که موضوع، آرایه‌ای است که شامل مجموعه‌ای متفاوت از مقادیر داده شده به هر ترتیبی است. این یک مقایسه مقداری است، نه یک مقایسه مرجع. محتویات اشیاء و آرایه‌ها به صورت بازگشتی مقایسه می‌شوند.
hasLength(expected) ادعا می‌کند که موضوع یک آرایه یا رشته با طول داده شده است. اگر مقدار، آرایه یا رشته نباشد، این ادعا همیشه با شکست مواجه می‌شود.
isEmpty() ادعا می‌کند که موضوع یک آرایه یا رشته خالی است (طول = 0). اگر مقدار، آرایه یا رشته نباشد، این ادعا همیشه با شکست مواجه می‌شود.
isNotEmpty() ادعا می‌کند که موضوع یک آرایه یا رشته است که خالی نیست (طول > 0). اگر مقدار یک آرایه یا رشته نباشد، این ادعا همیشه با شکست مواجه می‌شود.
isArray() ادعا می‌کند که نوع موضوع، آرایه است.
isBoolean() ادعا می‌کند که نوع موضوع از نوع بولی است.
isFunction() ادعا می‌کند که نوع موضوع یک تابع است.
isNumber() ادعا می‌کند که نوع موضوع عدد است.
isObject() ادعا می‌کند که نوع فاعل، شیء است.
isString() ادعا می‌کند که نوع موضوع، رشته است.

مثال‌ها 

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

fail

بلافاصله در آزمون فعلی شکست می‌خورد و در صورت ارائه، پیام داده شده را چاپ می‌کند.

نحو

fail(opt_message);

پارامترها

پارامتر نوع توضیحات
opt_message رشته متن پیام خطا اختیاری.

مثال 

fail('This test has failed.');

mock

API mock به شما امکان می‌دهد رفتار APIهای Sandboxed را نادیده بگیرید. استفاده از API ساختگی در کد قالب بی‌خطر است، اما فقط در حالت آزمایشی قابل اجرا است. قبل از اجرای هر آزمایش، نمونه‌های ساختگی بازنشانی می‌شوند.

نحو

mock(apiName, returnValue);

پارامترها

پارامتر نوع توضیحات
apiName رشته نام API که قرار است شبیه‌سازی شود؛ همان رشته‌ای که به require() ارسال شده است.
returnValue هر The value to return for the API or a function called in place of the API. If returnValue is a function, that function is called in place of the Sandboxed API; if returnValue is anything other than a function, that value is returned in place of the Sandboxed API.

مثال‌ها 

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

mockObject

The mockObject API lets you override the behavior of Sandboxed APIs that return an object. The API is safe to use in template code, but it is operational only in test mode. Mocks are reset before each test is run.

Syntax

mockObject(apiName, objectMock);

پارامترها

پارامتر نوع توضیحات
apiName رشته The name of the API to mock; same string as passed to require()
objectMock شیء The value to return for the API or a function called in place of the API. Must be an object.

مثال‌ها 

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

Runs the code for the template, ie the content of the Code tab, in the current test environment with a given input data object.

Syntax

runCode(data)

پارامترها

پارامتر نوع توضیحات
data شیء Data object to be used in the test.

مقدار بازگشتی

Returns the value of a variable for variable templates; returns undefined for all other template types.

مثال 

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