شروع کنید

Google User Messaging Platform (UMP) SDK ابزاری برای حفظ حریم خصوصی و پیام‌رسانی است که به شما در مدیریت انتخاب‌های حریم خصوصی کمک می‌کند. برای اطلاعات بیشتر، درباره حریم خصوصی و پیام‌رسانی را ببینید.

پیش نیازها

• Android API سطح 21 یا بالاتر

یک نوع پیام ایجاد کنید

پیام‌های کاربر را با یکی از انواع پیام‌های کاربر موجود در برگه حریم خصوصی و پیام‌رسانی حساب AdMob خود ایجاد کنید. UMP SDK سعی می‌کند پیام حریم خصوصی ایجاد شده از AdMob Application ID را در پروژه شما نمایش دهد.

برای جزئیات بیشتر، درباره حریم خصوصی و پیام‌رسانی را ببینید.

با Gradle نصب کنید

وابستگی Google User Messaging Platform SDK را به فایل 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() درخواست به‌روزرسانی اطلاعات رضایت کاربر را در هر راه‌اندازی برنامه بدهید. این درخواست موارد زیر را بررسی می کند:

• آیا رضایت لازم است . به عنوان مثال، برای بار اول رضایت لازم است، یا تصمیم قبلی رضایت منقضی شده است.
• آیا یک نقطه ورود گزینه های حریم خصوصی مورد نیاز است یا خیر . برخی از پیام‌های حریم خصوصی به برنامه‌ها نیاز دارند که به کاربران اجازه دهند گزینه‌های حریم خصوصی خود را در هر زمان تغییر دهند.

هشدار: اگر رضایت منقضی شده باشد، استفاده از روش‌های دیگر برای بررسی وضعیت رضایت، مانند حافظه پنهان در برنامه یا رشته رضایت قبلی ذخیره شده، می‌تواند منجر به خطای TCF 3.3 شود.

در صورت نیاز فرم پیام حریم خصوصی را بارگیری و ارائه دهید

پس از دریافت به‌روزترین وضعیت رضایت، با loadAndShowConsentFormIfRequired() تماس بگیرید تا فرم‌های مورد نیاز برای جمع‌آوری رضایت کاربر بارگیری شود. پس از بارگذاری، فرم ها بلافاصله ارائه می شوند.

نکته کلیدی: اگر هیچ فرم پیام حفظ حریم خصوصی نیاز به جمع آوری رضایت کاربر قبل از درخواست تبلیغات نداشته باشد، پاسخ تماس بلافاصله فراخوانی می شود.

کد زیر نحوه درخواست آخرین اطلاعات رضایت کاربر را نشان می دهد. در صورت نیاز، کد بارگیری می شود و فرم پیام حریم خصوصی را ارائه می دهد:

جاوا

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

کاتلین

// 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() را بررسی کنید تا مشخص کنید آیا یک نقطه ورود گزینه های حریم خصوصی برای برنامه شما مورد نیاز است یا خیر:

جاوا

/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
GoogleMobileAdsConsentManager.java

کاتلین

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

یک عنصر قابل مشاهده به برنامه خود اضافه کنید

اگر به یک نقطه ورودی حریم خصوصی نیاز است، یک عنصر رابط کاربری قابل مشاهده و قابل تعامل به برنامه خود اضافه کنید که فرم گزینه های حریم خصوصی را ارائه می دهد. اگر نقطه ورود حریم خصوصی مورد نیاز نیست، عنصر UI خود را طوری پیکربندی کنید که قابل مشاهده و تعامل نباشد.

جاوا

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

کاتلین

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

فرم گزینه های حریم خصوصی را ارائه دهید

هنگامی که کاربر با عنصر شما تعامل دارد، فرم گزینه های حریم خصوصی را ارائه دهید:

جاوا

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

کاتلین

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

درخواست تبلیغات

قبل از درخواست تبلیغات در برنامه خود، بررسی کنید که آیا رضایت کاربر را با استفاده از canRequestAds() دریافت کرده اید یا خیر. هنگام جمع آوری رضایت دو مکان برای بررسی وجود دارد:

• پس از کسب رضایت در جلسه جاری.
• بلافاصله پس از فراخوانی requestConsentInfoUpdate() . امکان دارد در جلسه قبل رضایت گرفته شده باشد. به‌عنوان بهترین روش تأخیر، توصیه می‌کنیم منتظر تکمیل تماس نمانید تا بتوانید در اسرع وقت پس از راه‌اندازی برنامه، بارگیری تبلیغات را شروع کنید.

توجه: canRequestAds() همیشه false برمی گرداند تا زمانی که requestConsentInfoUpdate() را فراخوانی کنید.

اگر در فرآیند جمع‌آوری رضایت خطایی رخ داد، همچنان باید بررسی کنید که آیا می‌توانید آگهی درخواست کنید یا خیر. UMP SDK از وضعیت رضایت جلسه قبل استفاده می کند.

کد زیر بررسی می‌کند که آیا می‌توانید در طول فرآیند جمع‌آوری رضایت، آگهی درخواست کنید:

جاوا

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

کاتلین

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 را تنظیم می‌کند:

جاوا

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

کاتلین

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

تست کردن

اگر می‌خواهید یکپارچه‌سازی برنامه خود را در حین توسعه آزمایش کنید، این مراحل را دنبال کنید تا دستگاه آزمایشی خود را به صورت برنامه‌نویسی ثبت کنید. قبل از انتشار برنامه، حتماً کدی را که این شناسه‌های دستگاه آزمایشی را تنظیم می‌کند حذف کنید.

توجه: از نسخه 2.2.0، شبیه سازها نیازی به اضافه شدن به لیست شناسه دستگاه شما ندارند، زیرا به طور پیش فرض دستگاه های آزمایشی هستند.

1. requestConsentInfoUpdate() فراخوانی کنید.

2. خروجی گزارش را برای پیامی شبیه به مثال زیر بررسی کنید، که شناسه دستگاه شما و نحوه افزودن آن را به عنوان یک دستگاه آزمایشی نشان می دهد:

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

3. شناسه دستگاه آزمایشی خود را در کلیپ بورد خود کپی کنید.

4. کد خود را برای فراخوانی ConsentDebugSettings.Builder().TestDeviceHashedIds تغییر دهید و لیستی از شناسه های دستگاه آزمایشی خود را ارسال کنید.

   جاوا

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

   کاتلین

   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 SDK با استفاده از setDebugGeography() روشی را برای آزمایش رفتار برنامه شما ارائه می دهد که گویی دستگاه در مناطق مختلفی مانند EEA یا انگلستان قرار دارد. توجه داشته باشید که تنظیمات اشکال زدایی فقط در دستگاه های آزمایشی کار می کند.

جاوا

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

کاتلین

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 را بازنشانی کنید تا بتوانید اولین تجربه نصب کاربر را شبیه سازی کنید. SDK متد reset() را برای این کار فراهم می کند.

جاوا

consentInformation.reset();

کاتلین

consentInformation.reset()

احتیاط: این روش فقط برای اهداف آزمایشی استفاده می شود. در کد تولید نباید reset() فراخوانی کنید.

نمونه هایی در GitHub

نمونه کاملی از ادغام UMP SDK که در این صفحه در Java BannerExample و Kotlin BannerExample پوشش داده شده است را ببینید.