تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البدء

حزمة تطوير البرامج لمنصّة 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:2.2.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>

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

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

إليك مثال على كيفية التحقّق من الحالة من MainActivity في طريقة onCreate().

Java

package com.example.myapplication;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.ump.ConsentInformation;
import com.google.android.ump.ConsentRequestParameters;
import com.google.android.ump.FormError;
import com.google.android.ump.UserMessagingPlatform;

public class MainActivity extends AppCompatActivity {
  private ConsentInformation consentInformation;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .build();

    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        (OnConsentInfoUpdateSuccessListener) () -> {
          // TODO: Load and show the privacy message form.
        },
        (OnConsentInfoUpdateFailureListener) requestConsentError -> {
          // Consent gathering failed.
          Log.w(TAG, String.format("%s: %s",
              requestConsentError.getErrorCode(),
              requestConsentError.getMessage()));
        });
  }
}

Kotlin

package com.example.myapplication

import com.google.android.ump.ConsentInformation
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateFailureListener
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateSuccessListener
import com.google.android.ump.ConsentRequestParameters
import com.google.android.ump.UserMessagingPlatform

class MainActivity : AppCompatActivity() {
  private lateinit var consentInformation: ConsentInformation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Create a ConsentRequestParameters object.
    val params = ConsentRequestParameters
        .Builder()
        .build()

    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        ConsentInformation.OnConsentInfoUpdateSuccessListener {
          // TODO: Load and show the privacy message form.
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
  }
}

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

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

Java

public class MainActivity extends AppCompatActivity {
  private ConsentInformation consentInformation;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .build();

    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        (OnConsentInfoUpdateSuccessListener) () -> {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this,
            (OnConsentFormDismissedListener) loadAndShowError -> {
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, String.format("%s: %s",
                    loadAndShowError.getErrorCode(),
                    loadAndShowError.getMessage()));
              }

              // Consent has been gathered.
            }
          );
        },
        (OnConsentInfoUpdateFailureListener) requestConsentError -> {
          // Consent gathering failed.
          Log.w(TAG, String.format("%s: %s",
              requestConsentError.getErrorCode(),
              requestConsentError.getMessage()));
        });
  }
}

Kotlin

class MainActivity : AppCompatActivity() {
  private lateinit var consentInformation: ConsentInformation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Create a ConsentRequestParameters object.
    val params = ConsentRequestParameters
        .Builder()
        .build()

    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        ConsentInformation.OnConsentInfoUpdateSuccessListener {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this@MainActivity,
            ConsentForm.OnConsentFormDismissedListener {
              loadAndShowError ->
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
              }

              // Consent has been gathered.
            }
          )
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
  }
}

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

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

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

لتطبيق نقطة إدخال لخيارات الخصوصية، أكمِل الخطوات التالية:

تحقّق من ConsentInformation.PrivacyOptionsRequirementStatus.
إذا كانت نقطة إدخال خيارات الخصوصية ، أضف عنصر واجهة مستخدم مرئيًا وتفاعليًا إلى تطبيقك.
تشغيل نموذج خيارات الخصوصية باستخدام showPrivacyOptionsForm()

يوضح مثال الرمز التالي هذه الخطوات:

Java

private final ConsentInformation consentInformation;

// Show a privacy options button if required.
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  // ...

  consentInformation = UserMessagingPlatform.getConsentInformation(this);
  consentInformation.requestConsentInfoUpdate(
      this,
      params,
      (OnConsentInfoUpdateSuccessListener) () -> {
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
          this,
          (OnConsentFormDismissedListener) loadAndShowError -> {
            // ...

            // Consent has been gathered.

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

@Override
public boolean onCreateOptionsMenu(Menu menu) {
  getMenuInflater().inflate(R.menu.action_menu, menu);
  MenuItem moreMenu = menu.findItem(R.id.action_more);
  moreMenu.setVisible(isPrivacyOptionsRequired());
  return true;
}

@Override
public boolean onOptionsItemSelected(MenuItem item) {
  // ...

  popup.setOnMenuItemClickListener(
      popupMenuItem -> {
        if (popupMenuItem.getItemId() == R.id.privacy_settings) {
          // Present the privacy options form when a user interacts with
          // the privacy settings button.
          UserMessagingPlatform.showPrivacyOptionsForm(
              this,
              formError -> {
                if (formError != null) {
                  // Handle the error.
                }
              }
          );
          return true;
        }
        return false;
      });
  return super.onOptionsItemSelected(item);
}

Kotlin

private val consentInformation: ConsentInformation =
  UserMessagingPlatform.getConsentInformation(context)

// Show a privacy options button if required.
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED

override fun onCreate(savedInstanceState: Bundle?) {
  // ...
  consentInformation = UserMessagingPlatform.getConsentInformation(this)
  consentInformation.requestConsentInfoUpdate(
      this,
      params,
      ConsentInformation.OnConsentInfoUpdateSuccessListener {
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
          this@MainActivity,
          ConsentForm.OnConsentFormDismissedListener {
            // ...

            // Consent has been gathered.

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

override fun onCreateOptionsMenu(menu: Menu?): Boolean {
  menuInflater.inflate(R.menu.action_menu, menu)
  menu?.findItem(R.id.action_more)?.apply {
    isVisible = isPrivacyOptionsRequired
  }
  return super.onCreateOptionsMenu(menu)
}

override fun onOptionsItemSelected(item: MenuItem): Boolean {
  // ...

  popup.setOnMenuItemClickListener { popupMenuItem ->
    when (popupMenuItem.itemId) {
      R.id.privacy_settings -> {
        // Present the privacy options form when a user interacts with
        // the privacy settings button.
        UserMessagingPlatform.showPrivacyOptionsForm(this) { formError ->
          formError?.let {
            // Handle the error.
          }
        }
        true
      }
      else -> false
    }
  }
  return super.onOptionsItemSelected(item)
}

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

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

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

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

Java

public class MainActivity extends AppCompatActivity {
  private ConsentInformation consentInformation;
  // Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
  private final AtomicBoolean isMobileAdsInitializeCalled = new AtomicBoolean(false);
  
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .build();

    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        (OnConsentInfoUpdateSuccessListener) () -> {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this,
            (OnConsentFormDismissedListener) loadAndShowError -> {
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, String.format("%s: %s",
                    loadAndShowError.getErrorCode(),
                    loadAndShowError.getMessage()));
              }

              // Consent has been gathered.
              if (consentInformation.canRequestAds()) {
                initializeMobileAdsSdk();
              }
            }
          );
        },
        (OnConsentInfoUpdateFailureListener) requestConsentError -> {
          // Consent gathering failed.
          Log.w(TAG, String.format("%s: %s",
              requestConsentError.getErrorCode(),
              requestConsentError.getMessage()));
        });
    
    // Check if you can initialize the Google Mobile Ads SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if (consentInformation.canRequestAds()) {
      initializeMobileAdsSdk();
    }
  }
  
  private void initializeMobileAdsSdk() {
    if (isMobileAdsInitializeCalled.getAndSet(true)) {
      return;
    }

    new Thread(
            () -> {
              // Initialize the Google Mobile Ads SDK on a background thread.
              
              MobileAds.initialize(this, initializationStatus -> {});
              runOnUiThread(
                  () -> {
                    // TODO: Request an ad.
                    // loadInterstitialAd();
                  });
              
            })
        .start();
  }
}

Kotlin

class MainActivity : AppCompatActivity() {
  private lateinit var consentInformation: ConsentInformation
  // Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
  private var isMobileAdsInitializeCalled = AtomicBoolean(false)
  
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Create a ConsentRequestParameters object.
    val params = ConsentRequestParameters
        .Builder()
        .build()

    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        ConsentInformation.OnConsentInfoUpdateSuccessListener {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this@MainActivity,
            ConsentForm.OnConsentFormDismissedListener {
              loadAndShowError ->
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
              }

              // Consent has been gathered.
              if (consentInformation.canRequestAds()) {
                initializeMobileAdsSdk()
              }
            }
          )
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
    
    // Check if you can initialize the Google Mobile Ads SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if (consentInformation.canRequestAds()) {
      initializeMobileAdsSdk()
    }
  }
  
  private fun initializeMobileAdsSdk() {
    if (isMobileAdsInitializeCalled.getAndSet(true)) {
      return
    }

    val backgroundScope = CoroutineScope(Dispatchers.IO)
    backgroundScope.launch {
      
      MobileAds.initialize(this@MainActivity) {}
      runOnUiThread {
        // TODO: Request an ad.
        // loadInterstitialAd()
      }
      
    }
  }
}

الاختبار

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

اتصل على requestConsentInfoUpdate().
يمكنك التحقّق من مخرجات السجلّ لرسالة مشابهة للمثال التالي، وهي تعرض رقم تعريف جهازك وكيفية إضافته كجهاز اختبار:
```
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
```
انسخ رقم تعريف جهاز الاختبار إلى الحافظة.
عدِّل الرمز من أجل ConsentDebugSettings.Builder().addTestDeviceHashedId() وتخطّي النقاط قائمة بأرقام تعريف الأجهزة الاختبارية

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

توفِّر حزمة تطوير البرامج (SDK) لمنصّة UMP طريقة لاختبار سلوك تطبيقك كما لو كان الجهاز في المنطقة الاقتصادية الأوروبية أو المملكة المتحدة باستخدام the setDebugGeography() method which takes a DebugGeography on ConsentDebugSettings.Builder. لاحظ أن لا تعمل إعدادات تصحيح الأخطاء إلا على الأجهزة الاختبارية.

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()

أمثلة على GitHub

أمثلة على دمج حزمة تطوير البرامج (SDK) لمنصّة UMP: Java | Kotlin

البدء

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

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

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

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

طلب الحصول على معلومات الموافقة

Java

Kotlin

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

Java

Kotlin

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

Java

Kotlin

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

Java

Kotlin

الاختبار

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

Java

Kotlin

إعادة ضبط حالة الموافقة

Java

Kotlin

أمثلة على GitHub