מתחילים

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>

אחזור פרטי ההסכמה של המשתמש

כדי לקבל את פרטי ההסכמה של המשתמש:

מגדירים מופע של ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

מאתחלים את המכונה ConsentInformation:

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

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

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

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.java

Kotlin

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

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

טעינת הטופס של הודעת הפרטיות והצגתו

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

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

Java

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

Kotlin

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

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

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

בדיקה אם נדרשת נקודת כניסה לאפשרויות הפרטיות

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

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

הרשימה המלאה של סטטוסי הדרישות של אפשרויות הפרטיות מופיעה במאמר ConsentInformation.PrivacyOptionsRequirementStatus.

הצגת הטופס של אפשרויות הפרטיות

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

Java

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

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

שליחת בקשה להצגת מודעות עם הסכמת משתמשים

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

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

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

• אחרי ש-UMP SDK אוסף הסכמה בסשן הנוכחי.
• מיד אחרי שתתקשרו למספר requestConsentInfoUpdate(). יכול להיות ש-UMP SDK קיבל הסכמה בסשן הקודם של האפליקציה.

חשוב: הפונקציה canRequestAds() תמיד מחזירה את הערך false עד שמפעילים את הפונקציה requestConsentInfoUpdate()

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

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

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

בדיקה

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

הערה: החל מגרסה 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,
       // ...
   )
   

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

באמצעות 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()

אזהרה: השיטה הזו מיועדת לשימוש למטרות בדיקה בלבד. אסור להפעיל את reset() בקוד בסביבת הייצור.

דוגמאות ב-GitHub

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