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

اختيار النظام الأساسي: Android (إصدار تجريبي) جديد Android iOS Unity Flutter

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

المتطلبات الأساسية

  • المستوى 21 من واجهة برمجة التطبيقات Android أو مستوى أحدث

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

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

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

التثبيت باستخدام Gradle

Gradle على مستوى التطبيق في الوحدة، والذي يكون عادةً app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:4.0.0")
}

بعد إجراء التغييرات على ملف build.gradle الخاص بتطبيقك، احرص على مزامنة مشروعك مع ملفات Gradle.

إضافة رقم تعريف التطبيق

يمكنك العثور على رقم تعريف تطبيقك في الـ AdMob UI. أضِف رقم التعريف إلى ملف AndroidManifest.xml باستخدام مقتطف الرمز البرمجي التالي:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

للحصول على معلومات موافقة المستخدم، اتّبِع الخطوات التالية:

أعلِن عن مثيل من ConsentInformation:

جافا

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

يمكنك تهيئة مثيل ConsentInformation:

جافا

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

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

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

جافا


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () -> // Called when consent information is successfully updated.
    requestConsentError -> // Called when there's an error updating consent information.
GoogleMobileAdsConsentManager.java

Kotlin


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    // Called when consent information is successfully updated.
  },
  { requestConsentError ->
    // Called when there's an error updating consent information.
  },
)
GoogleMobileAdsConsentManager.kt

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

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

جافا


UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
GoogleMobileAdsConsentManager.java

Kotlin


UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}
GoogleMobileAdsConsentManager.kt

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

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

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

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

جافا


/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}

GoogleMobileAdsConsentManager.java

Kotlin


/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED

GoogleMobileAdsConsentManager.kt

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

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

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

جافا


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
GoogleMobileAdsConsentManager.java

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

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

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

جافا

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

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

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

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

منع العمل غير الضروري لطلب عرض الإعلان

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

الاختبار

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

  1. استخدِم requestConsentInfoUpdate().

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

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

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

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

    جافا

    ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    // ...
);

    Kotlin

    val debugSettings = ConsentDebugSettings.Builder(this)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    // ...
)

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

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

جافا

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

Kotlin

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

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

جافا

consentInformation.reset();

Kotlin

consentInformation.reset()

أمثلة على GitHub

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