البدء

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

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

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

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

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

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

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

جمع الموافقات

للحصول على الموافقة، أكمِل الخطوات التالية:

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

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

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

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

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

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

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

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

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

Java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity, onConsentGatheringCompleteListener::consentGatheringComplete),
    onConsentGatheringCompleteListener::consentGatheringComplete);
ConsentManager.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)
  },
)

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

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

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

بعد استدعاء requestConsentInfoUpdate()، تحقّق من ConsentInformation.PrivacyOptionsRequirementStatus لتحديد ما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة لتطبيقك:

Java

/** Helper function to determine if a privacy options entry point is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
ConsentManager.java

Kotlin

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

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

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

Java

// Check ConsentInformation.getPrivacyOptionsRequirementStatus() to see the button should
// be shown or hidden.
if (consentManager.isPrivacyOptionsRequired()) {
  privacyButton.setVisibility(View.VISIBLE);
}
MyActivity.java

Kotlin

// Check ConsentInformation.getPrivacyOptionsRequirementStatus() to see the button should
// be shown or hidden.
if (consentManager.isPrivacyOptionsRequired) {
  privacyButton.visibility = View.VISIBLE
}

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

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

Java

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

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

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

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

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

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

.

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

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

Java

consentManager.gatherConsent(
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.i(
            LOGTAG,
            "Consent Error: "
                + String.format(
                    "%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (consentManager.canRequestAds()) {
        initializeImaSdk();
      } else {
        Log.i(LOGTAG, "Consent not available to request ads");
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (consentManager.canRequestAds()) {
  initializeImaSdk();
}
MyActivity.java

Kotlin

consentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(LOGTAG, "${error.errorCode}: ${error.message}")
  }
  if (consentManager.canRequestAds) {
    initializeImaSdk()
  } else {
    Log.i(LOGTAG, "Consent not available to request ads")
  }
  // ...
}
// This sample attempts to load ads using consent obtained in the previous session.
if (consentManager.canRequestAds) {
  initializeImaSdk()
}

يُعدّ الرمز البرمجي التالي أداة تطوير برامج (SDK) لميزة DAI في إعلانات الوسائط التفاعلية بعد جمع موافقة المستخدم:

Java

private void initializeImaSdk() {
  if (sdkFactory != null) {
    // If the SDK is already initialized, do nothing.
    return;
  }

  sdkFactory = ImaSdkFactory.getInstance();

  adDisplayContainer =
      ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter);

  createAdsLoader();
  setUpPlayButton();
}
MyActivity.java

Kotlin

private fun initializeImaSdk() {
  sdkFactory = ImaSdkFactory.getInstance()
  adDisplayContainer = ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter)
  createAdsLoader()
  setUpPlayButton()
}

الاختبار

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

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

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

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

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

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

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

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

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

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

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

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

أمثلة على GitHub

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