البدء

حزمة تطوير البرامج (SDK) لمنصة Google User Messaging Platform (UMP) هي أداة للخصوصية والمراسلة تساعدك في إدارة خيارات الخصوصية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة لمحة عن أداة "الخصوصية والمراسلة".

إنشاء نوع رسالة

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

لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة لمحة عن أداة "الخصوصية والمراسلة".

الحصول على معلومات موافقة المستخدم

عليك طلب تعديل معلومات موافقة المستخدم عند كل عملية تشغيل للتطبيق، وذلك باستخدام requestConsentInfoUpdate(). يتحقّق هذا الطلب مما يلي:

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

@override
void initState() {
  super.initState();

  // Create a ConsentRequestParameters object.
  final params = ConsentRequestParameters();

  // Request an update to consent information on every app launch.
  ConsentInformation.instance.requestConsentInfoUpdate(
    params,
    () async {
      // Called when consent information is successfully updated.
    },
    (FormError error) {
      // Called when there's an error updating consent information.
    },
  );
}

تحميل نموذج رسالة الخصوصية وعرضه

بعد تلقّي أحدث حالة موافقة، استخدِم الدالة loadAndShowConsentFormIfRequired() لتحميل أي نماذج مطلوبة لجمع موافقة المستخدم. بعد التحميل، تظهر النماذج على الفور.

@override
void initState() {
  super.initState();

  // Create a ConsentRequestParameters object.
  final params = ConsentRequestParameters();

  // Request an update to consent information on every app launch.
  ConsentInformation.instance.requestConsentInfoUpdate(
    params,
    () async {
      ConsentForm.loadAndShowConsentFormIfRequired((loadAndShowError) {
        if (loadAndShowError != null) {
          // Consent gathering failed.
        }

        // Consent has been gathered.
      });
    },
    (FormError error) {
      // Handle the error.
    },
  );
}

خيارات الخصوصية

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

التحقّق مما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة

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

/// Helper variable to determine if the privacy options entry point is required.
Future<bool> isPrivacyOptionsRequired() async {
  return await ConsentInformation.instance
      .getPrivacyOptionsRequirementStatus() ==
      PrivacyOptionsRequirementStatus.required;
}

للاطّلاع على القائمة الكاملة بحالات متطلبات خيارات الخصوصية، يُرجى الاطّلاع على PrivacyOptionsRequirementStatus.

عرض نموذج خيارات الخصوصية

عندما يتفاعل المستخدم مع العنصر، اعرض نموذج خيارات الخصوصية:

ConsentForm.showPrivacyOptionsForm((formError) {
  if (formError != null) {
    debugPrint("${formError.errorCode}: ${formError.message}");
  }
});

طلب الإعلانات مع موافقة المستخدم

قبل طلب الإعلانات، استخدِم canRequestAds() للتحقّق مما إذا كنت قد حصلت على موافقة المستخدم:

await ConsentInformation.instance.canRequestAds()

في ما يلي الأماكن التي يمكنك التحقّق منها لمعرفة ما إذا كان بإمكانك طلب عرض الإعلانات أثناء جمع الموافقة:

• بعد أن تجمع حزمة تطوير البرامج (SDK) لمنصّة إدارة الموافقة الموافقة في الجلسة الحالية
• مباشرةً بعد الاتصال بالرقم requestConsentInfoUpdate() من المحتمل أنّ حزمة تطوير البرامج لمنصة UMP قد حصلت على الموافقة في جلسة التطبيق السابقة.

في حال حدوث خطأ أثناء عملية جمع الموافقة، تحقَّق مما إذا كان بإمكانك طلب الإعلانات. تستخدِم حزمة تطوير البرامج (SDK) لمنصّة UMP حالة الموافقة من جلسة التطبيق السابقة.

منع العمل المتكرّر في طلبات الإعلانات

أثناء التحقّق من canRequestAds() بعد جمع الموافقة وبعد طلب requestConsentInfoUpdate()، تأكَّد من أنّ منطقك يمنع طلبات الإعلانات المكرّرة التي قد تؤدي إلى عرض true في كلتا الحالتين. على سبيل المثال، مع متغيّر منطقي.

الاختبار

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

1. تواصل هاتفيًا مع "requestConsentInfoUpdate()".

2. تحقَّق من ناتج السجلّ بحثًا عن رسالة مشابهة للمثال التالي، والذي يعرض معرّف جهازك وكيفية إضافته كجهاز اختبار:

   Android

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231")
   to set this as a debug device.
   

   iOS

   <UMP SDK>To enable debug mode for this device,
   set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
   

3. انسخ رقم تعريف جهاز الاختبار إلى الحافظة.

4. عدِّل الرمز البرمجي لاستدعاء ConsentDebugSettings.testIdentifiers وتمرير قائمة بأرقام تعريف أجهزتك الاختبارية.

   ConsentDebugSettings debugSettings = ConsentDebugSettings(
     testIdentifiers: ["TEST-DEVICE-HASHED-ID"],
   );
   
   ConsentRequestParameters params =
       ConsentRequestParameters(consentDebugSettings: debugSettings);
   
   ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
     // ...
   };
   

فرض موقع جغرافي

توفّر حزمة تطوير البرامج (SDK) لمنصّة UMP طريقة لاختبار سلوك تطبيقك كما لو كان الجهاز في مناطق مختلفة، مثل المنطقة الاقتصادية الأوروبية أو المملكة المتحدة، وذلك باستخدام debugGeography. يُرجى العِلم أنّ إعدادات تصحيح الأخطاء لا تعمل إلا على الأجهزة الاختبارية.

ConsentDebugSettings debugSettings = ConsentDebugSettings(
  debugGeography: DebugGeography.debugGeographyEea,
  testIdentifiers: ["TEST-DEVICE-HASHED-ID"],
);

ConsentRequestParameters params =
    ConsentRequestParameters(consentDebugSettings: debugSettings);

ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
  // ...
};

إعادة ضبط حالة الموافقة

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

ConsentInformation.instance.reset();

أمثلة على GitHub

يمكنك الاطّلاع على مثال كامل لعملية دمج حزمة تطوير البرامج (SDK) لمنصّة UMP التي تم تناولها في هذه الصفحة في أمثلة Flutter.