הגדרת UMP SDK

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

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

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

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

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

ייבוא ה-SDK

‫CocoaPods (מועדף)

הדרך הקלה ביותר לייבא את ה-SDK לפרויקט ב-iOS היא להשתמש ב-CocoaPods. פותחים את קובץ ה-Podfile של הפרויקט ומוסיפים את השורה הזו ליעד של האפליקציה:

pod 'GoogleUserMessagingPlatform'

לאחר מכן, מריצים את הפקודה הבאה:

pod install --repo-update

אם אתם לא מכירים את CocoaPods, כדאי לקרוא את המאמר שימוש ב-CocoaPods כדי ללמוד איך ליצור קובצי Podfile ולהשתמש בהם.

Swift Package Manager

‫UMP SDK תומך גם ב-Swift Package Manager. כדי לייבא את חבילת Swift, פועלים לפי השלבים הבאים:

1. ב-Xcode, מתקינים את חבילת Swift של UMP SDK: עוברים אל File > Add Packages...‎ (קובץ > הוספת חבילות...‎).

2. בהנחיה שמופיעה, מחפשים את מאגר ה-GitHub של חבילת ה-Swift של ה-UMP SDK:

   https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
   

3. בוחרים את הגרסה של חבילת Swift של UMP SDK שבה רוצים להשתמש. בפרויקטים חדשים, מומלץ להשתמש באפשרות Up to Next Major Version.

אחרי שתסיימו, פלטפורמת Xcode תתחיל לטפל ביחסי התלות שבחבילה ולהוריד אותם ברקע. לפרטים נוספים על הוספת יחסי תלות של חבילות, קראו את המאמר של אפל.

הורדה ידנית

הדרך השנייה לייבא את ה-SDK היא באופן ידני.

הורדת ה-SDK

לאחר מכן, גוררים את ה-framework לפרויקט Xcode ומוודאים שבוחרים באפשרות Copy items if needed.

אחר כך אפשר לכלול את ה-framework בכל קובץ שצריך באמצעות:

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

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

מזהה האפליקציה מופיע בממשק המשתמש של AdMob. מוסיפים את המזהה אל Info.plist באמצעות קטע הקוד הבא:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

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

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

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

Swift

// Requesting an update to consent information should be called on every app launch.
ConsentInformation.shared.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  // ...
}
GoogleMobileAdsConsentManager.swift

SwiftUI

// Requesting an update to consent information should be called on every app launch.
ConsentInformation.shared.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  // ...
}
GoogleMobileAdsConsentManager.swift

Objective-C

// Requesting an update to consent information should be called on every app launch.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable requestConsentError) {
                           // ...
                         }];
GoogleMobileAdsConsentManager.m

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

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

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

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

Swift

try await ConsentForm.loadAndPresentIfRequired(from: viewController)
GoogleMobileAdsConsentManager.swift

SwiftUI

try await ConsentForm.loadAndPresentIfRequired(from: nil)
GoogleMobileAdsConsentManager.swift

Objective-C

[UMPConsentForm
    loadAndPresentIfRequiredFromViewController:viewController
                             completionHandler:^(NSError *_Nullable loadAndPresentError) {
                                 // Consent gathering process is complete.
                                }];
GoogleMobileAdsConsentManager.m

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

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

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

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

Swift

var isPrivacyOptionsRequired: Bool {
  return ConsentInformation.shared.privacyOptionsRequirementStatus == .required
}
GoogleMobileAdsConsentManager.swift

Objective-C

- (BOOL)isPrivacyOptionsRequired {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
         UMPPrivacyOptionsRequirementStatusRequired;
}
GoogleMobileAdsConsentManager.m

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

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

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

Swift

try await ConsentForm.presentPrivacyOptionsForm(from: viewController)
GoogleMobileAdsConsentManager.swift

SwiftUI

try await ConsentForm.presentPrivacyOptionsForm(from: nil)
GoogleMobileAdsConsentManager.swift

Objective-C

[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                          completionHandler:completionHandler];
GoogleMobileAdsConsentManager.m

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

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

Swift

ConsentInformation.shared.canRequestAds

Objective-C

UMPConsentInformation.sharedInstance.canRequestAds;

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

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

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

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

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

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

בדיקה

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

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

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

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

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

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

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

   Swift

   let parameters = RequestParameters()
   let debugSettings = DebugSettings()
   
   debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
   parameters.debugSettings = debugSettings
   
   // Include the UMPRequestParameters in your consent request.
   ConsentInformation.shared.requestConsentInfoUpdate(
       with: parameters,
       completionHandler: { error in
         // ...
       })
   

   Objective-C

   UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
   UMPDebugSettings *debugSettings = [[UMPDebugSettings alloc] init];
   
   debugSettings.testDeviceIdentifiers = @[ @"TEST-DEVICE-HASHED-ID" ];
   parameters.debugSettings = debugSettings;
   
   // Include the UMPRequestParameters in your consent request.
   [UMPConsentInformation.sharedInstance
       requestConsentInfoUpdateWithParameters:parameters
                           completionHandler:^(NSError *_Nullable error){
                             // ...
   }];
   

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

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

Swift

let parameters = RequestParameters()
let debugSettings = DebugSettings()

debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
debugSettings.geography = .EEA
parameters.debugSettings = debugSettings

// Include the UMPRequestParameters in your consent request.
ConsentInformation.shared.requestConsentInfoUpdate(
    with: parameters,
    completionHandler: { error in
      // ...
    })

Objective-C

UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
UMPDebugSettings *debugSettings = [[UMPDebugSettings alloc] init];

debugSettings.testDeviceIdentifiers = @[ @"TEST-DEVICE-HASHED-ID" ];
debugSettings.geography = UMPDebugGeographyEEA;
parameters.debugSettings = debugSettings;

// Include the UMPRequestParameters in your consent request.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable error){
                           // ...
}];

איפוס מצב ההסכמה

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

Swift

ConsentInformation.shared.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

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

דוגמאות ב-GitHub

דוגמה מלאה לשילוב של UMP SDK שמופיע בדף הזה זמינה בקישורים הבאים:

• Swift BannerExample
• SwiftUIDemo
• Objective-C BannerExample