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

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

تعمل واجهات برمجة التطبيقات هذه مع 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 string نوع الموافقة الذي يتم تغييره.
granted boolean قيمة منطقية تكون صحيحة إذا كان يتم تغيير نوع الموافقة المحدّد إلى "ممنوحة".

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

إذن access_consent مع إذن بالقراءة لنوع الموافقة

addEventCallback

تتيح لك واجهة برمجة التطبيقات addEventCallback تسجيل دالة ردّ اتصال سيتمّ استدعاؤها في نهاية حدث معيّن. سيتمّ استدعاء الدالة المُعاد الاتصال بها عند تنفيذ جميع العلامات للحدث، أو عند بلوغ مهلة حدث على الصفحة. يتم تمرير قيمتَين إلى الدالة المُعاد الاتصال بها، وهما معرّف الحاوية التي تستدعي الدالة وكائن يحتوي على معلومات عن الحدث.

البنية

addEventCallback(callback)

المعلّمات

المَعلمة النوع الوصف
callback function الدالة التي سيتمّ استدعاؤها في نهاية الحدث.

يحتوي عنصر 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 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 number إصدار طبقة البيانات الاختياري والقيمة الافتراضية هي 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). بعد إنشاء الدالة، تنشئ واجهة برمجة التطبيقات هذه arrayKey صفيفًا في window (إذا لم يكن متوفّرًا) باستخدام الوسيطة arrayKey .

عند استدعاء الدالة التي تم إنشاؤها ضمن fnKey، تدفع وسيطات العنصر إلى الصفيف الذي تم إنشاؤه ضمن arrayKey. القيمة المعروضة لواجهة برمجة التطبيقات هي الدالة التي تم إنشاؤها ضمن fnKey.

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

مثال:

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

البنية

createArgumentsQueue(fnKey, arrayKey)

المعلّمات

المَعلمة النوع الوصف
fnKey string المسار في 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 string عنوان 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 string مكوّن من معرّف الموارد المنتظم (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 number الحد الأدنى للقيمة المحتمَلة للعدد الصحيح المعروض.
max number الحد الأقصى للقيمة المحتمَلة للعدد الصحيح المعروض.

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

بلا عُري

getContainerVersion

تعرِض هذه الدالة عنصرًا يحتوي على بيانات عن الحاوية الحالية. يحتوي العنصر الذي تم إرجاعه على الحقول التالية:

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

مثال

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

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

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

البنية

getContainerVersion();

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

read_container_data

getCookieValues

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

البنية

getCookieValues(name[, decode])

المعلّمات

المَعلمة النوع الوصف
name string اسم ملف تعريف الارتباط
decode boolean يتحكّم هذا الخيار في ما إذا كان سيتم فك ترميز قيم ملفات تعريف الارتباط باستخدام دالة decodeURIComponent() في JavaScript. الإعداد التلقائي هو true.

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

get_cookies

getQueryParameters

تعرِض هذه الدالة المَعلمة الأولى أو جميع المَعلمات لمَعلمة queryKey في عنوان URL الحالي. تعرِض هذه الدالة القيمة الأولى من 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 'null'
true ‎'boolean'‎
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 string عنوان 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 تُستخدَم لتحديد سمات النطاق ، والمسار ، وExpires ، وMax-Age ، وSecure ، و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 number تحدِّد قيمة بالمللي ثانية للتحكّم في مدة الانتظار قبل إرسال البيانات. تُستخدَم مع أدوات الحصول على الموافقات التي يتم تحميلها بشكل غير متزامن.

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

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

setInWindow

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

البنية

setInWindow(key, value, overrideExisting)

المعلّمات

المَعلمة النوع الوصف
key string المفتاح في window لوضع القيمة فيه
value * القيمة المطلوب ضبطها في window.
overrideExisting boolean يجب ضبط العلامة التي تشير إلى هذه القيمة في window، بغض النظر عمّا إذا كانت هناك قيمة أم لا.

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

access_globals

sha256

تُحسِب هذه الدالة تجزئة SHA-256 للإدخال وتستدعي دالة استدعاء مع تجزئة بترميز base64، ما لم يحدِّد عنصر options ترميزًا مختلفًا للإدخال.

مثال:

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

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

البنية

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

المعلّمات

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

عنصر 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 إلغاء سلوك واجهات برمجة التطبيقات في وضع الحماية. إنّ واجهة برمجة التطبيقات mock API آمنة للاستخدام في رمز النموذج، ولكنّها لا تعمل إلا في وضع الاختبار. تتم إعادة ضبط النماذج الاختبارية قبل إجراء كل اختبار.

البنية

mock(apiName, returnValue);

المعلّمات

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

أمثلة

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 object عنصر البيانات الذي سيتم استخدامه في الاختبار.

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

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

مثال

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