البدء

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

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

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

  • المستوى 21 لواجهة برمجة التطبيقات Android أو مستوى أعلى

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

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

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

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

أضِف الاعتمادية لحزمة تطوير البرامج (SDK) لمنصة Google لمراسلة المستخدمين إلى ملف 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>

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

عرِّف مثيلاً من ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

إعداد مثيل ConsentInformation:

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

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

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

Java


// 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() لتحميل أي نماذج مطلوبة لجمع موافقة المستخدم. بعد التحميل، تظهر النماذج على الفور.

Java


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() لتحديد ما إذا كانت نقطة دخول لخيارات الخصوصية مطلوبة لتطبيقك. وإذا كانت نقطة الدخول مطلوبة، أضِف عنصرًا مرئيًا وقابلاً للتفاعل في واجهة المستخدم إلى تطبيقك يعرض نموذج خيارات الخصوصية. إذا لم تكن نقطة دخول الخصوصية مطلوبة، اضبط عنصر واجهة المستخدم على أن يكون غير مرئي وغير قابل للتفاعل.

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

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

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

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

Java


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

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

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

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

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

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

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

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

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

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

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

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

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

أمثلة على GitHub

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