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

میاناهای برنامه‌سازی کاربردی اصلی

این میاناهای برنامه‌سازی کاربردی با جاوا اسکریپت جعبه شنی کار می‌کنند تا الگوهای سفارشی در «مدیر برچسب Google» بسازند. هر API با عبارت require() اضافه می‌شود، برای مثال:

const myAPI = require('myAPI');

addConsentListener

تابع شنونده‌ای را ثبت می‌کند تا وقتی وضعیت نوع رضایت مشخص‌شده تغییر می‌کند اجرا شود.

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

مثال:

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 boolean بولی که اگر نوع رضایت مشخص‌شده به «اعطاشده» تغییر کند، مقدار آن «درست» است.

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

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

addEventCallback

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

نحو

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

aliasInWindow API به شما امکان می‌دهد نام مستعار (مثلاً 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 با آرگومان‌های ارائه‌شده فراخوانی می‌کند و مقدار را برمی‌گرداند. اگر نوع پاسخ را نتوان مستقیماً به نوعی که در جاوا اسکریپت محدودشده پشتیبانی می‌شود نگاشت کرد، undefined برگردانده خواهد شد. هشت نوع پشتیبانی‌شده در JavaScript جعبه امن عبارت‌اند از 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 رشته کلید در قالب «a.b.c».
dataLayerVersion number نسخه لایه داده اختیاری. مقدار پیش‌فرض ۲ است. اکیداً توصیه می‌شود از مقدار ۱ استفاده نکنید.

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

read_data_layer

copyFromWindow

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

نحو

copyFromWindow(key)

پارامترها

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

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

access_globals

createArgumentsQueue

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

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

وقتی تابع ایجادشده تحت fnKey فراخوانی می‌شود، شیء آرگومان‌هایش را به آرایه ایجادشده تحت arrayKey ارسال می‌کند. مقدار برگشتی میانای برنامه‌سازی کاربردی تابع ایجادشده تحت 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 رشته شناسه منبع یکسانی که توسط 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 API به شما امکان می‌دهد رشته‌ها را از نمایش base64 آن‌ها رمزگشایی کنید. اگر ورودی نامعتبر ارائه شود، undefined را برمی‌گرداند.

نحو

fromBase64(base64EncodedString)

پارامترها

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

نمونه

const fromBase64 = require('fromBase64');

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

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

خالی

generateRandom

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

نحو

generateRandom(min, max)

پارامترها

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

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

هیچ‌کدام.

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 boolean کنترل می‌کند که آیا مقادیر کوکی با decodeURIComponent() جاوا اسکریپت رمزگشایی شوند یا نه. پیش‌فرض به true.

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

get_cookies

getQueryParameters

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

نحو

getQueryParameters(queryKey[, retrieveAll])

پارامترها

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

برای مثال، اگر نشانی وب فعلی 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

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

نحو

getReferrerQueryParameters(queryKey[, retrieveAll])

پارامترها

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

برای مثال، اگر نشانی وب ارجاع‌دهنده 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 شیء سند را برای ارجاع‌دهنده می‌خواند و رشته‌ای را برمی‌گرداند که نشان‌دهنده بخشی از ارجاع‌دهنده است. اگر مؤلفه‌ای مشخص نشده باشد، نشانی وب کامل ارجاع‌دهنده برگردانده می‌شود.

نحو

getReferrerUrl([component])

پارامترها

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

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

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

getTimestamp

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

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

نحو

getTimestamp();

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

هیچ‌کدام.

getTimestampMillis

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

نحو

getTimestampMillis();

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

هیچ‌کدام.

getType

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

نحو

getType(data.someField)

یادداشت‌ها

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

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

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

هیچ‌کدام.

getUrl

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

نحو

getUrl(component)

پارامترها

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

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

get_url

gtagSet

فرمان تنظیم gtag را به لایه داده ارسال می‌کند تا در اسرع وقت پس‌از رویداد فعلی پردازش شود و پردازش هر برچسبی که راه‌اندازی کرده است به‌پایان برسد (یا زمان پردازش برچسب به‌پایان برسد). تضمین می‌شود که به‌روزرسانی قبل‌از هر مورد در صف لایه داده، در این محفظه پردازش شود.

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

نمونه:

const gtagSet = require('gtagSet');

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

نحو

gtagSet(object)

پارامترها

پارامتر نوع شرح
Object شیء شیئی که وضعیت سراسری را برای دارایی‌های حاوی آن به‌روز می‌کند.

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

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

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

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

injectHiddenIframe

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

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

نحو

injectHiddenIframe(url, onSuccess)

پارامترها

پارامتر نوع شرح
url رشته نشانی وبی که به‌عنوان مقدار مشخصه src iframe استفاده می‌شود.
onSuccess تابع وقتی قاب باموفقیت بار می‌شود، فراخوانی می‌شود.

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

inject_hidden_iframe

injectScript

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

نحو

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

پارامترها

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

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

inject_script

isConsentGranted

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

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

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

مثال:

const isConsentGranted = require('isConsentGranted');

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

نحو

isConsentGranted(consentType)

پارامترها

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

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

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

JSON

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

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

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

نحو

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

پارامترها

JSON.parse

پارامتر نوع شرح
stringInput any مقداری که باید تبدیل شود. اگر مقدار رشته نباشد، ورودی به رشته تبدیل خواهد شد.

JSON.stringify

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

نمونه

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] any آرگومان‌ها

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

logging

makeInteger

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

نحو

makeInteger(value)

پارامترها

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

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

هیچ‌کدام.

makeNumber

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

نحو

makeNumber(value)

پارامترها

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

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

هیچ‌کدام.

makeString

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

نحو

makeString(value)

پارامترها

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

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

هیچ‌کدام.

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 را ارائه می‌دهد.

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

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

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

روش freeze() رفتار Object.freeze() «کتابخانه استاندارد» را ارائه می‌دهد. شیء منجمدشده دیگر قابل‌تغییر نیست؛ منجمد کردن شیء مانع از اضافه شدن خصوصیات جدید به آن، برداشته شدن خصوصیات موجود، و تغییر مقادیر خصوصیات موجود می‌شود. ‫freeze() همان شیء را که ارسال شده است برمی‌گرداند. با آرگومان اولیه یا تهی طوری رفتار می‌شود که گویی شیء ثابتی است و برگردانده خواهد شد.

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

  • keyToDelete نمی‌تواند رشته‌ای با جداکننده نقطه باشد که کلید تودرتو را مشخص می‌کند.
  • از delete() نمی‌توان برای برداشتن عناصر از آرایه استفاده کرد.
  • از delete() نمی‌توان برای برداشتن هیچ‌یک از ویژگی‌ها از دامنه جهانی استفاده کرد.

نحو

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

پارامترها

Object.keys

پارامتر نوع شرح
objectInput any شیئی که کلیدهای آن باید شمارش شود. اگر ورودی شیء نباشد، به شیء تبدیل خواهد شد.

Object.values

پارامتر نوع شرح
objectInput any شیئی که مقادیر آن باید شمارش شود. اگر ورودی شیء نباشد، به شیء تبدیل خواهد شد.

Object.entries

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

Object.freeze

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

Object.delete

پارامتر نوع شرح
objectInput any شیئی که کلید آن حذف می‌شود.
keyToDelete رشته کلید سطح بالا برای حذف.

نمونه

const Object = require('Object');

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

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

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

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

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

parseUrl

شیئی را برمی‌گرداند که حاوی همه بخش‌های تشکیل‌دهنده نشانی وب داده‌شده است، مشابه شیء URL.

این میانای برنامه‌سازی کاربردی برای هر نشانی وب ناقصی undefined را برمی‌گرداند. برای نشانی‌های وب با قالب‌بندی صحیح، فیلدهایی که در رشته نشانی وب وجود ندارند، مقدار رشته خالی خواهند داشت، یا در مورد 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 any آرگومان‌های تابع براساس اجازه‌ای که درخواست می‌شود متفاوت است. آرگومان‌های تابع را در زیر ببینید.

متغیرهای مستقل تابع

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

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

readUrl: برای پُرسمان اینکه آیا کل نشانی وب قابل‌خواندن است یا نه، به متغیرهای مستقل دیگری نیاز نیست. برای پرسمان اینکه آیا مؤلفه داده‌شده قابل‌خواندن است یا نه، نام مؤلفه را به‌عنوان آرگومان دوم ارسال کنید:

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

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

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

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

هیچ‌کدام.

readAnalyticsStorage

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

  • ‫client_id: رشته‌ای که شناسه مشتری مورداستفاده برای تجزیه‌وتحلیل را نشان می‌دهد.
  • sessions: آرایه‌ای از اشیای حاوی اطلاعات درباره جلسه‌های فعلی. هر شیء شامل موارد زیر است:
    • ‫measurement_id: رشته‌ای که شناسه سنجش مقصد Analytics را نشان می‌دهد.
    • ‫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 به نقطه پایانی نشانی وب مشخص‌شده ارسال می‌کند.

نحو

sendPixel(url, onSuccess, onFailure)

پارامترها

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

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

send_pixel

setCookie

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

نحو

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

پارامترها

پارامتر نوع شرح
name رشته نام کوکی.
value رشته مقدار کوکی.
options شیء مشخصه‌های دامنه، مسیر، انقضا، حداکثر سن، ایمن، و SameSite را مشخص می‌کند. (گزینه‌ها را در زیر ببینید.)
encode boolean کنترل می‌کند که آیا مقدار کوکی باید با encodeURIComponent() جاوا اسکریپت کدبندی شود یا نه. پیش‌فرض‌ها به true.

گزینه‌ها

  • دامنه: توسط ویژگی options['domain'] تنظیم می‌شود، درصورت وجود. این مقدار را روی 'auto' تنظیم کنید تا کوکی بااستفاده از گسترده‌ترین دامنه ممکن، براساس مکان سند، نوشته شود. اگر این کار ناموفق باشد، به‌طور متوالی زیردامنه‌های محدودتر را امتحان می‌کند. اگر همه این‌ها ناموفق باشد، سعی می‌کند کوکی را بدون دامنه بنویسد. اگر مقداری تنظیم نشده باشد، این مورد سعی می‌کند کوکی را بدون دامنه مشخص‌شده بنویسد. توجه: وقتی کوکی بدون دامنه مشخص‌شده‌ای در document.cookie نوشته می‌شود، نماینده کاربر دامنه کوکی را به‌طور پیش‌فرض روی میزبان مکان سند فعلی تنظیم می‌کند.
  • مسیر: تنظیم‌شده توسط options['path']، درصورت وجود. وقتی کوکی بدون مسیر مشخصی در document.cookie نوشته می‌شود، نماینده کاربر به‌طور پیش‌فرض مسیر کوکی را روی مسیر مکان سند فعلی تنظیم می‌کند.
  • Max-Age: که توسط 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 رشته مقدار هر نوع رضایت را می‌توان روی `'granted'` (اعطاشده) یا `'denied'` (ردشده) تنظیم کرد. هر مقداری غیراز `'granted'` (اعطاشده) به‌عنوان `'denied'` (ردشده) درنظر گرفته می‌شود. تنظیم مقدار روی `undefined` (تعریف‌نشده) هیچ تأثیری بر مقدار قبلی آن نخواهد داشت.
region آرایه آرایه اختیاری از کدهای منطقه که مشخص می‌کند تنظیمات رضایت در کدام منطقه اعمال می‌شود. کدهای منطقه بااستفاده از کشور و/یا بخش‌های فرعی در قالب ISO 3166-2 بیان می‌شوند.
wait_for_update number مقدار میلی‌ثانیه‌ای را برای کنترل مدت زمان انتظار قبل‌از ارسال داده‌ها مشخص می‌کند. با ابزارهای رضایت که به‌صورت ناهمگام بار می‌شوند استفاده می‌شود.

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

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

setInWindow

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

نحو

setInWindow(key, value, overrideExisting)

پارامترها

پارامتر نوع شرح
key رشته کلید در window برای قرار دادن مقدار در آن.
value * مقداری که باید در window تنظیم شود.
overrideExisting boolean پرچمی که نشان می‌دهد مقدار باید در 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 API به شما امکان می‌دهد رشته‌ای را به نمایش 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 رشته مقدار هر نوع رضایت را می‌توان روی «اعطاشده» یا «ردشده» تنظیم کرد. هر مقداری غیراز «granted» (اعطاشده) به‌عنوان «denied» (ردشده) درنظر گرفته می‌شود. تنظیم مقدار روی «undefined» هیچ تأثیری بر مقدار قبلی آن نخواهد داشت.

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

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

میاناهای برنامه‌سازی کاربردی آزمایشی

این میاناهای برنامه‌سازی کاربردی با آزمایش‌های جاوا اسکریپت جعبه امن کار می‌کنند تا آزمایش‌هایی برای الگوهای سفارشی در Google Tag Manager بسازند. این میاناهای برنامه‌سازی کاربردی آزمایشی به عبارت require() نیاز ندارند. درباره آزمایش‌های الگو سفارشی بیشتر بدانید.

assertApi

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

نحو

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 API از کتابخانه [Truth] Google الگوبرداری شده است. این متد شیئی را برمی‌گرداند که می‌توان از آن برای ایجاد ادعاهای روان درباره مقدار موضوع استفاده کرد. شکست در اثبات بلافاصله آزمایش را متوقف می‌کند و آن را به‌عنوان ناموفق علامت‌گذاری می‌کند. بااین‌حال، شکست در یک آزمایش بر چارچوب‌های تست دیگر تأثیر نخواهد گذاشت.

نحو

assertThat(actual, opt_message)

پارامترها

پارامتر نوع شرح
actual any مقداری که باید در بررسی‌های روان استفاده شود.
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

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

نحو

mock(apiName, returnValue);

پارامترها

پارامتر نوع شرح
apiName رشته نام API برای شبیه‌سازی؛ همان رشته‌ای که به require() ارسال شده است
returnValue any مقداری که برای API یا تابع فراخوانی‌شده به‌جای API برگردانده می‌شود. اگر returnValue تابع باشد، آن تابع به‌جای Sandboxed API فراخوانی می‌شود؛ اگر returnValue هر چیزی به‌جز تابع باشد، آن مقدار به‌جای Sandboxed API برگردانده می‌شود.

نمونه‌ها

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

mockObject

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

نحو

mockObject(apiName, objectMock);

پارامترها

پارامتر نوع شرح
apiName رشته نام API برای شبیه‌سازی؛ همان رشته‌ای که به require() ارسال شده است
objectMock شیء مقداری که برای API یا تابع فراخوانی‌شده به‌جای API برگردانده می‌شود. باید شیء باشد.

نمونه‌ها

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

runCode

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

نحو

runCode(data)

پارامترها

پارامتر نوع شرح
data شیء مورد داده‌ای که باید در آزمایش استفاده شود.

برگرداندن مقدار

مقدار متغیر را برای الگوهای متغیر برمی‌گرداند؛ برای همه انواع الگوهای دیگر، undefined را برمی‌گرداند.

نمونه

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