הגדרת UMP SDK

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

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

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

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

  • אם נדרשת הסכמה. לדוגמה, אם נדרשת הסכמה בפעם הראשונה, או אם פג התוקף של החלטת ההסכמה הקודמת.
  • אם נדרשת נקודת כניסה לאפשרויות הפרטיות. חלק מההודעות בנושא פרטיות מחייבות את האפליקציות לאפשר למשתמשים לשנות את אפשרויות הפרטיות שלהם בכל שלב.
/**
 * Requests consent information update on app launch.
 */
export function requestConsent(onComplete?: () => void) {
  requestConsentInfoUpdate({}, (error) => {
    if (error) {
      console.warn('Consent info update error:', error.message);
    } else {
      console.log('Consent info update complete.');
    }

    // Load and show consent form if required.
    loadAndPresentConsentForm(onComplete);
  });
}

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

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

/**
 * Loads and presents the privacy message form if required to collect user consent.
 */
export function loadAndPresentConsentForm(onComplete?: () => void) {
  loadAndShowConsentFormIfRequired((formError) => {
    if (formError) {
      console.warn('Consent form error:', formError.message);
    } else {
      console.log('Consent gathering complete.');
    }

    // Execute logic that depends on consent state (for example, initialize the SDK).
    onComplete?.();
  });
}

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

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

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

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

/**
 * Helper to determine if the privacy options entry point is required.
 */
export function isPrivacyOptionsRequired(): boolean {
  return (
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED
  );
}

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

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

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

/**
 * Renders a privacy options button if required by user consent policy.
 */
export function PrivacyOptionsButton({
  onDismissed,
}: {
  onDismissed?: (error?: FormError) => void;
}) {
  const isRequired =
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED;

  if (!isRequired) {
    return null;
  }

  const handleShowPrivacyOptions = () => {
    showPrivacyOptionsForm((error) => {
      if (error) {
        console.error('Failed to show privacy options form:', error.message);
      } else {
        console.log('Privacy options form dismissed.');
      }

      // Execute custom logic after form is dismissed.
      onDismissed?.(error);
    });
  };

  return <Button title="Privacy Settings" onPress={handleShowPrivacyOptions} />;
}

בקשת מודעות בהסכמת המשתמש

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

/**
 * Checks whether user consent allows requesting ads and initializes the SDK.
 */
let isMobileAdsInitialized = false;

export function initializeMobileAdsSdkIfConsentGiven() {
  if (canRequestAds()) {
    if (!isMobileAdsInitialized) {
      isMobileAdsInitialized = true;
      initialize({}, (status) => {
        console.log('Google Mobile Ads SDK initialized:', status);
      });
    }
  }
}

ריכזנו כאן את המקומות שבהם אפשר לבדוק אם אפשר לבקש מודעות בזמן איסוף ההסכמה:

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

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

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

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

בדיקה

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

  1. התקשרו אל requestConsentInfoUpdate().

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

    Android

    Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231")
to set this as a debug device.

    iOS

    <UMP SDK>To enable debug mode for this device,
set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]

  3. מעתיקים את מזהה מכשיר הבדיקה ללוח.

  4. משנים את הקוד כדי להפעיל את consentDebugSettings.testDeviceIdentifiers ולהעביר רשימה של מזהי המכשירים לבדיקה.

    /**
 * Registers a test device for testing consent flows.
 */
export function configureTestDevice() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.DISABLED,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Test device registered.');
      }
    },
  );
}

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

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

/**
 * Configures debug settings to force EEA geography on a test device.
 */
export function configureDebugGeography() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.EEA,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Consent debug test configuration loaded.');
      }
    },
  );
}

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

/**
 * Resets consent state for testing purposes.
 */
export function resetConsentState() {
  reset();
}