תחילת העבודה

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

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

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

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

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

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

התקנה באמצעות 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.

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

מזהה האפליקציה מופיע בממשק המשתמש של 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(). הבקשה הזו בודקת את הפרטים הבאים:

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

אם צריך, טוענים טופס של הודעת פרטיות ומציגים אותו

אחרי שתקבלו את סטטוס ההסכמה העדכני ביותר, תוכלו להפעיל את הפונקציה 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

הוספת רכיב גלוי לאפליקציה

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

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(). יש שני מקומות שצריך לבדוק בזמן קבלת ההסכמה:

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

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

הקוד הבא בודק אם אפשר לשלוח בקשות להצגת מודעות במהלך תהליך קבלת ההסכמה:

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

בדיקה

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

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

איך מגדירים אזור גיאוגרפי

באמצעות UMP SDK אפשר לבדוק את אופן הפעולה של האפליקציה כאילו המכשיר נמצא באזורים שונים, כמו אזור הכלכלי האירופי או בריטניה, באמצעות 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,
    ...
)

כשבודקים את האפליקציה באמצעות ה-SDK של UMP, כדאי לאפס את המצב של ה-SDK כדי שתוכלו לדמות את חוויית ההתקנה הראשונה של המשתמש. כדי לעשות זאת, ה-SDK מספק את השיטה reset().

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

דוגמאות ב-GitHub

בקישורים הבאים תוכלו למצוא דוגמה מלאה לשילוב של UMP SDK שמופיע בדף הזה, במאמרים Java BannerExample ו- Kotlin BannerExample.