הגדרת UMP SDK

‫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
  // ...
}

SwiftUI


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

Objective-C


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

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

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

Swift


try await ConsentForm.loadAndPresentIfRequired(from: viewController)

SwiftUI


try await ConsentForm.loadAndPresentIfRequired(from: nil)

Objective-C


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

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

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

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

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

Swift


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

Objective-C


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

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

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

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

Swift


try await ConsentForm.presentPrivacyOptionsForm(from: viewController)

SwiftUI


try await ConsentForm.presentPrivacyOptionsForm(from: nil)

Objective-C


[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                          completionHandler:completionHandler];

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

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

Swift

ConsentInformation.shared.canRequestAds

Objective-C

UMPConsentInformation.sharedInstance.canRequestAds;

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

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

אם מתרחשת שגיאה במהלך תהליך איסוף ההסכמה, צריך לבדוק אם אפשר לבקש מודעות. ערכת ה-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 מספק את השיטה reset.

Swift

ConsentInformation.shared.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

דוגמאות ב-GitHub

דוגמה מלאה לשילוב של ה-UMP SDK שמופיע בדף הזה זמינה ב-