البدء

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

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

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

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

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

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

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

أضف التبعية لحزمة تطوير البرامج (SDK) لمنصة Google User Messaging Platform إلى ملف Gradle على مستوى التطبيق الخاص بالوحدة، والذي يكون عادةً app/build.gradle:

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

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

أضِف معرّف التطبيق.

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

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

للحصول على موافقة المستخدم، عليك إكمال الخطوات التالية:

  1. طلب أحدث معلومات موافقة المستخدِم
  2. حمِّل نموذج موافقة وقدِّمه إذا لزم الأمر.

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

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

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

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

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

Java


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity,
            formError -> {
              // Consent has been gathered.
              onConsentGatheringCompleteListener.consentGatheringComplete(formError);
            }),
    requestConsentError ->
        onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError));
GoogleMobileAdsConsentManager.java

Kotlin


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)
GoogleMobileAdsConsentManager.kt

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

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

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

بعد الاتصال بـ requestConsentInfoUpdate()، تحقَّق من getPrivacyOptionsRequirementStatus() لتحديد ما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة لتطبيقك أم لا:

Java


/** 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

إضافة عنصر مرئي إلى تطبيقك

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

Java


if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}
MyActivity.java

Kotlin


if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}
MainActivity.kt

تقديم نموذج خيارات الخصوصية

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

Java


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

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

طلب إدراج الإعلانات

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

  • بعد الحصول على الموافقة في الجلسة الحالية
  • بعد الاتصال بـ requestConsentInfoUpdate() مباشرةً من المحتمل أن تكون قد حصلت على موافقة في الجلسة السابقة. ومن بين أفضل ممارسات وقت الاستجابة، ننصحك بعدم انتظار اكتمال معاودة الاتصال حتى تتمكّن من البدء في تحميل الإعلانات في أقرب وقت ممكن بعد إطلاق تطبيقك.
.

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

يتحقّق الرمز التالي من إمكانية طلب إعلانات أثناء عملية الحصول على الموافقات:

Java


googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

Kotlin


googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

يعمل الرمز البرمجي التالي على إعداد حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" بعد جمع موافقة المستخدم:

Java


private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}

MyActivity.java

Kotlin


private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}

MainActivity.kt

الاختبار

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

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

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

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

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

  4. عليك تعديل الرمز لطلب "ConsentDebugSettings.Builder().TestDeviceHashedIds" وإدراج أرقام تعريف الأجهزة الاختبارية.

    Java

    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(). وتجدُر الإشارة إلى أنّ إعدادات تصحيح الأخطاء لا تعمل إلا على الأجهزة الاختبارية.

Java

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,
    ...
)

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

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

أمثلة على GitHub

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