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

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

تعمل واجهات برمجة التطبيقات هذه مع 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 string نوع الموافقة المطلوب تفعيله للاستماع إلى التغييرات في الحالة
listener function الدالة التي سيتم تنفيذها عند تغيُّر حالة نوع الموافقة المحدَّد

عند استدعاء مستمع، سيتم تمريره بنوع الموافقة الذي يتم تغييره والقيمة الجديدة لنوع الموافقة هذا:

المَعلمة النوع الوصف
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 string مسار مفصول بنقاط إلى عنصر window حيث يجب نسخ قيمة إليه. يجب أن تكون جميع المكوّنات في المسار حتى المكوّن الأخير موجودة في عنصر window.
fromPath string مسار مفصول بنقاط إلى 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 string مسار مفصول بنقاط إلى الدالة في window لمحاولة الاستدعاء
args * الوسيطات التي سيتم تمريرها إلى الدالة.

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

access_globals مع تفعيل الإذن execute

callLater

تُحدِّد موعدًا لإجراء طلب إلى دالة بشكل غير متزامن. سيتم استدعاء الدالة بعد عرض الرمز الحالي. وهذا يعادل setTimeout(<function>, 0).

البنية

callLater(function)

المعلّمات

المَعلمة النوع الوصف
function function الدالة المطلوب استدعاءها.

copyFromDataLayer

تعرض القيمة المعينة حاليًا للمفتاح المحدد في طبقة البيانات: القيمة الموجودة في المفتاح المحدد إذا كان نوعًا أساسيًا أو دالة أو كائنًا حرفيًا، أو undefined بخلاف ذلك.

البنية

copyFromDataLayer(key[, dataLayerVersion])

المعلّمات

المَعلمة النوع الوصف
key string المفتاح بالتنسيق "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 string المفتاح في 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 string تمثّل هذه السمة المسار في window حيث تم ضبط الصفيف، إذا لم يكن متوفّرًا. تتيح هذه الوسيطة استخدام أسلوب التنقيط العادي. إذا لم يكن مسار المفتاح متوفّرًا، يتم طرح استثناء. وهذا يعني أنّه إذا كان arrayKey هو 'one.two'، ولم يكن هناك عنصر عام باسم 'one'، سيتم طرح استثناء.

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

access_globals

createQueue

تنشئ مصفوفة في window (إذا لم تكن موجودة) وتعرض دالة تدفع القيم إلى ذلك الصفيف.

تتطلّب هذه الوظيفة إعداد القراءة والكتابة لـ arrayKey في إذن access_globals.

مثال:

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

البنية

createQueue(arrayKey)

المعلّمات

المَعلمة النوع الوصف
arrayKey string المفتاح في 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) المقدَّم. لعرض سلسلة تمثّل مكوّن معرّف الموارد المنتظم (URI) الذي تم فك ترميزه. تعرِض القيمة undefined عند إدخال قيمة غير صالحة.

مثال:

const decode = require('decodeUriComponent');

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

البنية

decodeUriComponent(encoded_uri_component)

المعلّمات

المَعلمة النوع الوصف
encoded_uri_component string عنصر معرّف الموارد المنتظم (URI) الذي تم ترميزه باستخدام encodeUriComponent() أو بوسائل أخرى

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

بلا عُري

encodeUri

عرض معرّف موارد منتظم (URI) مُشفَّر من خلال ترميز الأحرف الخاصة تعرِض هذه الدالة سلسلة تمثّل السلسلة المقدَّمة التي تم ترميزها على أنّها معرّف موارد منتظم (URI). تعرِض القيمة undefined عند تقديم إدخال غير صالح (عنصر بديل وحيد).

مثال:

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

البنية

encodeUri(uri)

المعلّمات

المَعلمة النوع الوصف
uri string عنوان URI كامل

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

بلا عُري

encodeUriComponent

عرض معرّف موارد منتظم (URI) مُشفَّر من خلال ترميز الأحرف الخاصة تعرِض هذه الدالة سلسلة تمثّل السلسلة المقدَّمة التي تم ترميزها على أنّها معرّف موارد منتظم (URI). تعرِض القيمة undefined عند تقديم إدخال غير صالح (عنصر بديل وحيد).

مثال:

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

البنية

encodeUriComponent(str)

المعلّمات

المَعلمة النوع الوصف
str سلسلة نصية مكوّن من معرّف الموارد المنتظم (URI)

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

بلا عُري

fromBase64

تتيح لك واجهة برمجة التطبيقات fromBase64 فك ترميز السلاسل من تمثيل base64. تعرِض القيمة undefined عند تقديم إدخال غير صالح.

البنية

fromBase64(base64EncodedString)

المعلّمات

المَعلمة النوع الوصف
base64EncodedString string سلسلة Base64 مرمّزة.

مثال

const fromBase64 = require('fromBase64');

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

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

لا ينطبق

generateRandom

لعرض رقم (صحيح) عشوائي ضمن النطاق المحدّد.

البنية

generateRandom(min, max)

المعلّمات

المَعلمة النوع الوصف
min الرقم الحد الأدنى لقيمة محتملة للعدد الصحيح الذي تم عرضه.
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 string اسم ملف تعريف الارتباط
decode boolean يتحكّم هذا الخيار في ما إذا كان سيتم فك ترميز قيم ملفات تعريف الارتباط باستخدام دالة decodeURIComponent() في JavaScript. وتكون القيم التلقائية true.

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

get_cookies

getQueryParameters

عرض أول معلمات أو جميعها لعنوان URL الحالي queryKey. تعرِض هذه الدالة القيمة الأولى من queryKey أو مصفوفة من القيم من queryKey.

البنية

getQueryParameters(queryKey[, retrieveAll])

المعلّمات

المَعلمة النوع الوصف
queryKey string مفتاح القراءة من مَعلمات طلب البحث
retrieveAll boolean ما إذا كان سيتم استرداد جميع القيم.

على سبيل المثال، إذا كان عنوان 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 string مفتاح القراءة من مَعلمات طلب البحث
retrieveAll boolean ما إذا كان سيتم استرداد جميع القيم.

على سبيل المثال، إذا كان عنوان 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 string المكوّن الذي سيتم إرجاعه من عنوان 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 ‎‘undefined'‎
null "خالية"
true "منطقي"
12 'number'
'string' 'string'
{ a: 3 } 'object'
[ 1, 3 ] 'array'
(x) => x + 1 'function'

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

بلا عُري

getUrl

تعرِض هذه الوظيفة سلسلة تمثّل كل عنوان URL الحالي أو جزءًا منه، استنادًا إلى نوع المكوِّن وبعض مَعلمات الإعداد.

البنية

getUrl(component)

المعلّمات

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

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

get_url

gtagSet

تُرسِل هذه السمة أمرًا من gtag set إلى طبقة البيانات، ليتمّت معالجته في أقرب وقت ممكن بعد انتهاء معالجة الحدث الحالي وأيّ علامات فعّلها (أو بعد بلوغ مهلة معالجة العلامة). نضمن تتمة معالجة التعديل في هذه الحاوية قبل أي عناصر في قائمة الانتظار في ملف تعريف البيانات.

على سبيل المثال، إذا تمّ استدعاء الإجراء من خلال علامة يتمّ تنشيطها عند إعداد الموافقة، سيتمّ تطبيق الupdate قبل معالجة حدث الإعداد. على سبيل المثال، يمكن ضبط ads_data_redaction على true أو false أو url_passthrough على true أو false.

أمثلة:

const gtagSet = require('gtagSet');

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

البنية

gtagSet(object)

المعلّمات

المَعلمة النوع الوصف
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 string عنوان URL الذي سيتم استخدامه كقيمة لسمة src iframe
onSuccess function يتم استدعاء هذا الإجراء عند تحميل الإطار بنجاح.

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

inject_hidden_iframe

injectScript

تُضيف علامة نص برمجي إلى الصفحة لتحميل عنوان URL المحدّد بشكل غير متزامن. يتم تقديم وظائف الردّ على المكالمات كمثيلات وظائف، ويتم لفّها في وظائف JavaScript التي تستدعيها.

البنية

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

المعلّمات

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

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

inject_script

isConsentGranted

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

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

ستوفّر واجهة مستخدِم أداة "إدارة العلامات من Google" لإعدادات العلامة خيارًا لإطلاق العلامة دائمًا. إذا كانت العلامة المفعّلة دائمًا تستخدم واجهة برمجة التطبيقات هذه، تُعتبر الموافقة ممنوحة ويتم عرض true، بغض النظر عن حالة الموافقة الفعلية.

مثال:

const isConsentGranted = require('isConsentGranted');

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

البنية

isConsentGranted(consentType)

المعلّمات

المَعلمة النوع الوصف
consentType string نوع الموافقة المطلوب التحقّق من حالته

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

إذن 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 string اسم العمود الذي ستصبح قيمه مفاتيح في Map المحوَّلة.
valueColumnName string اسم العمود الذي ستصبح قيمه قيمًا في 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... التي يمكن عدّها للكائن المحدَّد بالترتيب نفسه الذي ستُعرِضه حلقة for...in.... إذا كانت قيمة الإدخال ليست عنصرًا، سيتم تحويلها إلى عنصر.

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

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

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

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

  • لا يمكن أن تكون 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 string مفتاح المستوى الأعلى لحذف العنصر

مثال

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

طلب الأذونات المسموح بها والمحدودة تعرِض هذه الدالة قيمة boolean: true إذا تم منح الإذن، false بخلاف ذلك.

البنية

queryPermission(permission, functionArgs*)

المعلّمات

المَعلمة النوع الوصف
permission string اسم الإذن
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

تستورد دالة مضمّنة حسب الاسم. تُعرِض دالة أو عنصرًا يمكن استدعاؤه من برنامجك. تعرِض القيمة undefined عندما لا يتوافق المتصفّح مع الدالة المضمّنة.

البنية

require(name)

المعلّمات

المَعلمة النوع الوصف
name string اسم الدالة المطلوب استيرادها.

مثال

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

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

بلا عُري

sendPixel

يُرسِل طلب GET إلى نقطة نهاية عنوان URL محدّدة.

البنية

sendPixel(url, onSuccess, onFailure)

المعلّمات

المَعلمة النوع الوصف
url string مكان إرسال وحدة البكسل
onSuccess function يتمّ استدعاؤه عند تحميل وحدة البكسل بنجاح. ملاحظة: حتى إذا تم إرسال الطلب بنجاح، قد تتطلّب المتصفّحات استجابة صورة صالحة من أجل تشغيل onSuccess.
onFailure function يتمّ استدعاؤه عند تعذّر تحميل وحدة البكسل. ملاحظة: حتى إذا تم إرسال الطلب بنجاح، قد يتم تشغيل onFailure إذا لم يعرض الخادم استجابة صالحة للصورة.

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

send_pixel

setCookie

لضبط ملفّ تعريف الارتباط أو حذفه باستخدام الاسم والقيمة والخيارات المحدّدة.

البنية

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

المعلّمات

المَعلمة النوع الوصف
name string اسم ملف تعريف الارتباط
value string قيمة ملفّ تعريف الارتباط
options object تُحدِّد سمات النطاق ، و"المسار"، و"انتهاء الصلاحية"، و"الحد الأقصى للعمر"، و"آمن"، و"SameSite". (اطّلِع على الخيارات أدناه).
encode boolean يتحكّم في ما إذا كان سيتم ترميز قيمة ملف تعريف الارتباط باستخدام encodeURIComponent() في لغة JavaScript. الإعداد التلقائي هو true.

الخيارات

  • النطاق: يتم ضبطه من خلال السمة options['domain']، إذا كانت متوفّرة. اضبط هذه القيمة على 'auto' لمحاولة كتابة ملف تعريف الارتباط باستخدام النطاق الأوسع نطاقًا ممكنًا، استنادًا إلى موضع المستند. وإذا لم تنجح هذه المحاولة، سيحاول استخدام نطاقات فرعية أصغر حجمًا بشكلٍ متسلسل. وفي حال تعذّر تنفيذ كل هذه الإجراءات، سيحاول البرنامج كتابة ملف تعريف الارتباط بدون نطاق. في حال عدم ضبط أي قيمة، سيحاول هذا الإجراء كتابة ملف تعريف الارتباط بدون تحديد نطاق. ملاحظة: عند كتابة ملف تعريف ارتباط بدون نطاق محدّد في document.cookie، سيضبط وكيل المستخدم نطاق ملف تعريف الارتباط تلقائيًا على مضيف موقع المستند الحالي.
  • المسار: يتم ضبطه بواسطة options['path']، في حال توفّره. عند كتابة ملف تعريف ارتباط بدون مسار محدّد إلى document.cookie، سيضبط وكيل المستخدم مسار ملف تعريف الارتباط تلقائيًا على مسار موقع المستند الحالي.
  • Max-Age: يتم ضبطها بواسطة options['max-age']، إذا كانت متوفّرة.
  • تاريخ انتهاء الصلاحية: يتم ضبطه بواسطة options['expires']، في حال توفّره. إذا كانت هذه السمة متوفّرة، يجب أن تكون سلسلة تاريخ بتنسيق التوقيت العالمي المتفق عليه. يمكن استخدام 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 object عنصر يحدّد الحالة التلقائية لأنواع الموافقة المحدّدة

عنصر consentSettings هو تعيين لسلاسل أنواع الموافقة العشوائية إلى أحد النوعَين 'granted' أو 'denied'. تتيح هذه السمة القيم التالية:

اسم المفتاح النوع الوصف
consentType string يمكن ضبط قيمة كل نوع موافقة على "granted" أو "denied". سيتم التعامل مع أي قيمة غير "granted" على أنّها "denied". لن يؤدي ضبط القيمة على "undefined" إلى التأثير في قيمتها السابقة.
region مصفوفة هي مصفوفة اختيارية من رموز المناطق تحدّد المنطقة التي تنطبق عليها إعدادات الموافقة. ويتم التعبير عن رموز المناطق باستخدام البلد و/أو التقسيمات الفرعية بتنسيق ISO 3166-2.
wait_for_update الرقم تحدِّد هذه السياسة قيمة مللي ثانية للتحكّم في مدة الانتظار قبل إرسال البيانات. تُستخدَم مع أدوات الحصول على الموافقات التي يتم تحميلها بشكل غير متزامن.

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

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

setInWindow

تضبط القيمة المحدّدة في window على المفتاح المحدّد. لن تؤدي هذه الطريقة تلقائيًا إلى ضبط القيمة في window إذا كانت هناك قيمة متوفّرة. اضبط overrideExisting على true لضبط القيمة في window بغض النظر عن وجود قيمة حالية. تعرض قيمة منطقية: true إذا تم تحديد القيمة بنجاح، وfalse بخلاف ذلك.

البنية

setInWindow(key, value, overrideExisting)

المعلّمات

المَعلمة النوع الوصف
key string المفتاح في 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 function يتمّ استدعاؤه باستخدام الملخّص الناتج، الذي يتم تشفيره بترميز base64، ما لم يحدّد options ترميزًا مختلفًا للإخراج.
onFailure function يتمّ استدعاؤه في حال حدوث خطأ أثناء احتساب الملخّص، أو إذا كان المتصفّح لا يتيح استخدام 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 string السلسلة المطلوب تشفيرها

مثال

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

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

إذن access_consent مع إذن الوصول للكتابة لجميع أنواع الموافقة في ملف تعريف consentSettings

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

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

assertApi

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

البنية

assertApi(apiName)

المعلّمات

المَعلمة النوع الوصف
apiName string اسم واجهة برمجة التطبيقات المطلوب التحقّق منها، وهي السلسلة نفسها التي تم تمريرها إلى 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 string رسالة اختيارية للطباعة في حال تعذّر تأكيد القيمة.

أداة المطابقة

أداة المطابقة الوصف
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 string نص رسالة خطأ اختياري.

مثال

fail('This test has failed.');

mock

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

البنية

mock(apiName, returnValue);

المعلّمات

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

أمثلة

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

mockObject

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

البنية

mockObject(apiName, objectMock);

المعلّمات

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

أمثلة

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

runCode

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

البنية

runCode(data)

المعلّمات

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

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

تعرِض هذه الدالة قيمة متغيّر للنماذج المتغيّرة، وتعرِض undefined لجميع أنواع النماذج الأخرى.

مثال

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