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

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

توضّح هذه الصفحة أنواع الموافقة في Google Tag Manager، وتعرّفك على كيفية دمجها مع حلّ إدارة الموافقات الذي تستخدمه.

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

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

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

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

• استخدِم واجهات برمجة التطبيقات الخاصة بميزة "وضع الموافقة" في "إدارة العلامات من Google"، وهما 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 لضبط المَعلمات الاختيارية التالية:

• url_passthrough
• ads_data_redaction
• developer_id

لا تتوفّر واجهات برمجة التطبيقات هذه إلا في بيئة وضع الحماية لنموذج "إدارة العلامات من Google".

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

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

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

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

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

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

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

gtagSet('url_passthrough', true);

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

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

لإخفاء بيانات الأداء مع إعلاناتك بشكل أكبر عند رفض ad_storage، اضبط قيمة ads_data_redaction على "صحيح".

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

gtagSet('ads_data_redaction', true);

معرّف المطوّر

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

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

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

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

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

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

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

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