דף זה תורגם על ידי Cloud Translation API.

מתחילים

Google User Messaging Platform (UMP) SDK הוא כלי לניהול פרטיות ובקשות הסכמה, שיעזור לכם לנהל את העדפות הפרטיות של המשתמשים. למידע נוסף, ראו מידע על הכלי 'פרטיות והודעות'. אפשר לראות הטמעה עובדת של IMA עם UMP SDK באפליקציות לדוגמה של UMP ב-Objective-C או ב-Swift.

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

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

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

מייבאים את ה-SDK

ה-UMP SDK לא נכלל כיחס תלות ל-IMA SDK, לכן עליכם להוסיף אותו בעצמכם באופן מפורש.

CocoaPods (מועדף)

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

pod 'GoogleUserMessagingPlatform'

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

pod install --repo-update

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

Swift Package Manager

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

ב-Xcode, מתקינים את חבילת Swift של UMP SDK. לשם כך, עוברים אל File (קובץ) > Add Packages (הוספת חבילות)….
בהודעה שמופיעה, מחפשים את המאגר של UMP SDK Swift Package ב-GitHub:
```
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
```
בוחרים את הגרסה של חבילת Swift של UMP SDK שבה רוצים להשתמש. בפרויקטים חדשים, מומלץ להשתמש באפשרות עד לגרסה הראשית הבאה.

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

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

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

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

איסוף הסכמה

כדי לקבל הסכמה, מבצעים את השלבים הבאים:

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

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

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

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

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

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

Swift


// Requesting an update to consent information should be called on every app launch.
UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  guard requestConsentError == nil else {
    return consentGatheringComplete(requestConsentError)
  }

  UMPConsentForm.loadAndPresentIfRequired(from: consentFormPresentationviewController) {
    loadAndPresentError in

    // Consent has been gathered.
    consentGatheringComplete(loadAndPresentError)
  }
}ConsentManager.swift

Objective-C


// Requesting an update to consent information should be called on every app launch.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable requestConsentError) {
                           if (requestConsentError) {
                             consentGatheringComplete(requestConsentError);
                           } else {
                             [UMPConsentForm
                                 loadAndPresentIfRequiredFromViewController:viewController
                                                          completionHandler:^(
                                                              NSError
                                                                  *_Nullable loadAndPresentError) {
                                                            // Consent has been gathered.
                                                            consentGatheringComplete(
                                                                loadAndPresentError);
                                                          }];
                           }
                         }];ConsentManager.m

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

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

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

אחרי שמפעילים את requestConsentInfoUpdateWithParameters:completionHandler:, בודקים את UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus כדי לקבוע אם נדרשת נקודת כניסה לאפשרויות הפרטיות באפליקציה:

Swift


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

Objective-C


- (BOOL)areGDPRConsentMessagesRequired {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
         UMPPrivacyOptionsRequirementStatusRequired;
}ConsentManager.m

הוספת רכיב גלוי לאפליקציה

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

Swift


self.privacySettingsButton.isEnabled = ConsentManager.shared.isPrivacyOptionsRequiredViewController.swift

Objective-C


// Set up the privacy options button to show the UMP privacy form.
// Check ConsentInformation.getPrivacyOptionsRequirementStatus
// to see the button should be shown or hidden.
strongSelf.privacySettingsButton.hidden =
    !ConsentManager.sharedInstance.areGDPRConsentMessagesRequired;ViewController.m

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

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

Swift


UMPConsentForm.presentPrivacyOptionsForm(
  from: viewController, completionHandler: completionHandler)ConsentManager.swift

Objective-C


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

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

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

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

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

הקוד הבא בודק אם אפשר לשלוח בקשות להצגת מודעות במהלך תהליך קבלת ההסכמה:

Swift


ConsentManager.shared.gatherConsent(from: self) { [weak self] consentError in
  guard let self else { return }

  if let consentError {
    // Consent gathering failed. This sample loads ads using
    // consent obtained in the previous session.
    print("Error: \(consentError.localizedDescription)")
  }
  // ...
}ViewController.swift

Objective-C


  [ConsentManager.sharedInstance
      gatherConsentFromConsentPresentationViewController:self
                                consentGatheringComplete:^(NSError *_Nullable consentError) {
                                  if (consentError) {
                                    // Consent gathering failed.
                                    NSLog(@"Error: %@", consentError.localizedDescription);
                                  }

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

                                  // ...

                                  if (ConsentManager.sharedInstance.canRequestAds) {
                                    [strongSelf setupAdsLoader];
                                  }
                                }];

  // This sample attempts to load ads using consent obtained in the previous session.
  if (ConsentManager.sharedInstance.canRequestAds) {
    [self setupAdsLoader];
  }

  [self setUpContentPlayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestAds];
  self.playButton.hidden = YES;
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

#pragma mark SDK Setup

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;
}

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}

#pragma mark AdsLoader Delegates

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}

#pragma mark AdsManager Delegates

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}

@end
ViewController.m

הקוד הבא מגדיר את IMA DAI SDK אחרי קבלת ההסכמה מהמשתמש:

Swift


private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: ViewController.testAppAdTagURL,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}ViewController.swift

Objective-C


- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;
}ViewController.m

בדיקה

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

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

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

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){
                           // ...
}];

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

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

Swift

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

דוגמאות ב-GitHub

דוגמה מלאה לשילוב של UMP SDK שמפורט בדף הזה מופיעה ב- UmpExample ל-Swift וב- UmpExample ל-Objective-C.

הסכמה באיחוד האירופי ו-GDPR

מתחילים

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

מייבאים את ה-SDK

CocoaPods (מועדף)

Swift Package Manager

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

איסוף הסכמה

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

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

Swift

Objective-C

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

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

Swift

Objective-C

הוספת רכיב גלוי לאפליקציה

Swift

Objective-C

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

Swift

Objective-C

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

Swift

Objective-C

Swift

Objective-C

בדיקה

Swift

Objective-C

איך מגדירים אזור גיאוגרפי

Swift

Objective-C

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

Swift

Objective-C

דוגמאות ב-GitHub