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

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

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

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

بلا عُري

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

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

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

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

ستوفّر واجهة مستخدم "إدارة العلامات من 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() في &quot;المكتبة العادية&quot;. تعرض هذه الطريقة مصفوفة بأسماء السمات القابلة للتعداد الخاصة بكائن معيّن، وذلك بالترتيب نفسه الذي تعرضه حلقة for...in.... إذا كانت قيمة الإدخال ليست عنصرًا، سيتم تحويلها إلى عنصر.

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

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

توفّر الطريقة freeze() سلوك Object.freeze() في &quot;المكتبة العادية&quot;. لا يمكن تغيير الكائن المجمَّد، ويمنع تجميد الكائن إضافة خصائص جديدة إليه وإزالة الخصائص الحالية وتغيير قيم الخصائص الحالية. تعرض الدالة 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 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

الاستعلام عن الأذونات المسموح بها والمحدودة تعرض هذه الدالة قيمة منطقية: 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(...);
}

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

بلا عُري

readAnalyticsStorage

يستردّ البيانات المخزّنة للإحصاءات ويعرض عنصرًا يتضمّن client_id وsessions.

  • client_id: سلسلة تمثّل رقم تعريف العميل المستخدَم في الإحصاءات.
  • sessions: مصفوفة من العناصر التي تحتوي على معلومات حول الجلسات الحالية. يتضمّن كل عنصر ما يلي:
    • measurement_id: سلسلة تمثّل رقم تعريف القياس الخاص بوجهة &quot;إحصاءات Google&quot;.
    • ‫session_id: سلسلة تمثّل الطابع الزمني الذي يحدّد الجلسة الحالية.
    • ‫session_number: رقم يمثّل عدد الجلسات التي بدأها المستخدم حتى الجلسة الحالية.

البنية

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

المعلّمات

المَعلمة النوع الوصف
cookieOptions object اختياري خيارات لقراءة ملفات تعريف الارتباط التي تتضمّن cookie_prefix أو cookie_domain أو cookie_path معيّنًا

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

read_analytics_storage

مثال

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

لعرض قيمة document.characterSet.

البنية

readCharacterSet()

المعلّمات

بلا عُري

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

read_character_set

readTitle

لعرض قيمة document.title.

البنية

readTitle()

المعلّمات

بلا عُري

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

read_title

require

تستورد هذه الدالة دالة مضمّنة حسب الاسم. تعرض هذه السمة دالة أو كائنًا يمكن استدعاؤه من برنامجك. تعرض الدالة القيمة غير محدّدة عندما لا يتيح المتصفّح استخدام الدالة المضمّنة.

البنية

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

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

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

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

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

قيمة العائد

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

مثال

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