מתחילים

בחירת פלטפורמה: Android iOS Unity Flutter

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

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

  • רמת ה-API ב-Android היא 21 ומעלה

יצירת סוג הודעה

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

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

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

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

אפשר למצוא את מזהה האפליקציה בממשק המשתמש של 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 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

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

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

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 קיבל הסכמה בסשן הקודם באפליקציה.

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

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

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

בדיקה

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

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

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

דוגמאות ב-GitHub

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