إعداد حزمة تطوير البرامج (SDK) الخاصة بمنصة UMP

اختيار النظام الأساسي: Android iOS Unity Flutter Android (قديم)

حزمة تطوير البرامج لمنصة 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()

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

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

في حال حدوث خطأ أثناء عملية جمع الموافقة، تحقَّق مما إذا كان بإمكانك طلب الإعلانات. تستخدِم حزمة تطوير البرامج لمنصّة 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 {
  // ...
};

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

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

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

ConsentRequestParameters params =
    ConsentRequestParameters(consentDebugSettings: debugSettings);

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

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

ConsentInformation.instance.reset();

أمثلة على GitHub

يمكنك الاطّلاع على مثال كامل حول تكامل حزمة تطوير البرامج لمنصة UMP التي ناقشناها في هذه الصفحة ضمن أمثلة Flutter.