Bắt đầu

SDK Nền tảng thông báo cho người dùng (UMP) của Google là một công cụ về quyền riêng tư và thông báo để giúp bạn quản lý các lựa chọn về quyền riêng tư. Để biết thêm thông tin, hãy xem bài viết Giới thiệu về Quyền riêng tư và thông báo.

Điều kiện tiên quyết

• Android API cấp 21 trở lên

Tạo loại thông báo

Tạo thông báo cho người dùng bằng một trong các Loại thông báo cho người dùng hiện có trong thẻ Quyền riêng tư và thông báo của tài khoản AdMob. SDK UMP cố gắng hiển thị thông báo về quyền riêng tư được tạo từ Mã ứng dụng AdMob được đặt trong dự án của bạn.

Để biết thêm thông tin, hãy xem bài viết Giới thiệu về quyền riêng tư và thông báo.

Cài đặt bằng Gradle

Thêm phần phụ thuộc cho SDK Nền tảng thông báo cho người dùng của Google vào tệp Gradle ở cấp ứng dụng trong mô-đun của bạn, thường là app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

Sau khi thực hiện những thay đổi đối với build.gradle của ứng dụng, hãy nhớ đồng bộ hoá dự án của bạn với các tệp Gradle.

Thêm mã ứng dụng

Bạn có thể tìm thấy mã ứng dụng trong Giao diện người dùng AdMob. Thêm mã nhận dạng vào AndroidManifest.xml của bạn bằng đoạn mã sau:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

Thu thập sự đồng ý

Để thu thập sự đồng ý, hãy hoàn tất các bước sau:

1. Yêu cầu cung cấp thông tin về sự đồng ý gần đây nhất của người dùng.
2. Tải và trình bày biểu mẫu lấy sự đồng ý (nếu cần).

Yêu cầu cung cấp thông tin về sự đồng ý

Bạn nên yêu cầu cập nhật thông tin về trạng thái đồng ý của người dùng mỗi lần chạy ứng dụng bằng cách sử dụng requestConsentInfoUpdate(). Yêu cầu này sẽ kiểm tra những mục sau:

• Liệu có cần sự đồng ý hay không. Ví dụ: yêu cầu phải có sự đồng ý lần đầu hoặc quyết định đồng ý trước đó đã hết hạn.
• Liệu có bắt buộc phải có điểm truy cập các lựa chọn về quyền riêng tư hay không. Một số thông báo về quyền riêng tư yêu cầu các ứng dụng cho phép người dùng sửa đổi các tuỳ chọn về quyền riêng tư của họ bất cứ lúc nào.

Tải và hiển thị biểu mẫu thông báo về quyền riêng tư (nếu cần)

Sau khi bạn nhận được trạng thái đồng ý mới nhất, hãy gọi loadAndShowConsentFormIfRequired() để tải mọi biểu mẫu cần thiết để thu thập sự đồng ý của người dùng. Sau khi tải, các biểu mẫu sẽ xuất hiện ngay lập tức.

Mã sau đây minh hoạ cách yêu cầu thông tin mới nhất về sự đồng ý của người dùng. Nếu cần, mã sẽ tải và hiển thị một biểu mẫu thông báo về quyền riêng tư:

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

Tuỳ chọn quyền riêng tư

Một số biểu mẫu thông báo về quyền riêng tư được trình bày từ điểm truy cập lựa chọn về quyền riêng tư do nhà xuất bản hiển thị, cho phép người dùng quản lý các lựa chọn về quyền riêng tư của họ bất cứ lúc nào. Để tìm hiểu thêm về thông báo mà người dùng của bạn nhìn thấy tại điểm truy cập vào các tuỳ chọn về quyền riêng tư, hãy xem phần Các loại thông báo hiện có cho người dùng.

Kiểm tra xem có bắt buộc phải có điểm truy cập cho các lựa chọn về quyền riêng tư hay không

Sau khi bạn gọi requestConsentInfoUpdate(), hãy kiểm tra getPrivacyOptionsRequirementStatus() để xác định xem ứng dụng của bạn có cần điểm truy cập các lựa chọn về quyền riêng tư hay không:

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

Thêm một phần tử hiển thị vào ứng dụng

Nếu cần có điểm truy cập quyền riêng tư, hãy thêm một thành phần giao diện người dùng hiển thị và có thể tương tác vào ứng dụng của bạn để hiển thị biểu mẫu lựa chọn về quyền riêng tư. Nếu không bắt buộc phải có điểm truy cập quyền riêng tư, hãy định cấu hình phần tử giao diện người dùng để không hiển thị và không tương tác được.

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

Trình bày biểu mẫu về các lựa chọn về quyền riêng tư

Khi người dùng tương tác với phần tử của bạn, hãy hiển thị biểu mẫu lựa chọn về quyền riêng tư:

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

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Yêu cầu quảng cáo

Trước khi yêu cầu quảng cáo trong ứng dụng, hãy kiểm tra xem bạn đã nhận được sự đồng ý của người dùng hay chưa bằng cách sử dụng canRequestAds(). Có hai nơi để kiểm tra trong khi thu thập sự đồng ý:

• Sau khi thu thập được sự đồng ý trong phiên hiện tại.
• Ngay sau khi bạn gọi requestConsentInfoUpdate(). Có thể bạn đã nhận được sự đồng ý trong buổi chia sẻ trước. Tốt nhất là bạn không nên đợi lệnh gọi lại hoàn tất để có thể bắt đầu tải quảng cáo ngay khi có thể sau khi ứng dụng khởi chạy.

Nếu xảy ra lỗi trong quá trình thu thập sự đồng ý, bạn vẫn nên kiểm tra xem mình có thể yêu cầu quảng cáo hay không. SDK UMP sử dụng trạng thái đồng ý từ phiên trước.

Mã sau đây kiểm tra xem bạn có thể yêu cầu quảng cáo trong quá trình thu thập sự đồng ý hay không:

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

Đoạn mã sau đây thiết lập SDK quảng cáo trên thiết bị di động của Google sau khi thu thập được sự đồng ý của người dùng:

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

Thử nghiệm

Nếu bạn muốn thử nghiệm tính năng tích hợp trong ứng dụng khi đang phát triển, hãy làm theo các bước sau để đăng ký thiết bị thử nghiệm theo phương thức lập trình. Hãy nhớ xoá mã dùng để đặt các mã thiết bị thử nghiệm này trước khi bạn phát hành ứng dụng.

1. Gọi cho requestConsentInfoUpdate().

2. Kiểm tra đầu ra nhật ký để tìm một thông báo tương tự như sau. Ví dụ này cho biết mã thiết bị của bạn và cách thêm thông báo đó làm thiết bị kiểm thử:

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

3. Sao chép mã thiết bị thử nghiệm vào bảng nhớ tạm.

4. Sửa đổi mã của bạn để gọi ConsentDebugSettings.Builder().TestDeviceHashedIds và truyền vào danh sách mã thiết bị thử nghiệm.

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

Buộc hiển thị một khu vực địa lý

SDK UMP cung cấp một cách để kiểm thử hành vi của ứng dụng như thể thiết bị được đặt ở nhiều khu vực (chẳng hạn như Khu vực kinh tế Châu Âu (EEA) hoặc Vương quốc Anh) bằng cách sử dụng setDebugGeography(). Xin lưu ý rằng chế độ cài đặt gỡ lỗi chỉ hoạt động trên thiết bị thử nghiệm.

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

Đặt lại trạng thái đồng ý

Khi thử nghiệm ứng dụng bằng SDK UMP, bạn nên đặt lại trạng thái của SDK để có thể mô phỏng trải nghiệm cài đặt lần đầu của người dùng. SDK cung cấp phương thức reset() để làm việc này.

consentInformation.reset();

consentInformation.reset()

Ví dụ trên GitHub

Hãy xem ví dụ đầy đủ về việc tích hợp SDK UMP được đề cập trên trang này trong Ví dụ về biểu ngữ trong Java và Ví dụ về biểu ngữ trong Kotlin.