เริ่มเลย

SDK สำหรับ User Messaging Platform (UMP) ของ Google เป็นเครื่องมือด้านความเป็นส่วนตัวและการรับส่งข้อความเพื่อช่วยคุณจัดการตัวเลือกความเป็นส่วนตัว ดูข้อมูลเพิ่มเติมได้ที่ เกี่ยวกับความเป็นส่วนตัวและการรับส่งข้อความ

ข้อกำหนดเบื้องต้น

• Android API ระดับ 21 ขึ้นไป

สร้างประเภทข้อความ

สร้างข้อความสําหรับผู้ใช้ด้วยประเภทข้อความสําหรับผู้ใช้ที่ใช้ได้ประเภทใดประเภทหนึ่งในส่วนความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ของบัญชี Ad Manager UMP SDK จะพยายามแสดงข้อความความเป็นส่วนตัวที่สร้างจากรหัสแอปพลิเคชัน Ad Manager ที่ตั้งค่าไว้ในโปรเจ็กต์ของคุณ

โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อเกี่ยวกับความเป็นส่วนตัวและการรับส่งข้อความ

ติดตั้งด้วย Gradle

เพิ่ม Dependency สำหรับ SDK สำหรับ User Messaging Platform ของ Google ลงในไฟล์ Gradle ระดับแอปของโมดูล โดยปกติจะเป็น app/build.gradle

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

หลังจากทําการเปลี่ยนแปลงbuild.gradleของแอปแล้ว อย่าลืมซิงค์โปรเจ็กต์กับไฟล์ Gradle

เพิ่มรหัสแอปพลิเคชัน

คุณดูรหัสแอปพลิเคชันได้ใน UI ของ Ad Manager เพิ่มรหัสลงใน 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() เพื่อโหลดแบบฟอร์มที่จําเป็นในการรวบรวมความยินยอมของผู้ใช้ หลังจากโหลดแล้ว แบบฟอร์มจะแสดงทันที

ประเด็นสําคัญ: หากไม่มีแบบฟอร์มข้อความเกี่ยวกับความเป็นส่วนตัวที่กําหนดให้ต้องรวบรวมความยินยอมของผู้ใช้ก่อนส่งคําขอโฆษณา ระบบจะเรียกใช้การเรียกกลับทันที

โค้ดต่อไปนี้แสดงวิธีขอข้อมูลความยินยอมล่าสุดของผู้ใช้ โค้ดจะโหลดและแสดงแบบฟอร์มข้อความเกี่ยวกับความเป็นส่วนตัว หากจำเป็น

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.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)
  },
)
GoogleMobileAdsConsentManager.kt

ตัวเลือกความเป็นส่วนตัว

แบบฟอร์มข้อความเกี่ยวกับความเป็นส่วนตัวบางรายการจะแสดงจากจุดแรกเข้าของตัวเลือกความเป็นส่วนตัวที่ผู้เผยแพร่โฆษณาแสดงผล ซึ่งช่วยให้ผู้ใช้จัดการตัวเลือกความเป็นส่วนตัวได้ทุกเมื่อ ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อความที่ผู้ใช้เห็นที่จุดแรกเข้าของตัวเลือกความเป็นส่วนตัวได้ที่ประเภทข้อความสำหรับผู้ใช้ที่ใช้ได้

ตรวจสอบว่าต้องใช้จุดแรกเข้าของตัวเลือกความเป็นส่วนตัวหรือไม่

หลังจากเรียกใช้ requestConsentInfoUpdate() แล้ว ให้ตรวจสอบ ConsentInformation.PivacyOptionsRequirementStatus เพื่อดูว่าแอปของคุณต้องใช้จุดแรกเข้าของตัวเลือกความเป็นส่วนตัวหรือไม่

Java

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

Kotlin

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

เพิ่มองค์ประกอบที่มองเห็นได้ลงในแอป

หากจำเป็นต้องมีจุดแรกเข้าด้านความเป็นส่วนตัว ให้เพิ่มองค์ประกอบ UI ที่มองเห็นได้และโต้ตอบได้ลงในแอปที่แสดงแบบฟอร์มตัวเลือกความเป็นส่วนตัว หากไม่จำเป็นต้องมีจุดแรกเข้าด้านความเป็นส่วนตัว ให้กําหนดค่าองค์ประกอบ UI ให้มองไม่เห็นและโต้ตอบไม่ได้

Java

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

Kotlin

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

แสดงแบบฟอร์มตัวเลือกความเป็นส่วนตัว

เมื่อผู้ใช้โต้ตอบกับองค์ประกอบของคุณ ให้แสดงแบบฟอร์มตัวเลือกความเป็นส่วนตัวดังนี้

Java

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

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

ส่งคำขอแสดงโฆษณา

ก่อนขอโฆษณาในแอป ให้ตรวจสอบว่าคุณได้รับความยินยอมจากผู้ใช้โดยใช้ canRequestAds() หรือไม่ มี 2 ที่ที่ควรตรวจสอบขณะรวบรวมความยินยอม ได้แก่

• หลังจากรวบรวมความยินยอมในเซสชันปัจจุบันแล้ว
• ทันทีที่คุณโทรหา requestConsentInfoUpdate() เป็นไปได้ว่าได้รับความยินยอมในเซสชันก่อนหน้า เราขอแนะนําว่าอย่ารอให้การเรียกกลับเสร็จสมบูรณ์เพื่อเริ่มโหลดโฆษณาโดยเร็วที่สุดหลังจากเปิดแอปตามแนวทางปฏิบัติแนะนำเกี่ยวกับเวลาในการตอบสนอง

หมายเหตุ: canRequestAds() จะแสดงผลเป็น false เสมอ จนกว่าคุณจะเรียกใช้ requestConsentInfoUpdate()

หากเกิดข้อผิดพลาดระหว่างกระบวนการรวบรวมความยินยอม คุณควรตรวจสอบว่าสามารถขอโฆษณาได้หรือไม่ UMP SDK ใช้สถานะความยินยอมจากเซสชันก่อนหน้า

โค้ดต่อไปนี้จะตรวจสอบว่าคุณขอโฆษณาได้ในระหว่างกระบวนการรวบรวมความยินยอมหรือไม่

Java

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

Kotlin

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

โค้ดต่อไปนี้จะตั้งค่า Google Mobile Ads SDK หลังจากที่รวบรวมความยินยอมของผู้ใช้แล้ว

Java

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

Kotlin

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 และส่งรายการรหัสอุปกรณ์ทดสอบ

   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 มีวิธีทดสอบลักษณะการทํางานของแอปเสมือนว่าอุปกรณ์อยู่ในภูมิภาคต่างๆ เช่น EEA หรือสหราชอาณาจักร โดยใช้ 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,
    ...
)

รีเซ็ตสถานะความยินยอม

เมื่อทดสอบแอปด้วย UMP SDK คุณอาจพบว่าการรีเซ็ตสถานะของ SDK มีประโยชน์ในการจําลองประสบการณ์การติดตั้งครั้งแรกของผู้ใช้ SDK มีเมธอด reset() ที่ใช้ดำเนินการนี้

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

ข้อควรระวัง: วิธีนี้มีไว้เพื่อวัตถุประสงค์ในการทดสอบเท่านั้น คุณไม่ควรเรียกใช้ reset() ในโค้ดเวอร์ชันที่ใช้งานจริง

ตัวอย่างใน GitHub

ดูตัวอย่างการผสานรวม UMP SDK แบบเต็มซึ่งกล่าวถึงในหน้านี้ใน Java BannerExample และ Kotlin BannerExample