واجهات برمجة التطبيقات للنماذج المخصّصة

واجهات برمجة التطبيقات الأساسية

تعمل واجهات برمجة التطبيقات هذه مع JavaScript في وضع الحماية لإنشاء نماذج مخصّصة في Google إدارة العلامات. تتم إضافة كل واجهة برمجة تطبيقات مع عبارة 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 بتسجيل دالة استدعاء ستجعل أن يتم استدعاءها في نهاية الحدث. وسيتم استدعاء عملية معاودة الاتصال عند إجراء جميع علامات الحدث التي تم تنفيذها أو عند انقضاء مهلة الحدث في الصفحة. يتم تمرير قيمتين، رقم تعريف الحاوية التي تستدعي وكائن يحتوي على معلومات عن الحدث.

البنية

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 إنشاء اسم مستعار (مثل 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 باستخدام السمة المحددة الوسيطة وتُرجع القيمة. إذا تعذّر ربط نوع الإرجاع مباشرةً وهو نوع متوافق مع JavaScript موضوع في وضع الحماية، سيتم عرض 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 الرقم تعمل البيانات الاختيارية إصدار طبقة معينة. والقيمة الافتراضية هي 2. لا يُنصح بشدة أن استخدم القيمة 1.

الأذونات المرتبطة

read_data_layer

copyFromWindow

تنسخ متغيّرًا من عنصر window. إذا تعذّر إدخال القيمة في window بشكل مباشر إلى نوع متوافق مع JavaScript موضوع في وضع الحماية، undefined سيتم عاد. الأنواع الثمانية المتوافقة مع JavaScript في وضع الحماية هي null، undefined وboolean وnumber وstring وArray وObject وfunction. تعرض القيمة التي تم استرجاعها (وفرضها).

البنية

copyFromWindow(key)

المعلّمات

المعلمة النوع الوصف
key سلسلة المفتاح في window لنسخ قيمة.

الأذونات المرتبطة

access_globals

createArgumentsQueue

إنشاء قائمة انتظار مليئة بكائنات الوسيطات لدعم العلامة للحلول التي تتطلب ذلك.

إنشاء دالة في نطاق عمومي (أي window)، باستخدام الوسيطة fnKey (الدلالات نفسها مثل createQueue). بعد إنشاء الدالة، تنشئ واجهة برمجة التطبيقات هذه ينشئ مصفوفة في window (إذا لم تكن موجودة) باستخدام arrayKey الوسيطة.

عند استدعاء الدالة التي تم إنشاؤها ضمن 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 سلسلة يشير هذا المصطلح إلى عنوان URL تم ترميزه من قِبل encodeUri() أو بوسائل أخرى.

الأذونات المرتبطة

بلا عُري

decodeUriComponent

فك ترميز أي أحرف مشفرة في مكوّن معرّف الموارد المنتظم (URI) المقدَّم. تؤدي إلى إرجاع string التي تمثل مكوّن 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 منطقية تتحكّم في ما إذا كان سيتم فك ترميز قيم ملفات تعريف الارتباط باستخدام وJavaScript decodeURIComponent() الإعدادات التلقائية على true

الأذونات المرتبطة

get_cookies

getQueryParameters

عرض أول معلمات أو جميعها لعنوان URL الحالي queryKey. تعرض القيمة الأولى من 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 بالطريقة نفسها التي يتصرف بها 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 في مفاتيح طلب البحث المسموح بها (أو السماح بأي مفتاح استعلام).

getReferrerUrl

وبالنظر إلى نوع المكون، تقرأ واجهة برمجة التطبيقات كائن المستند للمحيل تُرجع سلسلة تمثل جزءًا من المُحيل. إذا لم يتم العثور على أي مكون المحدد، يتم عرض عنوان URL المُحيل بالكامل.

البنية

getReferrerUrl([component])

المعلّمات

المعلمة النوع الوصف
component سلسلة المكوِّن المطلوب عرضه من عنوان URL. يمكن أن تكون الحالة واحدة مما يلي: protocol، host، port، path، query، extension. في حال حذف قيمة component هي undefined أو null أو مع أحد هذه المكوّنات، فسيُكتب عنوان URL بأكمله عاد.

الأذونات المرتبطة

يجب أن تسمح get_referrer بالمكوِّن query، كما يجب أن تحدد queryKey في مفاتيح طلب البحث المسموح بها (أو السماح بأي مفتاح استعلام).

getTimestamp

تمّت إزالة هذا العمود. يُفضّل استخدام getTimestampMillis.

عرض رقم يمثل الوقت الحالي بالمللي ثانية منذ نظام التشغيل Unix حقبة، كما تم إرجاعها بواسطة Date.now().

البنية

getTimestamp();

الأذونات المرتبطة

بلا عُري

getTimestampMillis

عرض رقم يمثل الوقت الحالي بالمللي ثانية منذ نظام التشغيل Unix حقبة، كما تم إرجاعها بواسطة 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 إلى طبقة البيانات، لتتم معالجته فور بعد انتهاء الحدث الحالي وأي علامات تم تشغيلها المعالجة (أو انتهت مهلة معالجة العلامات). التحديث مضمون ستتم معالجته في هذه الحاوية قبل أي عناصر في قائمة الانتظار في طبقة البيانات قائمة الانتظار.

على سبيل المثال، في حال تم طلب الإذن من خلال علامة تم تنشيطها عند إعداد الموافقة، سيتم تنفيذ ما يلي: سيتم تطبيق التعديل قبل معالجة حدث الإعداد. أمثلة هي ضبط 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 غير مرئي إلى الصفحة

يتم توفير عمليات الاستدعاء كمثيلات للدالة، ويتم تضمينها في JavaScript. الدوال التي تستدعيها.

البنية

injectHiddenIframe(url, onSuccess)

المعلّمات

المعلمة النوع الوصف
url سلسلة عنوان URL الذي سيتم استخدامه كقيمة للسمة src في إطار iframe .
onSuccess الوظيفة يتم استدعاء هذا الإجراء عند تحميل الإطار بنجاح.

الأذونات المرتبطة

inject_hidden_iframe

injectScript

تتم إضافة علامة نص برمجي إلى الصفحة لتحميل عنوان URL المحدد بشكل غير متزامن. تشير رسالة الأشكال البيانية يتم توفير عمليات الاستدعاء كمثيلات للدوال ويتم تضمينها في JavaScript الدوال التي تستدعيها.

البنية

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

المعلّمات

المعلمة النوع الوصف
url سلسلة عنوان النص البرمجي المراد إدخاله.
onSuccess الوظيفة يتم استدعاء عند تحميل النص البرمجي بنجاح.
onFailure الوظيفة يتم استدعاء هذا الإجراء عند تعذُّر تحميل النص البرمجي.
cacheToken سلسلة سلسلة اختيارية تُستخدم للإشارة إلى عنوان URL الذي يجب أن يتم تخزينه مؤقتًا. في حال حذف هذه القيمة، فسيتم إنشاء عنصر نص برمجي واحد فقط تطلب منه JavaScript. وستؤدي أي محاولات إضافية للتحميل إلى الطريقتان onSuccess وonFailure المحدَّدتان قيد الانتظار إلى أن يتم تحميل النص البرمجي.

الأذونات المرتبطة

inject_script

isConsentGranted

تعرض القيمة "صحيح" إذا تم منح نوع الموافقة المحدّد.

يُؤخذ في الاعتبار منح الموافقة على نوع معيّن من أنواع الموافقة إذا كانت هذه الموافقة تم ضبط النوع على "تم منح الإذن" أو لم يتم تعيينها على الإطلاق. في حال ضبط نوع الموافقة على وأي قيمة أخرى سيتم اعتبارها غير ممنوحة.

ستوفر واجهة مستخدم أداة "إدارة العلامات من Google" لإعدادات العلامات خيارًا حَرِيق إذا كانت هناك علامة مُفعّلة دائمًا تستخدم واجهة برمجة التطبيقات هذه، تُعتبر الموافقة وسيتم إرجاع 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

تعرض القيمة المقدمة في شكل string.

البنية

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() ملف Object.keys() للمكتبة العادية. السلوك. يعرض صفيفًا من خاصية تعداد خاصة بكائن معين نفس الترتيب الذي يتم به التكرار الحلقي for...in.... إذا كانت قيمة الإدخال وليس كائنًا، فسيتم فرضه على كائن.

توفر الطريقة values() واجهة Object.values() للمكتبة العادية السلوك. يعرض صفيفًا من قيم الخصائص القابلة للتعداد لكائن معين. بالترتيب نفسه الذي يتم فيه إجراء التكرار الحلقي for...in.... إذا لم تكن قيمة الإدخال فسيتم فرضه على كائن.

توفّر الطريقة entries() واجهة برمجة التطبيقات العادية Object.entries(). السلوك. يعرض صفيفًا من خاصية تعداد خاصة بكائن معين أزواج [key, value] بالترتيب نفسه الذي تتبعه حلقة for...in.... إذا كانت قيمة الإدخال ليست كائنًا، فسيتم فرضها على كائن.

توفر الطريقة freeze() واجهة Object.freeze() للمكتبة العادية السلوك. لم يعد من الممكن تغيير الكائن المجمّد؛ ويمنع تجميد كائن إضافة المواقع الجديدة إليها، أو إزالة المواقع الحالية، وقيم المواقع الحالية من التغيير. تعرض freeze() نفس الكائن الذي تم تمريره. يتم التعامل مع الوسيطة الأساسية أو الفارغة على أنها إذا كان كائنًا مجمدًا وسيتم إعادته.

توفّر الطريقة delete() عامل تشغيل الحذف للمكتبة العادية. السلوك. وتؤدي هذه السياسة إلى إزالة المفتاح المحدّد من الكائن ما لم يتم تجميده. وكما هي الحال في عامل تشغيل حذف المكتبة العادية، تعرض الدالة true إذا كان الإدخال الأول القيمة (objectInput) هي كائن لا يتم تجميده حتى إذا كان الإدخال الثاني تحدد القيمة (keyToDelete) مفتاحًا غير موجود. يتم إرجاع false في جميع الحالات الأخرى. ومع ذلك، فهو يختلف عن عامل تشغيل حذف "المكتبة العادية" بالطرق التالية:

  • لا يمكن أن يكون keyToDelete سلسلة مفصولة بالنقاط تحدد مفتاحًا مدمجًا.
  • لا يمكن استخدام delete() لإزالة عناصر من مصفوفة.
  • لا يمكن استخدام delete() لإزالة أي خصائص من النطاق العمومي.

البنية

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

المعلّمات

Object.keys

المعلمة النوع الوصف
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.

ستعرض واجهة برمجة التطبيقات هذه undefined لأي عنوان URL مكتوب بشكل غير صحيح. للتنسيق الصحيح بالنسبة إلى عناوين URL، فإن الحقول غير الموجودة في سلسلة عنوان URL سيكون لها قيمة سلسلة فارغة، أو في حالة searchParams، كائن فارغ.

سيحتوي الكائن المعروض على الحقول التالية:

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

مثال

const parseUrl = require('parseUrl');

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

البنية

parseUrl(url);

المعلّمات

المعلمة النوع الوصف
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 كائن تحدد النطاق، سمات المسار وانتهاء الصلاحية والحدّ الأقصى للعمر والآمنة وسمة SameSite. (اطّلِع على الخيارات أدناه).
encode منطقية تتحكّم في ما إذا كان سيتم ترميز قيمة ملف تعريف الارتباط باستخدام وJavaScript 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 سلسلة يمكن ضبط قيمة كل نوع موافقة على "تم منح الإذن" أو "تم الرفض". وسيتم التعامل مع أي قيمة بخلاف `'granted'` على أنّها "'denied'". الإعداد ولن يكون للقيمة إلى "غير محددة" أي تأثير في قيمتها السابقة.
region مصفوفة مصفوفة اختيارية لرموز المناطق تحدد المنطقة التي التي تنطبق عليها إعدادات الموافقة يتم التعبير عن رموز المناطق باستخدام البلد. و/أو الأقسام الفرعية بتنسيق ISO 3166-2.
wait_for_update الرقم تحدِّد هذه السياسة قيمة مللي ثانية للتحكّم في مدة الانتظار قبل نقل البيانات. تم إرسالها. يتم استخدامها مع أدوات الموافقة التي يتم تحميلها بشكل غير متزامن.

الأذونات المرتبطة

إذن "access_consent" حاصل على إذن بتعديل المحتوى لجميع أنواع الموافقة في consentSettings.

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 سلسلة يمكن ضبط القيمة لكل نوع موافقة على "تم منح الإذن" أو "مرفوض". أي قيمة بخلاف "تم منح الإذن" سيتم التعامل معه على أنه "مرفوض". الإعداد القيمة إلى 'unbound' لن يكون لها أي تأثير على قيمته السابقة.

الأذونات المرتبطة

إذن "access_consent" حاصل على إذن بتعديل المحتوى لجميع أنواع الموافقة في consentSettings.

اختبار واجهات برمجة التطبيقات

تعمل واجهات برمجة التطبيقات هذه مع اختبارات JavaScript في وضع الحماية لإنشاء اختبارات مخصّصة النماذج في أداة "إدارة العلامات من Google" لا تحتاج واجهات برمجة التطبيقات التجريبية هذه إلى require(). الشخصي. مزيد من المعلومات عن اختبارات النماذج المخصّصة

assertApi

تعرض كائن مطابقة يمكن استخدامه للتأكيد على وجود تأكيدات حول واجهة برمجة التطبيقات المحددة.

البنية

assertApi(apiName)

المعلّمات

المعلمة النوع الوصف
apiName سلسلة اسم واجهة برمجة التطبيقات المطلوب التحقّق منها نفس السلسلة التي تم تمريرها إلى 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] من Google. تُرجع التي يمكن استخدامها للتعبير بطلاقة عن قيمة الموضوع. إنّ سيؤدي إخفاق التأكيد إلى إيقاف الاختبار فورًا ووضع علامة عليه كإخفاق. ومع ذلك، عدم تأثير الفشل في اختبار واحد على حالات الاختبار الأخرى.

البنية

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

تتيح لك واجهة برمجة التطبيقات mock إلغاء سلوك واجهات برمجة التطبيقات التي تم وضع الحماية لها. النموذج الوهمي يمكن استخدام واجهة برمجة التطبيقات بأمان في رمز النموذج، ولكنّها لا تعمل إلا في وضع الاختبار. وتتم إعادة ضبط النماذج قبل إجراء كل اختبار.

البنية

mock(apiName, returnValue);

المعلّمات

المعلمة النوع الوصف
apiName سلسلة اسم واجهة برمجة التطبيقات المطلوب محاكاةها نفس السلسلة التي تم تمريرها إلى require()
returnValue أيّ القيمة المطلوب عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاءها بدلاً من واجهة برمجة التطبيقات. إذا كانت returnValue دالة، يتم استدعاء هذه الدالة في مكان واجهة برمجة التطبيقات Sandboxed API إذا كانت السمة returnValue تمثّل أي قيمة أخرى من إحدى الدوال، يتم عرض هذه القيمة بدلاً من وضع الحماية واجهة برمجة التطبيقات.

أمثلة

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

mockObject

تتيح لك واجهة برمجة التطبيقات mockObject إلغاء سلوك واجهات برمجة التطبيقات ذات وضع الحماية التي لإرجاع كائن. يمكن استخدام واجهة برمجة التطبيقات بأمان في رمز النموذج، ولكنّها قابلة للتشغيل في وضع الاختبار فقط. وتتم إعادة ضبط النماذج قبل إجراء كل اختبار.

البنية

mockObject(apiName, objectMock);

المعلّمات

المعلمة النوع الوصف
apiName سلسلة اسم واجهة برمجة التطبيقات المطلوب محاكاةها نفس السلسلة التي تم تمريرها إلى require()
objectMock كائن القيمة المطلوب عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاءها بدلاً من واجهة برمجة التطبيقات. يجب أن تكون كائنًا.

أمثلة

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

runCode

لتشغيل رمز النموذج، أي محتوى علامة التبويب الرمز في بيئة الاختبار الحالية مع كائن بيانات إدخال معين.

البنية

runCode(data)

المعلّمات

المعلمة النوع الوصف
data كائن كائن البيانات المطلوب استخدامه في الاختبار.

القيمة المعروضة

لعرض قيمة متغير لنماذج المتغير؛ يُرجع undefined مقابل جميع أنواع النماذج الأخرى.

مثال

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