דף זה תורגם על ידי Cloud Translation API.

אני רוצה לנסות

Google User Messaging Platform (UMP) SDK הוא כלי פרטיות והעברת הודעות שמאפשר עזרה בניהול בחירות הפרטיות. מידע נוסף זמין במאמר הבא: מידע על 'פרטיות' העברת הודעות.

דרישות מוקדמות

Android API ברמה 21 ואילך

איך יוצרים את סוג ההודעה

ליצור הודעות למשתמשים באמצעות אחד הסוגים הזמינים של הודעות למשתמשים בקטע פרטיות העברת הודעות AdMob חשבון. UMP SDK מנסה להציג הודעה בנושא פרטיות שנוצרה מ AdMob מזהה האפליקציה שמוגדרים בפרויקט.

פרטים נוספים זמינים במאמר מידע על הכלי 'פרטיות והודעות'.

התקנה באמצעות Gradle

מוסיפים את התלות של Google User Messaging Platform SDK למודול ברמת האפליקציה, קובץ Gradle, בדרך כלל app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:2.2.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>

צריך לבקש עדכון של פרטי ההסכמה של המשתמשים בכל אפליקציה בהפעלה באמצעות requestConsentInfoUpdate(). הבקשה הזו בודקת הבאים:

אם נדרשת הסכמה. לדוגמה, נדרשת הסכמה למטרות בפעם הראשונה או פג התוקף של ההחלטה הקודמת בנושא הסכמה.
אם נדרשת נקודת כניסה לאפשרויות הפרטיות. הודעות מסוימות בנושא פרטיות לדרוש שהאפליקציות יאפשרו למשתמשים לשנות את אפשרויות הפרטיות שלהם בכל שלב.

דוגמה לאופן שבו אפשר לבדוק את הסטטוס מ-MainActivity onCreate().

Java

package com.example.myapplication;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.ump.ConsentInformation;
import com.google.android.ump.ConsentRequestParameters;
import com.google.android.ump.FormError;
import com.google.android.ump.UserMessagingPlatform;

public class MainActivity extends AppCompatActivity {
  private ConsentInformation consentInformation;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .build();

    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        (OnConsentInfoUpdateSuccessListener) () -> {
          // TODO: Load and show the privacy message form.
        },
        (OnConsentInfoUpdateFailureListener) requestConsentError -> {
          // Consent gathering failed.
          Log.w(TAG, String.format("%s: %s",
              requestConsentError.getErrorCode(),
              requestConsentError.getMessage()));
        });
  }
}

Kotlin

package com.example.myapplication

import com.google.android.ump.ConsentInformation
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateFailureListener
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateSuccessListener
import com.google.android.ump.ConsentRequestParameters
import com.google.android.ump.UserMessagingPlatform

class MainActivity : AppCompatActivity() {
  private lateinit var consentInformation: ConsentInformation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Create a ConsentRequestParameters object.
    val params = ConsentRequestParameters
        .Builder()
        .build()

    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        ConsentInformation.OnConsentInfoUpdateSuccessListener {
          // TODO: Load and show the privacy message form.
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
  }
}

טעינה והצגת טופס הודעה בנושא פרטיות במקרה הצורך

אחרי קבלת סטטוס ההסכמה העדכני ביותר, צריך להתקשר loadAndShowConsentFormIfRequired() כדי לטעון את כל הטפסים הנדרשים לקבל הסכמה מהמשתמשים. הטפסים מוצגים מיד לאחר הטעינה.

Java

public class MainActivity extends AppCompatActivity {
  private ConsentInformation consentInformation;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .build();

    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        (OnConsentInfoUpdateSuccessListener) () -> {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this,
            (OnConsentFormDismissedListener) loadAndShowError -> {
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, String.format("%s: %s",
                    loadAndShowError.getErrorCode(),
                    loadAndShowError.getMessage()));
              }

              // Consent has been gathered.
            }
          );
        },
        (OnConsentInfoUpdateFailureListener) requestConsentError -> {
          // Consent gathering failed.
          Log.w(TAG, String.format("%s: %s",
              requestConsentError.getErrorCode(),
              requestConsentError.getMessage()));
        });
  }
}

Kotlin

class MainActivity : AppCompatActivity() {
  private lateinit var consentInformation: ConsentInformation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Create a ConsentRequestParameters object.
    val params = ConsentRequestParameters
        .Builder()
        .build()

    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        ConsentInformation.OnConsentInfoUpdateSuccessListener {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this@MainActivity,
            ConsentForm.OnConsentFormDismissedListener {
              loadAndShowError ->
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
              }

              // Consent has been gathered.
            }
          )
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
  }
}

אם אתם צריכים לבצע פעולות כלשהן אחרי שהמשתמש ביצע החלטה או סגר בטופס, מוסיפים את הלוגיקה הזו callback עבור הטופס שלך.

אפשרויות פרטיות

חלק מהטפסים של הודעות בנושא פרטיות מוצגים מתוך ממשק פרטיות שעבר על ידי בעל התוכן הדיגיטלי נקודת כניסה, כך שמשתמשים יוכלו לנהל את אפשרויות הפרטיות שלהם בכל שלב. למידע נוסף על ההודעה שמוצגת למשתמשים באפשרויות הפרטיות נקודת כניסה, לראות הסוגים הזמינים של הודעות למשתמשים.

כדי להטמיע נקודת כניסה לאפשרויות פרטיות:

צריך לבדוק את ConsentInformation.PrivacyOptionsRequirementStatus.
אם נקודת כניסה לאפשרויות פרטיות היא נדרש, יש להוסיף לאפליקציה רכיב גלוי ואינטראקטיבי בממשק המשתמש.
הפעלת טופס אפשרויות הפרטיות באמצעות showPrivacyOptionsForm()

הקוד לדוגמה הבא מדגים את השלבים האלה:

Java

private final ConsentInformation consentInformation;

// Show a privacy options button if required.
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  // ...

  consentInformation = UserMessagingPlatform.getConsentInformation(this);
  consentInformation.requestConsentInfoUpdate(
      this,
      params,
      (OnConsentInfoUpdateSuccessListener) () -> {
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
          this,
          (OnConsentFormDismissedListener) loadAndShowError -> {
            // ...

            // Consent has been gathered.

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

@Override
public boolean onCreateOptionsMenu(Menu menu) {
  getMenuInflater().inflate(R.menu.action_menu, menu);
  MenuItem moreMenu = menu.findItem(R.id.action_more);
  moreMenu.setVisible(isPrivacyOptionsRequired());
  return true;
}

@Override
public boolean onOptionsItemSelected(MenuItem item) {
  // ...

  popup.setOnMenuItemClickListener(
      popupMenuItem -> {
        if (popupMenuItem.getItemId() == R.id.privacy_settings) {
          // Present the privacy options form when a user interacts with
          // the privacy settings button.
          UserMessagingPlatform.showPrivacyOptionsForm(
              this,
              formError -> {
                if (formError != null) {
                  // Handle the error.
                }
              }
          );
          return true;
        }
        return false;
      });
  return super.onOptionsItemSelected(item);
}

Kotlin

private val consentInformation: ConsentInformation =
  UserMessagingPlatform.getConsentInformation(context)

// Show a privacy options button if required.
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED

override fun onCreate(savedInstanceState: Bundle?) {
  // ...
  consentInformation = UserMessagingPlatform.getConsentInformation(this)
  consentInformation.requestConsentInfoUpdate(
      this,
      params,
      ConsentInformation.OnConsentInfoUpdateSuccessListener {
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
          this@MainActivity,
          ConsentForm.OnConsentFormDismissedListener {
            // ...

            // Consent has been gathered.

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

override fun onCreateOptionsMenu(menu: Menu?): Boolean {
  menuInflater.inflate(R.menu.action_menu, menu)
  menu?.findItem(R.id.action_more)?.apply {
    isVisible = isPrivacyOptionsRequired
  }
  return super.onCreateOptionsMenu(menu)
}

override fun onOptionsItemSelected(item: MenuItem): Boolean {
  // ...

  popup.setOnMenuItemClickListener { popupMenuItem ->
    when (popupMenuItem.itemId) {
      R.id.privacy_settings -> {
        // Present the privacy options form when a user interacts with
        // the privacy settings button.
        UserMessagingPlatform.showPrivacyOptionsForm(this) { formError ->
          formError?.let {
            // Handle the error.
          }
        }
        true
      }
      else -> false
    }
  }
  return super.onOptionsItemSelected(item)
}

בקשה להצגת מודעות

לפני ששולחים בקשה להצגת מודעות באפליקציה, צריך לבדוק אם קיבלת הסכמה מהמשתמש באמצעות canRequestAds(). יש שתי פלטפורמות מקומות שצריך לבדוק במהלך קבלת ההסכמה:

אחרי שהתקבלה הסכמה בסשן הנוכחי.
מיד לאחר שהתקשרת אל requestConsentInfoUpdate(). ייתכן שהתקבלה הסכמה בסשן הקודם. כזמן אחזור מומלץ לא להמתין עד לסיום הקריאה החוזרת כדי שתוכלו להתחיל לטעון מודעות בהקדם האפשרי אחרי השקת האפליקציה.

גם אם תתרחש שגיאה בתהליך קבלת ההסכמה, עדיין עליך מנסים לבקש מודעות. סטטוס ההסכמה מה-UMP SDK הקודם היה סשן.

Java

public class MainActivity extends AppCompatActivity {
  private ConsentInformation consentInformation;
  // Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
  private final AtomicBoolean isMobileAdsInitializeCalled = new AtomicBoolean(false);
  
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .build();

    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        (OnConsentInfoUpdateSuccessListener) () -> {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this,
            (OnConsentFormDismissedListener) loadAndShowError -> {
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, String.format("%s: %s",
                    loadAndShowError.getErrorCode(),
                    loadAndShowError.getMessage()));
              }

              // Consent has been gathered.
              if (consentInformation.canRequestAds()) {
                initializeMobileAdsSdk();
              }
            }
          );
        },
        (OnConsentInfoUpdateFailureListener) requestConsentError -> {
          // Consent gathering failed.
          Log.w(TAG, String.format("%s: %s",
              requestConsentError.getErrorCode(),
              requestConsentError.getMessage()));
        });
    
    // Check if you can initialize the Google Mobile Ads SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if (consentInformation.canRequestAds()) {
      initializeMobileAdsSdk();
    }
  }
  
  private void initializeMobileAdsSdk() {
    if (isMobileAdsInitializeCalled.getAndSet(true)) {
      return;
    }

    new Thread(
            () -> {
              // Initialize the Google Mobile Ads SDK on a background thread.
              
              MobileAds.initialize(this, initializationStatus -> {});
              runOnUiThread(
                  () -> {
                    // TODO: Request an ad.
                    // loadInterstitialAd();
                  });
              
            })
        .start();
  }
}

Kotlin

class MainActivity : AppCompatActivity() {
  private lateinit var consentInformation: ConsentInformation
  // Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
  private var isMobileAdsInitializeCalled = AtomicBoolean(false)
  
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Create a ConsentRequestParameters object.
    val params = ConsentRequestParameters
        .Builder()
        .build()

    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        ConsentInformation.OnConsentInfoUpdateSuccessListener {
          UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            this@MainActivity,
            ConsentForm.OnConsentFormDismissedListener {
              loadAndShowError ->
              if (loadAndShowError != null) {
                // Consent gathering failed.
                Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
              }

              // Consent has been gathered.
              if (consentInformation.canRequestAds()) {
                initializeMobileAdsSdk()
              }
            }
          )
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
    
    // Check if you can initialize the Google Mobile Ads SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if (consentInformation.canRequestAds()) {
      initializeMobileAdsSdk()
    }
  }
  
  private fun initializeMobileAdsSdk() {
    if (isMobileAdsInitializeCalled.getAndSet(true)) {
      return
    }

    val backgroundScope = CoroutineScope(Dispatchers.IO)
    backgroundScope.launch {
      
      MobileAds.initialize(this@MainActivity) {}
      runOnUiThread {
        // TODO: Request an ad.
        // loadInterstitialAd()
      }
      
    }
  }
}

בדיקה

כדי לבדוק את השילוב באפליקציה במהלך הפיתוח, צריך לפעול לפי השלבים הבאים: כדי לרשום את מכשיר הבדיקה באופן פרוגרמטי. חשוב להסיר את שמגדיר את מזהי מכשירי הבדיקה האלה לפני השקת האפליקציה.

התקשרות אל requestConsentInfoUpdate().
בודקים את פלט היומן להודעה שדומה לדוגמה הבאה: מציג את מזהה המכשיר ואיך להוסיף אותו כמכשיר בדיקה:
```
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
```
מעתיקים את מזהה מכשיר הבדיקה ללוח.
יש לשנות את הקוד כדי התקשרות ConsentDebugSettings.Builder().addTestDeviceHashedId() ומעבירים רשימה של המזהים של מכשירי הבדיקה.

אילוץ מיקום גיאוגרפי

UMP SDK מאפשר לבדוק את התנהגות האפליקציה כאילו המכשיר שנמצאים ב-EEA או בבריטניה דרך the setDebugGeography() method which takes a DebugGeography on ConsentDebugSettings.Builder. שימו לב הגדרות ניפוי הבאגים פועלות רק במכשירי בדיקה.

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

דוגמאות ב-GitHub

דוגמאות לשילוב של UMP SDK: Java | Kotlin

אני רוצה לנסות

דרישות מוקדמות

איך יוצרים את סוג ההודעה

התקנה באמצעות Gradle

מוסיפים את מזהה האפליקציה

בקשה למידע על הסכמה

Java

Kotlin

טעינה והצגת טופס הודעה בנושא פרטיות במקרה הצורך

Java

Kotlin

אפשרויות פרטיות

Java

Kotlin

בקשה להצגת מודעות

Java

Kotlin

בדיקה

אילוץ מיקום גיאוגרפי

Java

Kotlin

איפוס מצב ההסכמה

Java

Kotlin

דוגמאות ב-GitHub