שנתחיל?

בהתאם למדיניות Google בנושא הסכמת משתמשים באיחוד האירופי, עליך להציג הודעות גילוי נאות מסוימות למשתמשים שנמצאים באזור הכלכלי האירופי (EEA) ובבריטניה. בנוסף, עליך לקבל את הסכמתם לשימוש בקובצי cookie או באמצעים אחרים לאחסון מקומי, כשהדבר נדרש על פי חוק, וגם לקבל את הסכמתם לשימוש במידע אישי (כמו מזהה פרסום) לצורך הצגת מודעות. המדיניות הזו משקפת את הדרישות שמפורטות ב-ePrivacy Directive (ההנחיה בנושא פרטיות ותקשורת אלקטרונית) וב-General Data Protection Regulation (התקנה הכללית להגנה על מידע, GDPR) של האיחוד האירופי.

כדי לעזור לבעלי אפליקציות למלא את החובות שלהם במסגרת המדיניות הזו, Google מציעה את User Messaging Platform (UMP) SDK. ה-UMP SDK עודכן כדי לתמוך בתקנים האחרונים של IAB. עכשיו אפשר לטפל בכל ההגדרות האלה בקלות AdMob בפרטיות ובהעברת הודעות.

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

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

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

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

ייבוא ה-SDK

CocoaPods (מועדף)

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

pod 'GoogleUserMessagingPlatform'

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

pod install --repo-update

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

מנהל חבילות Swift

UMP SDK תומך גם ב-Swift Package Manager. בצעו את השלבים הבאים על מנת לייבא את חבילת Swift.

  1. ב-Xcode, כדי להתקין את חבילת Swift של UMP SDK, עוברים אל File > Add Packages....

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

    https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
    
  3. יש לבחור בגרסה של חבילת Swift של UMP SDK שבה רוצים להשתמש. לפרויקטים חדשים, מומלץ להשתמש ב-Up to Next Major Version.

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

הורדה ידנית

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

הורדת ה-SDK

לאחר מכן גוררים את ה-framework לפרויקט ה-Xcode, ומוודאים שבוחרים באפשרות Copy items by need (העתקת פריטים במידת הצורך).

לאחר מכן אפשר לכלול את ה-framework בכל קובץ שדרוש לכם באמצעות:

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

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

דוגמה לאופן שבו בודקים את הסטטוס של UIViewController בשיטה viewDidLoad().

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
    [weak self] requestConsentError in
    guard let self else { return }

    if let consentError = requestConsentError {
      // Consent gathering failed.
      return print("Error: \(consentError.localizedDescription)")
    }

    // TODO: Load and present the consent form.
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }

            // TODO: Load and present the consent form.
          }];
}

טעינה והצגה של טופס הסכמה במקרה הצורך

חשוב: ממשקי ה-API הבאים תואמים ל-UMP SDK בגרסה 2.1.0 ואילך.

אחרי שמקבלים את סטטוס ההסכמה העדכני ביותר, צריך להתקשר לכיתהloadAndPresentIfRequiredFromViewController:completionHandler: UMPConsentForm בכיתה כדי לטעון טופס הסכמה. אם נדרש סטטוס הסכמה, ה-SDK יטען טופס ויוצג מיד מהטופס view controller. completion handler נקרא אחרי סגירת הטופס. אם לא נדרשת הסכמה, completion handler נקרא באופן מיידי.

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
    [weak self] requestConsentError in
    guard let self else { return }

    if let consentError = requestConsentError {
      // Consent gathering failed.
      return print("Error: \(consentError.localizedDescription)")
    }

    UMPConsentForm.loadAndPresentIfRequired(from: self) {
      [weak self] loadAndPresentError in
      guard let self else { return }

      if let consentError = loadAndPresentError {
        // Consent gathering failed.
        return print("Error: \(consentError.localizedDescription)")
      }

      // Consent has been gathered.
    }
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }

            __strong __typeof__(self) strongSelf = weakSelf;
            if (!strongSelf) {
              return;
            }

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  if (loadAndPresentError) {
                    // Consent gathering failed.
                    NSLog(@"Error: %@", loadAndPresentError.localizedDescription);
                    return;
                  }

                  // Consent has been gathered.
                }];
          }];
}

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

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

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

  1. אחרי שהמערכת תאסוף את ההסכמה בסשן הנוכחי.
  2. מיד לאחר שתתקשר אל requestConsentInfoUpdateWithParameters:completionHandler:. יכול להיות שקיבלנו הסכמה בסשן הקודם. כשיטה מומלצת לזמן אחזור, מומלץ לא להמתין עד שהקריאה החוזרת תסתיים, כדי שתוכלו להתחיל לטעון את המודעות בהקדם האפשרי אחרי הפעלת האפליקציה.

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

Swift

class ViewController: UIViewController {

  // Use a boolean to initialize the Google Mobile Ads SDK and load ads once.
  private var isMobileAdsStartCalled = false

  override func viewDidLoad() {
    super.viewDidLoad()

    // Request an update for the consent information.
    UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
      [weak self] requestConsentError in
      guard let self else { return }

      if let consentError = requestConsentError {
        // Consent gathering failed.
        return print("Error: \(consentError.localizedDescription)")
      }

      UMPConsentForm.loadAndPresentIfRequired(from: self) {
        [weak self] loadAndPresentError in
        guard let self else { return }

        if let consentError = loadAndPresentError {
          // Consent gathering failed.
          return print("Error: \(consentError.localizedDescription)")
        }

        // Consent has been gathered.
        if UMPConsentInformation.sharedInstance.canRequestAds {
          self.startGoogleMobileAdsSDK()
        }
      }
    }
    
    // Check if you can initialize the Google Mobile Ads SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if UMPConsentInformation.sharedInstance.canRequestAds {
      startGoogleMobileAdsSDK()
    }
  }
  
  private func startGoogleMobileAdsSDK() {
    DispatchQueue.main.async {
      guard !self.isMobileAdsStartCalled else { return }

      self.isMobileAdsStartCalled = true

      // Initialize the Google Mobile Ads SDK.
      GADMobileAds.sharedInstance().start()

      // TODO: Request an ad.
      // GADInterstitialAd.load(...)
    }
  }
}

Objective-C

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }
            __strong __typeof__(self) strongSelf = weakSelf;
            if (!strongSelf) {
              return;
            }

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  if (loadAndPresentError) {
                    // Consent gathering failed.
                    NSLog(@"Error: %@", loadAndPresentError.localizedDescription);
                    return;
                  }

                  // Consent has been gathered.
                  __strong __typeof__(self) strongSelf = weakSelf;
                  if (!strongSelf) {
                    return;
                  }

                  if (UMPConsentInformation.sharedInstance.canRequestAds) {
                    [strongSelf startGoogleMobileAdsSDK];
                  }
                }];
          }];

  // Check if you can initialize the Google Mobile Ads SDK in parallel
  // while checking for new consent information. Consent obtained in
  // the previous session can be used to request ads.
  if (UMPConsentInformation.sharedInstance.canRequestAds) {
    [self startGoogleMobileAdsSDK];
  }
}

- (void)startGoogleMobileAdsSDK {
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    // Initialize the Google Mobile Ads SDK.
    [GADMobileAds.sharedInstance startWithCompletionHandler:nil];

    // TODO: Request an ad.
    // [GADInterstitialAd loadWithAdUnitID...];
  });
}

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

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

לשם כך:

  1. מטמיעים רכיב בממשק המשתמש, כמו לחצן בדף ההגדרות של האפליקציה, שיכול להפעיל טופס של אפשרויות פרטיות.
  2. בסיום loadAndPresentIfRequiredFromViewController:completionHandler: מסמנים את התיבהprivacyOptionsRequirementStatus כדי לקבוע אם להציג את הרכיב בממשק המשתמש שיכול להציג את טופס אפשרויות הפרטיות.
  3. כשמשתמש יוצר אינטראקציה עם הרכיב בממשק המשתמש, צריך לבצע קריאה אל presentPrivacyOptionsFormFromViewController:completionHandler: כדי להציג את הטופס כדי שהמשתמש יוכל לעדכן את אפשרויות הפרטיות שלו בכל שלב.

הדוגמה הבאה ממחישה איך להציג את טופס אפשרויות הפרטיות מתוך UIBarButtonItem.

Swift

@IBOutlet weak var privacySettingsButton: UIBarButtonItem!

var isPrivacyOptionsRequired: Bool {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus == .required
}

override func viewDidLoad() {
  // ...

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
    // ...

    UMPConsentForm.loadAndPresentIfRequired(from: self) {
      //...

      // Consent has been gathered.

      // Show the button if privacy options are required.
      self.privacySettingsButton.isEnabled = isPrivacyOptionsRequired
    }
  }
  // ...
}

// Present the privacy options form when a user interacts with the
// privacy settings button.
@IBAction func privacySettingsTapped(_ sender: UIBarButtonItem) {
  UMPConsentForm.presentPrivacyOptionsForm(from: self) {
    [weak self] formError in
    guard let self, let formError else { return }

    // Handle the error.
  }
}

Objective-C

@interface ViewController ()
@property(weak, nonatomic) IBOutlet UIBarButtonItem *privacySettingsButton;
@end

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

- (void)viewDidLoad {
  // ...

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:parameters
          completionHandler:^(NSError *_Nullable requestConsentError) {
            // ...

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  // ...

                  // Consent has been gathered.

                  // Show the button if privacy options are required.
                  strongSelf.privacySettingsButton.enabled = isPrivacyOptionsRequired;
                }];
          }];
}

// Present the privacy options form when a user interacts with your
// privacy settings button.
- (IBAction)privacySettingsTapped:(UIBarButtonItem *)sender {
  [UMPConsentForm presentPrivacyOptionsFormFromViewController:self
                                completionHandler:^(NSError *_Nullable formError) {
                                  if (formError) {
                                    // Handle the error.
                                  }
                                }];
}

בדיקה

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

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

    <UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
    
  3. מעתיקים את מזהה מכשיר הבדיקה ללוח.

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

    Swift

    let parameters = UMPRequestParameters()
    let debugSettings = UMPDebugSettings()
    debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
    parameters.debugSettings = debugSettings
    // Include the UMPRequestParameters in your consent request.
    UMPConsentInformation.sharedInstance.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){
                              ...
    }];
    

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

באמצעות UMP SDK אפשר לבדוק את התנהגות האפליקציה כאילו המכשיר נמצא ב-EEA או בבריטניה באמצעות the debugGeography property of type UMPDebugGeography on UMPDebugSettings. שימו לב שהגדרות ניפוי הבאגים פועלות רק במכשירי בדיקה.

Swift

let parameters = UMPRequestParameters()
let debugSettings = UMPDebugSettings()
debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
debugSettings.geography = .EEA
parameters.debugSettings = debugSettings
// Include the UMPRequestParameters in your consent request.
UMPConsentInformation.sharedInstance.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

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

דוגמאות ב-GitHub

דוגמאות לשילוב של UMP SDK: Swift | Objective-C