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

API های اصلی

این APIها با جاوا اسکریپت sandboxed برای ایجاد قالب های سفارشی در Google Tag Manager کار می کنند. هر 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 بولی یک بولی که اگر نوع رضایت مشخص شده به اعطا شده تغییر کند درست است.

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

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

addEventCallback

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

نحو

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 با آرگومان های داده شده فراخوانی می کند و مقدار را برمی گرداند. اگر نوع برگشتی را نتوان مستقیماً به یک نوع پشتیبانی شده در جاوا اسکریپت sandboxed نگاشت، undefined برگردانده می شود. هشت نوع پشتیبانی شده در جاوا اسکریپت سندباکس عبارتند از 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 شماره نسخه لایه داده اختیاری. مقدار پیش فرض 2 است. به شدت از استفاده از مقدار 1 خودداری می شود.

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

read_data_layer

copyFromWindow

یک متغیر را از شی window کپی می کند. اگر مقدار موجود در window را نتوان مستقیماً با یک نوع پشتیبانی شده در جاوا اسکریپت sandbox شده نگاشت، undefined برگردانده می شود. هشت نوع پشتیبانی شده در جاوا اسکریپت سندباکس عبارتند از 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 API به شما امکان می دهد رشته ها را از نمایش 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 URL فعلی برمی‌گرداند. اولین مقدار را از queryKey یا آرایه ای از مقادیر را از queryKey برمی گرداند.

نحو

getQueryParameters(queryKey[, retrieveAll])

پارامترها

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

برای مثال، اگر URL فعلی 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 عمل می کند، با این تفاوت که به جای URL فعلی روی ارجاع دهنده عمل می کند. اولین یا همه پارامترها را برای queryKey ارجاع دهنده داده شده برمی گرداند. اولین مقدار را از queryKey یا آرایه ای از مقادیر را از queryKey برمی گرداند.

نحو

getReferrerQueryParameters(queryKey[, retrieveAll])

پارامترها

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

به عنوان مثال، اگر URL ارجاع دهنده 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 در کلیدهای query مجاز مشخص کند (یا هر کلید پرس و جو را مجاز می کند.)

getReferrerUrl

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

نحو

getReferrerUrl([component])

پارامترها

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

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

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

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 شی شی ای که حالت جهانی را برای ویژگی های حاوی آن به روز می کند.

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

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() یک رشته JSON را برای ساخت مقدار یا شی توصیف شده توسط رشته تجزیه می کند. اگر مقدار قابل تجزیه نباشد (به عنوان مثال JSON دارای شکل نادرست)، تابع undefined برمی گردد. اگر مقدار ورودی یک رشته نباشد، ورودی به یک رشته اجباری می شود.

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

نحو

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

پارامترها

JSON.parse

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

JSON.stringify

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

مثال 

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

keys() رفتار Standard Library Object.keys() را ارائه می دهد. آرایه ای از نام ویژگی های شمارش پذیر یک شی معین را به همان ترتیبی که یک حلقه for...in... برمی گرداند. اگر مقدار ورودی یک شی نباشد، به یک شی اجباری می شود.

متد values() رفتار Standard Library Object.values() را ارائه می کند. آرایه ای از مقادیر ویژگی های شمارش پذیر خود یک شی معین را به همان ترتیبی که حلقه for...in... برمی گرداند. اگر مقدار ورودی یک شی نباشد، به یک شی اجباری می شود.

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

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

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

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

نحو

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

پارامترها

Object.keys

پارامتر تایپ کنید توضیحات
objectInput هر شیئی که کلیدهای آن شمارش شود. اگر ورودی یک شی نباشد، به یک شی اجباری می شود.

شیء. ارزش ها

پارامتر تایپ کنید توضیحات
objectInput هر شیئی که مقادیر آن را برشماریم. اگر ورودی یک شی نباشد، به یک شی اجباری می شود.

Object.entries

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

شیء.انجماد

پارامتر تایپ کنید توضیحات
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 رشته 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(...);
}

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

هیچ کدام

readCharacterSet

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

نحو

readCharacterSet()

پارامترها

هیچ کدام

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

read_character_set

readTitle

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

نحو

readTitle()

پارامترها

هیچ کدام

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

read_title

require

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

نحو

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 را مشخص می کند. ( گزینه ها را در زیر ببینید.)
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 با دسترسی نوشتن برای همه انواع رضایت در شیء consentSettings.

setInWindow

مقدار داده شده را در window در کلید داده شده تنظیم می کند. به طور پیش فرض اگر مقداری وجود داشته باشد، این روش مقدار را در window تنظیم نمی کند. برای تنظیم مقدار در window بدون توجه به وجود یک مقدار موجود، overrideExisting روی true تنظیم کنید. اگر مقدار با موفقیت تنظیم شده باشد یک Boolean : 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 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 رشته مقدار برای هر نوع رضایت را می توان روی "اعطا" یا "رد شده" تنظیم کرد. هر ارزشی غیر از "اعطا" به عنوان "رد شده" تلقی می شود. تنظیم مقدار روی "تعریف نشده" هیچ تاثیری بر مقدار قبلی آن نخواهد داشت.

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

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

تست API ها

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

assertApi

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

نحو

assertThat(actual, opt_message)

پارامترها

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

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

نحو

runCode(data)

پارامترها

پارامتر تایپ کنید توضیحات
data شی شی داده مورد استفاده در آزمون.

ارزش بازگشتی

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

مثال 

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