البدء

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

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

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

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

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

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

التثبيت باستخدام 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.

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

يمكنك العثور على رقم تعريف تطبيقك في واجهة مستخدم "مدير إعلانات Google". أضِف المعرّف إلى 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

تحذير: يمكن أن يؤدي استخدام طرق أخرى للتحقّق من حالة الموافقة، مثل ذاكرة التخزين المؤقت في تطبيقك أو سلسلة موافقة تم حفظها سابقًا، إلى خطأ في "إطار الشفافية والموافقة 3.3" في حال انتهاء صلاحية الموافقة.

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

بعد تلقّي أحدث حالة موافقة، اتصل بـ 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) لـ UMP الموافقة في الجلسة الحالية.
• بعد الاتصال بـ requestConsentInfoUpdate() مباشرةً قد يكون قد تم الحصول على الموافقة في جلسة التطبيق السابقة من خلال "حزمة تطوير البرامج (SDK) لمنصّة User Messaging Platform".

ملاحظة مهمة: يعرض canRequestAds() دائمًا القيمة false إلى أن يتم استدعاء requestConsentInfoUpdate()

.

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

منع تكرار عمل طلبات الإعلانات

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

الاختبار

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

ملاحظة: اعتبارًا من الإصدار 2.2.0، لا يلزم إضافة المحاكيات إلى قائمة أرقام تعريف الأجهزة لأنّها أجهزة اختبار تلقائيًا.

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

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

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

تحذير: يُقصد استخدام هذه الطريقة لأغراض الاختبار فقط. يجب عدم استدعاء reset() في رمز الإصدار العلني.

أمثلة على GitHub

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