הגדרת UMP SDK

בחירת פלטפורמה: Android iOS Unity Flutter Android (גרסה קודמת)

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

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

• ‫Android API ברמת 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:4.0.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>

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

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

מצהירים על מופע של ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit var 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

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

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

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

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

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

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 מספק את ה-method‏ reset().

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

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

דוגמאות ב-GitHub

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