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

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

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

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

إذن "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 سلسلة معرّف الموارد المنتظم (URI) الذي تم ترميزه باستخدام encodeUri() أو بطرق أخرى.

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

بلا عُري

decodeUriComponent

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

مثال:

const decode = require('decodeUriComponent');

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

البنية

decodeUriComponent(encoded_uri_component)

المَعلمات

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

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

بلا عُري

encodeUri

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

مثال:

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

البنية

encodeUri(uri)

المَعلمات

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

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

بلا عُري

encodeUriComponent

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

مثال:

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

البنية

encodeUriComponent(str)

المَعلمات

المَعلمة النوع الوصف
str سلسلة يشير ذلك المصطلح إلى مكوّن لمعرّف الموارد المنتظم (URI).

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

بلا عُري

fromBase64

تتيح لك واجهة برمجة التطبيقات fromBase64 فك ترميز السلاسل من تمثيل 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 boolean تتحكّم هذه السياسة في ما إذا كان سيتم فك ترميز قيم ملفات تعريف الارتباط باستخدام decodeURIComponent() في JavaScript. وتكون الإعدادات التلقائية true.

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

get_cookies

getQueryParameters

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

البنية

getQueryParameters(queryKey[, retrieveAll])

المَعلمات

المَعلمة النوع الوصف
queryKey سلسلة المفتاح المطلوب قراءته من مَعلمات طلب البحث.
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 سلسلة المفتاح المطلوب قراءته من مَعلمات طلب البحث.
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 سلسلة المكوّن المطلوب عرضه من عنوان URL. يمكن أن تكون إحدى السمات التالية: protocol أو host أو port أو path أو query أو extension. إذا كانت قيمة السمة component هي undefined أو null أو لا تتطابق مع أحد هذه المكوّنات، سيتم عرض عنوان URL بالكامل.

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

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

getTimestamp

تمّت إزالة هذا العمود. أفضِّل getTimestampMillis.

لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة يونكس، كما يعرضه Date.now().

البنية

getTimestamp();

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

بلا عُري

getTimestampMillis

لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة يونكس، كما يعرضه Date.now().

البنية

getTimestampMillis();

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

بلا عُري

getType

تعرض سلسلة تصف نوع القيمة المحدّدة. على عكس typeof، تفرق السمة getType بين array وobject.

البنية

getType(data.someField)

الملاحظات

يسرد الجدول التالي السلاسل التي تم إرجاعها لكل قيمة إدخال.

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

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

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

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

ستوفّر واجهة مستخدم أداة "إدارة العلامات من 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

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

  • النطاق: يتم ضبطه من خلال الموقع الإلكتروني options['domain']، إذا كان متوفّرًا. اضبط هذه القيمة على 'auto' لمحاولة كتابة ملف تعريف الارتباط باستخدام أوسع نطاق ممكن استنادًا إلى موقع المستند. إذا لم ينجح ذلك، فسيحاول بشكل متتابع تضييق النطاقات الفرعية. وإذا لم تنجح كل هذه الإجراءات، سيحاول كتابة ملف تعريف الارتباط بدون نطاق. إذا لم يتم ضبط أي قيمة، سيحاول هذا كتابة ملف تعريف الارتباط بدون تحديد نطاق. ملاحظة: عندما تتم كتابة ملف تعريف ارتباط بدون نطاق محدّد إلى document.cookie، سيضبط وكيل المستخدم نطاق ملف تعريف الارتباط تلقائيًا على مضيف موقع المستند الحالي.
  • المسار: يتم ضبطه من قِبل "options['path']"، إن كان متوفرًا. عند كتابة ملف تعريف ارتباط بدون مسار محدّد على document.cookie، سيضبط وكيل المستخدم مسار ملف تعريف الارتباط تلقائيًا على مسار موقع المستند الحالي.
  • الحد الأقصى للعمر: يتم ضبطه من خلال options['max-age']، إن وُجد.
  • تاريخ انتهاء الصلاحية: يتم ضبطه من خلال "options['expires']"، إذا كان متوفّرًا. في حالة وجودها، يجب أن تكون سلسلة تاريخ بتنسيق UTC. يمكن استخدام Date.toUTCString() لتنسيق Date لهذه المعلمة.
  • آمن: يتم ضبطه من قِبل "options['secure']"، إذا كان متوفرًا.
  • SameSite: يتم ضبطه من قِبل "options['samesite']"، إذا كان متوفّرًا.

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

set_cookies

setDefaultConsentState

تؤدي هذه السياسة إلى تطبيق تعديل تلقائي للموافقة على طبقة البيانات، لتتم معالجته في أقرب وقت ممكن بعد انتهاء معالجة الحدث الحالي وأي علامات تم تشغيلها (أو انتهاء مهلة معالجة العلامات). نضمن معالجة التحديث في هذه الحاوية قبل أي عناصر في قائمة الانتظار في طبقة البيانات. مزيد من المعلومات عن الموافقة

مثال:

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

البنية

setDefaultConsentState(consentSettings)

المَعلمات

المَعلمة النوع الوصف
consentSettings كائن يشير ذلك المصطلح إلى عنصر يحدّد الحالة التلقائية لأنواع الموافقة المحدّدة.

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

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

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

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

setInWindow

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

البنية

setInWindow(key, value, overrideExisting)

المَعلمات

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

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

access_globals

sha256

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

مثال:

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

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

البنية

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

المَعلمات

المَعلمة النوع الوصف
input سلسلة السلسلة المطلوب حساب التجزئة لها.
onSuccess الوظيفة يتم استدعاؤه مع الملخص الناتج، ويتم ترميزه باستخدام base64، ما لم يحدد الكائن options ترميزًا مختلفًا للإخراج.
onFailure الوظيفة يتم استدعاؤه في حال حدوث خطأ أثناء احتساب الملخّص أو إذا لم يكن المتصفّح متوافقًا في الأصل مع sha256. ويتم استدعاء معاودة الاتصال باستخدام كائن يحتوي على اسم الخطأ والرسالة.
options كائن كائن الخيارات الاختياري لتحديد ترميز الإخراج. وفي حال تحديدها، يجب أن يحتوي الكائن على المفتاح outputEncoding مع قيمة واحدة من base64 أو hex.

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

بلا عُري

templateStorage

لعرض كائن مع طرق للوصول إلى تخزين النموذج. تسمح مساحة تخزين النماذج بمشاركة البيانات عبر عمليات تنفيذ نموذج واحد. تستمر البيانات المخزنة في تخزين النماذج طوال عمر الصفحة.

البنية

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

// Deletes all stored values for the template.
templateStorage.clear();

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

access_template_storage

مثال

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

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

تتيح لك واجهة برمجة التطبيقات toBase64 ترميز سلسلة في تمثيل base64.

البنية

toBase64(input)

المَعلمات

المَعلمة النوع الوصف
input سلسلة سلسلة مطلوب ترميزها

مثال

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

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

لا ينطبق

updateConsentState

تعمل على تحديث الموافقة إلى طبقة البيانات، لتتم معالجتها في أقرب وقت ممكن بعد انتهاء معالجة الحدث الحالي وأي علامات تم تشغيلها (أو انتهاء مهلة معالجة العلامة). نضمن معالجة التحديث في هذه الحاوية قبل أي عناصر في قائمة الانتظار في طبقة البيانات. مزيد من المعلومات عن الموافقة

مثال:

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

البنية

updateConsentState(consentSettings)

المَعلمات

المَعلمة النوع الوصف
consentSettings كائن يشير ذلك المصطلح إلى عنصر يعدِّل الحالة لأنواع الموافقة المحدّدة.

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

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

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

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

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

تعمل واجهات برمجة التطبيقات هذه مع اختبارات 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 غير دالة، فسيتم عرض هذه القيمة بدلاً من Sandbox API.

أمثلة

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

runCode

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

البنية

runCode(data)

المَعلمات

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

قيمة الإرجاع

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

مثال

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