إنشاء نموذج لوضع الموافقة

هذه الوثيقة مخصّصة للمطوّرين الذين يديرون حلاً لإدارة الموافقة على المواقع الإلكترونية التي تستخدِم أداة "إدارة العلامات من Google".

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

حالة الموافقة وأنواع الموافقة

تعدِّل علامات Google وعلامات الجهات الخارجية سلوكها المتعلّق بتخزين البيانات استنادًا إلى حالة الموافقة التي تكون إما granted أو denied. يمكن أن تتضمّن هذه العلامات عمليات تحقّق مدمجة من الموافقة لأيّ من أنواع الموافقة التالية:

إنشاء نموذج موافقة جديد

يتتبّع "وضع الموافقة" خيارات الزوّار بشأن الموافقة، وتضمن عمليات التحقّق من الموافقة في العلامات تعديل سلوك العلامة وفقًا لذلك. عند إنشاء نموذج موافقة جديد، اتّبِع أفضل الممارسات:

• استخدِم واجهات برمجة التطبيقات لوضع الموافقة في Tag Manager setDefaultConsentState و updateConsentState بدلاً من gtag consent.

• اضبط حالات الموافقة التلقائية فورًا عند التفعيل باستخدام مشغِّل إعداد الموافقة - جميع الصفحات.

• على منصّة إدارة الموافقة أن تطلب من الزائر في أقرب وقت ممكن منح الموافقة أو رفضها لجميع أنواع الموافقة السارية.

• عندما يشير الزائر إلى خياره بشأن الموافقة، على منصّة إدارة الموافقة تمرير حالة الموافقة المعدَّلة.

1- إنشاء نموذج جديد

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

لإنشاء نموذج موافقة:

1. سجِّل الدخول إلى حسابك على Google Tag Manager.
2. في لوحة التنقّل اليمنى، انقر على النماذج.
3. في لوحة نماذج العلامات ، انقر على جديدة.

لضبط حالات الموافقة التلقائية:

1. انقر على علامة التبويب الحقول ، ثمّ على إضافة حقل > جدول المَعلمات.
2. غيِّر الاسم إلى defaultSettings.
3. وسِّع الحقل.
4. عدِّل الاسم المعروض إلى Default settings.
5. انقر على إضافة عمود، ثمّ اختَر إدخال نص، وغيِّر الاسم إلى region و ضَع علامة في مربّع يجب أن تكون قيم العمود فريدة.
6. وسِّع العمود، وغيِّر الاسم المعروض إلى Region (leave blank to have consent apply to all regions). العبارة بين قوسَين هي مستندات لمستخدِمي النموذج. مزيد من المعلومات حول ضبط القيم التلقائية للموافقة لمناطق مختلفة.
7. انقر على إضافة عمود، ثمّ اختَر إدخال نص، وغيِّر الاسم إلى granted.
8. وسِّع العمود وغيِّر الاسم المعروض إلى Granted Consent Types (comma separated).
9. انقر على إضافة عمود، ثمّ اختَر إدخال نص، وغيِّر الاسم إلى denied.
10. وسِّع العمود وغيِّر الاسم المعروض إلى Denied Consent Types (comma separated)

اختياري: لإضافة إمكانية إخفاء بيانات الإعلانات:

1. انقر على إضافة حقل، ثمّ اختَر مربّع اختيار، وغيِّر اسم الحقل إلى ads_data_redaction.
2. عدِّل الاسم المعروض إلى Redact Ads Data

مزيد من المعلومات حول سلوك ملفات تعريف الارتباط عند إخفاء بيانات الأداء مع إعلانات

اختياري: لإضافة إمكانية تمرير مَعلمات عناوين URL:

1. انقر على إضافة حقل، ثمّ اختَر مربّع اختيار، وغيِّر اسم الحقل إلى url_passthrough.
2. عدِّل الاسم المعروض إلى Pass through URL parameters

مزيد من المعلومات حول تمرير مَعلمات عناوين URL

لإضافة رمز التنفيذ:

1. افتح علامة التبويب الرمز في محرِّر النماذج.
2. في عينة التعليمات البرمجية أدناه، عدِّل الحقول النائبة.
3. انسخ الرمز واستبدِله برمز النص النموذجي في محرِّر النماذج.
4. انقر على حفظ النموذج.

// The first two lines are optional, use if you want to enable logging
const log = require('logToConsole');
log('data =', data);
const setDefaultConsentState = require('setDefaultConsentState');
const updateConsentState = require('updateConsentState');
const getCookieValues = require('getCookieValues');
const callInWindow = require('callInWindow');
const gtagSet = require('gtagSet');
const JSON = require('JSON');
const COOKIE_NAME = 'Your_cookie_name';
/*
 *   Splits the input string using comma as a delimiter, returning an array of
 *   strings
 */
const splitInput = (input) => {
  if (!input) return [];
  return input.split(',')
      .map(entry => entry.trim())
      .filter(entry => entry.length !== 0);
};
/*
 *   Processes a row of input from the default settings table, returning an object
 *   which can be passed as an argument to setDefaultConsentState
 */
const parseCommandData = (settings) => {
  const regions = splitInput(settings['region']);
  const granted = splitInput(settings['granted']);
  const denied = splitInput(settings['denied']);
  const commandData = {};
  if (regions.length > 0) {
    commandData.region = regions;
  }
  granted.forEach(entry => {
    commandData[entry] = 'granted';
  });
  denied.forEach(entry => {
    commandData[entry] = 'denied';
  });
  return commandData;
};
/*
 *   Called when consent changes. Assumes that consent object contains keys which
 *   directly correspond to Google consent types.
 */
const onUserConsent = (consent) => {
  const consentModeStates = {
    ad_storage: consent['adConsentGranted'] ? 'granted' : 'denied',
    ad_user_data: consent['adUserDataConsentGranted'] ? 'granted' : 'denied',
    ad_personalization: consent['adPersonalizationConsentGranted'] ? 'granted' : 'denied',
    analytics_storage: consent['analyticsConsentGranted'] ? 'granted' : 'denied',
    functionality_storage: consent['functionalityConsentGranted'] ? 'granted' : 'denied',
    personalization_storage: consent['personalizationConsentGranted'] ? 'granted' : 'denied',
    security_storage: consent['securityConsentGranted'] ? 'granted' : 'denied',
  };
  updateConsentState(consentModeStates);
};
/*
 *   Executes the default command, sets the developer ID, and sets up the consent
 *   update callback
 */
const main = (data) => {
  /*
   * Optional settings using gtagSet
   */
  gtagSet('ads_data_redaction', data.ads_data_redaction);
  gtagSet('url_passthrough', data.url_passthrough);
  gtagSet('developer_id.your_developer_id', true);
  // Set default consent state(s). Add optional chaining to safely handle cases
  // where defaultSettings might be null or undefined.
  data.defaultSettings?.forEach(settings => {
    const defaultData = parseCommandData(settings);
    // wait_for_update (ms) allows for time to receive visitor choices from the CMP
    defaultData.wait_for_update = 500;
    setDefaultConsentState(defaultData);
  });

  // Check if cookie is set and has values that correspond to Google consent
  // types. If it does, run onUserConsent().
  const cookieValues = getCookieValues(COOKIE_NAME);
  if (cookieValues && cookieValues.length > 0) {
    try {
      const settings = JSON.parse(cookieValues[0]);
      if (settings) {
        onUserConsent(settings);
      }
    } catch (e) {
      // Log an error if the cookie value is not valid JSON.
    }
  }
  /**
   *   Add event listener to trigger update when consent changes
   *
   *   References an external method on the window object which accepts a
   *   function as an argument. If you do not have such a method, you will need
   *   to create one before continuing. This method should add the function
   *   that is passed as an argument as a callback for an event emitted when
   *   the user updates their consent. The callback should be called with an
   *   object containing fields that correspond to the five built-in Google
   *   consent types.
   */
  callInWindow('addConsentListenerExample', onUserConsent);
};
main(data);
data.gtmOnSuccess();

بعد ذلك، اضبط الأذونات للوصول إلى حالة الموافقة وملفات تعريف الارتباط.

لإضافة أذونات لإدارة حالات الموافقة:

1. انقر على علامة التبويب الأذونات ، ثمّ على الوصول إلى حالة الموافقة.
2. انقر على إضافة نوع الموافقة.
3. انقر على المربّع واختَر ad_storage من القائمة المنسدلة.
4. ضَع علامة في مربّع الكتابة.
5. انقر على إضافة.
6. كرِّر الخطوات من 2 إلى 5 لكلٍّ من ad_user_data وad_personalization وanalytics_storage. إذا كنت بحاجة إلى أنواع موافقة إضافية، أضِفها بالطريقة نفسها.
7. انقر على حفظ.

لإضافة أذونات للوصول إلى ملفات تعريف الارتباط:

1. انقر على علامة التبويب الأذونات ، ثمّ على قراءة قيم ملفات تعريف الارتباط.
2. ضمن محدّد، أدخِل أسماء كلّ ملفات تعريف الارتباط التي يحتاج الرمز إلى قراءتها لتحديد خيارات المستخدِم بشأن الموافقة، مع إدخال اسم واحد في كل سطر.
3. انقر على حفظ.

2. إنشاء اختبارات الوحدة

راجِع الاختبارات للحصول على معلومات حول إنشاء اختبارات للنموذج.

3. دمج النموذج مع حلّ الموافقة

يعرض الرمز التالي مثالاً واحدًا على كيفية دمج هذا النموذج مع رمز حلّ إدارة الموافقة من خلال إضافة مستمع:

// Array of callbacks to be executed when consent changes
const consentListeners = [];

/**
 *   Called from GTM template to set callback to be executed when user consent is provided.
 *   @param {function} Callback to execute on user consent
 */
window.addConsentListenerExample = (callback) => {
  consentListeners.push(callback);
};

/**
 *   Called when user grants/denies consent.
 *   @param {Object} Object containing user consent settings.
 */
const onConsentChange = (consent) => {
  consentListeners.forEach((callback) => {
    callback(consent);
  });
};

تعديل حالة الموافقة

بعد أن يشير أحد زوّار الموقع الإلكتروني إلى خياراته بشأن الموافقة، عادةً من خلال التفاعل مع بانر الموافقة، يجب أن يعدِّل رمز النموذج حالات الموافقة وفقًا لذلك باستخدام واجهة برمجة التطبيقات updateConsentState.

يعرض المثال التالي طلب updateConsentState لزائر أشار إلى موافقته على جميع أنواع التخزين. مرة أخرى، يستخدم هذا المثال قيمًا مبرمَجة لـ granted، ولكن من الناحية العملية، يجب تحديد هذه القيم في وقت التشغيل باستخدام موافقة الزائر التي تجمعها منصّة إدارة الموافقة.

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'ad_user_data': 'granted',
  'ad_personalization': 'granted',
  'analytics_storage': 'granted',
  'functionality_storage': 'granted',
  'personalization_storage': 'granted',
  'security_storage': 'granted'
});

لمحة عن السلوك الخاص بالمنطقة

لضبط حالات الموافقة التلقائية التي تنطبق على الزوّار من مناطق معيّنة، حدِّد منطقة (وفقًا للمعيار ISO 3166-2) في الـ نموذج. يتيح استخدام قيم المناطق لمستخدِمي النماذج الامتثال للوائح التنظيمية الإقليمية بدون فقدان معلومات الزوّار من خارج هذه المناطق. عندما لا يتم تحديد منطقة في أمر setDefaultConsentState، تنطبق القيمة على جميع المناطق الأخرى.

على سبيل المثال، يضبط ما يلي الحالة التلقائية لـ analytics_storage على denied للزوّار من إسبانيا وألاسكا، ويضبط analytics_storage على granted لجميع الزوّار الآخرين:

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'analytics_storage': 'denied',
  'region': ['ES', 'US-AK']
});
setDefaultConsentState({
  'analytics_storage': 'granted'
});

الأولوية للحالة الأكثر تحديدًا

إذا ظهر أمران للموافقة التلقائية على الصفحة نفسها مع قيم لمنطقة ومنطقة فرعية، سيسري الأمر الذي يتضمّن منطقة أكثر تحديدًا. على سبيل المثال، إذا تم ضبط ad_storage على 'granted' للمنطقة US و ad_storage على 'denied' للمنطقة US-CA، سيسري الإعداد الأكثر تحديدًا US-CA على الزائر من كاليفورنيا.

البيانات الوصفية الإضافية

يمكنك استخدام gtagSet API لضبط المَعلمات الاختيارية التالية:

• url_passthrough
• ads_data_redaction
• developer_id

لا تتوفّر واجهات برمجة التطبيقات هذه إلا في بيئة وضع الحماية لنموذج Google Tag Manager (GTM).

تمرير معلومات النقرات على الإعلانات ورقم تعريف العميل ورقم تعريف الجلسة في عناوين URL

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

ومع ذلك، إذا تم ضبط ad_storage على denied، لن تحفظ علامات Google هذه المعلومات محليًا. لتحسين جودة قياس عدد النقرات على الإعلانات في هذه الحالة، يمكن للمعلِنين اختياريًا تمرير معلومات النقرات على الإعلانات من خلال مَعلمات عناوين URL على مستوى الصفحات باستخدام ميزة تُعرف باسم تمرير عنوان URL.

وبالمثل، إذا تم ضبط analytics_storage على denied، يمكن استخدام ميزة تمرير عنوان URL لإرسال الإحصاءات المستندة إلى الأحداث والجلسات (بما في ذلك الإحالات الناجحة) بدون ملفات تعريف ارتباط على مستوى الصفحات.

يجب استيفاء الشروط التالية لاستخدام ميزة تمرير عنوان URL:

• تتوفّر على الصفحة علامات Google المستندة إلى التحقّق من حالة الموافقة.
• تم تفعيل خيار استخدام ميزة تمرير عنوان URL للموقع الإلكتروني.
• تم تنفيذ "وضع الموافقة" على الصفحة.
• يشير الرابط الخارجي إلى النطاق نفسه لنطاق الصفحة الحالية.
• يتضمّن عنوان URL معرّف gclid/dclid (علامات "إعلانات Google" وعلامات Floodlight فقط)

يجب أن يسمح النموذج لمستخدِم النموذج بضبط ما إذا كان يريد تفعيل هذا الإعداد أم لا. يُستخدَم رمز النموذج التالي لضبط url_passthrough على true:

gtagSet('url_passthrough', true);

إخفاء بيانات الأداء مع إعلانات

عندما يتم ضبط ad_storage على denied، لا يتم ضبط أي ملفات تعريف ارتباط جديدة لأغراض إعلانية. بالإضافة إلى ذلك، لن يتم استخدام ملفات تعريف ارتباط الطرف الثالث التي تم ضبطها سابقًا على google.com وdoubleclick.net. ستظل البيانات المُرسَلة إلى Google تتضمّن عنوان URL الكامل للصفحة، بما في ذلك أي معلومات عن النقرات على الإعلانات في مَعلمات عناوين URL.

لإخفاء بيانات الأداء مع إعلانات بشكلٍ أكبر عندما يتم ضبط ad_storage على denied، اضبط ads_data_redaction على true.

عندما تكون ads_data_redaction هي true وad_storage هي denied، سيتم إخفاء معرّفات النقرات على الإعلانات التي تُرسَل في طلبات الشبكة من خلال علامات "إعلانات Google" وعلامات Floodlight.

gtagSet('ads_data_redaction', true);

رقم تعريف المطوّر:

إذا كنت مورِّد منصّة إدارة موافقة ولديك رقم تعريف مطوّر صادر عن Google، استخدِم الطريقة التالية لضبطه في أقرب وقت ممكن في النموذج.

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

gtagSet('developer_id.<your_developer_id>', true);

توفير مستندات للمستخدِمين

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

• كيفية ضبط القيم التلقائية للموافقة في جدول الإعدادات
• كيفية ضبط القيم التلقائية للموافقة لمناطق مختلفة من خلال إضافة صفوف جدول إضافية
• تفعيل العلامة باستخدام مشغِّل إعداد الموافقة - جميع الصفحات

الخطوات التالية

إذا كنت تريد توفير النموذج لجميع مستخدِمي Tag Manager، حمِّله إلى الـ معرض نماذج المنتدى.