شروع کنید

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>

اطلاعات رضایت کاربر را دریافت کنید

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

یک نمونه از ConsentInformation را اعلام کنید:

private final ConsentInformation consentInformation;

private lateinit val consentInformation: ConsentInformation

نمونه ConsentInformation را راه اندازی کنید:

consentInformation = UserMessagingPlatform.getConsentInformation(context);

consentInformation = UserMessagingPlatform.getConsentInformation(context)

شما باید با استفاده از requestConsentInfoUpdate() درخواست به‌روزرسانی اطلاعات رضایت کاربر را در هر راه‌اندازی برنامه بدهید. این درخواست موارد زیر را بررسی می کند:

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

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

// 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() تماس بگیرید تا فرم‌های مورد نیاز برای جمع‌آوری رضایت کاربر بارگیری شود. پس از بارگذاری، فرم ها بلافاصله ارائه می شوند.

UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
GoogleMobileAdsConsentManager.java

UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}
GoogleMobileAdsConsentManager.kt

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

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

بررسی کنید که آیا یک نقطه ورود گزینه های حریم خصوصی مورد نیاز است یا خیر

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

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

برای فهرست کامل وضعیت‌های مورد نیاز گزینه‌های حریم خصوصی، ConsentInformation.PrivacyOptionsRequirementStatus را ببینید.

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

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

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

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

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

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

consentInformation.canRequestAds();

consentInformation.canRequestAds()

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

• پس از کسب رضایت UMP SDK در جلسه جاری.
• بلافاصله پس از فراخوانی requestConsentInfoUpdate() . UMP SDK ممکن است در جلسه قبلی برنامه رضایت کسب کرده باشد.

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

از کار اضافی درخواست آگهی جلوگیری کنید

همانطور که canRequestAds() پس از جمع‌آوری رضایت و پس از فراخوانی requestConsentInfoUpdate() بررسی می‌کنید، مطمئن شوید که منطق شما از درخواست‌های اضافی تبلیغاتی جلوگیری می‌کند که ممکن است منجر به بازگشت true هر دو چک شود. به عنوان مثال، با یک متغیر بولی.

تست کردن

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

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

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

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

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>

اطلاعات رضایت کاربر را دریافت کنید

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

یک نمونه از ConsentInformation را اعلام کنید:

private final ConsentInformation consentInformation;

private lateinit val consentInformation: ConsentInformation

نمونه ConsentInformation را راه اندازی کنید:

consentInformation = UserMessagingPlatform.getConsentInformation(context);

consentInformation = UserMessagingPlatform.getConsentInformation(context)

شما باید با استفاده از requestConsentInfoUpdate() درخواست به‌روزرسانی اطلاعات رضایت کاربر را در هر راه‌اندازی برنامه بدهید. این درخواست موارد زیر را بررسی می کند:

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

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

// 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() تماس بگیرید تا فرم‌های مورد نیاز برای جمع‌آوری رضایت کاربر بارگیری شود. پس از بارگذاری، فرم ها بلافاصله ارائه می شوند.

UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
GoogleMobileAdsConsentManager.java

UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}
GoogleMobileAdsConsentManager.kt

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

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

بررسی کنید که آیا یک نقطه ورود گزینه های حریم خصوصی مورد نیاز است یا خیر

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

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

برای فهرست کامل وضعیت‌های مورد نیاز گزینه‌های حریم خصوصی، ConsentInformation.PrivacyOptionsRequirementStatus را ببینید.

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

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

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

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

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

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

consentInformation.canRequestAds();

consentInformation.canRequestAds()

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

• پس از کسب رضایت UMP SDK در جلسه جاری.
• بلافاصله پس از فراخوانی requestConsentInfoUpdate() . UMP SDK ممکن است در جلسه قبلی برنامه رضایت کسب کرده باشد.

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

از کار اضافی درخواست آگهی جلوگیری کنید

همانطور که canRequestAds() پس از جمع‌آوری رضایت و پس از فراخوانی requestConsentInfoUpdate() بررسی می‌کنید، مطمئن شوید که منطق شما از درخواست‌های اضافی تبلیغاتی جلوگیری می‌کند که ممکن است منجر به بازگشت true هر دو چک شود. به عنوان مثال، با یک متغیر بولی.

تست کردن

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

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

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

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