Memulai

Google User Messaging Platform (UMP) SDK adalah alat privasi dan pesan untuk membantu Anda mengelola pilihan privasi. Untuk informasi selengkapnya, lihat Tentang Privasi & pesan. Anda dapat melihat penerapan IMA yang berfungsi dengan UMP SDK di aplikasi contoh UMP Objective-C atau Swift.

Membuat jenis pesan

Buat pesan pengguna dengan salah satu Jenis pesan pengguna yang tersedia di tab Privasi & pesan di akun Ad Manager Anda. UMP SDK mencoba menampilkan pesan privasi yang dibuat dari ID Aplikasi Iklan Media Interaktif yang ditetapkan dalam project Anda.

Untuk mengetahui detail selengkapnya, lihat Tentang privasi dan pesan.

Mengimpor SDK

UMP SDK tidak disertakan sebagai dependensi IMA SDK, jadi Anda harus menambahkannya secara eksplisit sendiri.

CocoaPods (lebih disukai)

Cara termudah untuk mengimpor SDK ke dalam project iOS adalah dengan menggunakan CocoaPods. Buka Podfile project dan tambahkan baris ini ke target aplikasi:

pod 'GoogleUserMessagingPlatform'

Kemudian, jalankan perintah berikut:

pod install --repo-update

Jika Anda baru menggunakan CocoaPods, lihat Menggunakan CocoaPods untuk mengetahui detail tentang cara membuat dan menggunakan Podfile.

Swift Package Manager

UMP SDK juga mendukung Swift Package Manager. Ikuti langkah-langkah berikut untuk mengimpor paket Swift.

1. Di Xcode, instal Paket Swift UMP SDK dengan membuka File > Add Packages....

2. Pada perintah yang muncul, telusuri repositori GitHub Paket Swift UMP SDK:

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

3. Pilih versi Paket Swift UMP SDK yang ingin Anda gunakan. Untuk project baru, sebaiknya gunakan Sampai Versi Utama Berikutnya.

Xcode kemudian akan me-resolve dependensi paket Anda dan mendownloadnya di latar belakang. Untuk mengetahui detail selengkapnya tentang cara menambahkan dependensi paket, lihat artikel Apple.

Menambahkan ID aplikasi

Anda dapat menemukan ID aplikasi di UI Ad Manager. Tambahkan ID ke Info.plist Anda dengan cuplikan kode berikut:

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

Mengumpulkan izin

Untuk mengumpulkan izin, selesaikan langkah-langkah berikut:

1. Meminta informasi izin pengguna terbaru.
2. Memuat dan menampilkan formulir izin, jika diperlukan.

Permintaan informasi izin

Anda harus meminta pembaruan informasi izin pengguna di setiap peluncuran aplikasi, menggunakan requestConsentInfoUpdateWithParameters:completionHandler:. Permintaan ini memeriksa hal berikut:

• Apakah izin diperlukan. Misalnya, izin diperlukan untuk pertama kalinya, atau masa berlaku keputusan izin sebelumnya telah berakhir.
• Apakah titik entri opsi privasi diperlukan. Beberapa pesan privasi memerlukan aplikasi untuk mengizinkan pengguna mengubah opsi privasi mereka kapan saja.

Peringatan: Menggunakan cara lain untuk memeriksa status izin, seperti cache di aplikasi Anda atau string izin yang disimpan sebelumnya, dapat menyebabkan error TCF 3.3 jika izin telah berakhir masa berlakunya.

Memuat dan menampilkan formulir pesan privasi jika diperlukan

Setelah Anda menerima status izin terbaru, panggil loadAndPresentIfRequiredFromViewController:completionHandler: untuk memuat formulir yang diperlukan untuk mengumpulkan izin pengguna. Setelah dimuat, formulir akan langsung ditampilkan.

Poin Penting: Jika tidak ada formulir pesan privasi yang mewajibkan pengumpulan izin pengguna sebelum meminta iklan, callback akan segera dipanggil.

Kode berikut menunjukkan cara meminta informasi izin terbaru pengguna. Jika diperlukan, kode akan dimuat dan menampilkan formulir pesan privasi:

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

Opsi privasi

Beberapa formulir pesan privasi ditampilkan dari titik entri opsi privasi yang dirender penayang, sehingga pengguna dapat mengelola opsi privasi mereka kapan saja. Untuk mempelajari lebih lanjut pesan yang dilihat pengguna di titik entri opsi privasi, lihat Jenis pesan pengguna yang tersedia.

Memeriksa apakah titik entri opsi privasi diperlukan

Setelah Anda memanggil requestConsentInfoUpdateWithParameters:completionHandler:, periksa UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus untuk menentukan apakah titik entri opsi privasi diperlukan untuk aplikasi Anda:

Swift

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

Objective-C

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

Menambahkan elemen yang terlihat ke aplikasi

Jika titik entri privasi diperlukan, tambahkan elemen UI yang terlihat dan dapat berinteraksi ke aplikasi Anda yang menampilkan formulir opsi privasi. Jika titik entri privasi tidak diperlukan, konfigurasikan elemen UI Anda agar tidak terlihat dan dapat berinteraksi.

Swift

self.privacySettingsButton.isEnabled = ConsentManager.shared.isPrivacyOptionsRequired
ViewController.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

Menampilkan formulir opsi privasi

Saat pengguna berinteraksi dengan elemen Anda, tampilkan formulir opsi privasi:

Swift

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

Objective-C

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

Permintaan iklan

Sebelum meminta iklan di aplikasi, periksa apakah Anda telah mendapatkan izin dari pengguna menggunakan UMPConsentInformation.sharedInstance.canRequestAds. Ada dua tempat untuk memeriksa saat mengumpulkan izin:

• Setelah izin dikumpulkan dalam sesi saat ini.
• Segera setelah Anda memanggil requestConsentInfoUpdateWithParameters:completionHandler:. Izin mungkin telah diperoleh dalam sesi sebelumnya. Sebagai praktik terbaik latensi, sebaiknya jangan menunggu callback selesai agar Anda dapat mulai memuat iklan sesegera mungkin setelah aplikasi diluncurkan.

Catatan: UMPConsentInformation.sharedInstance.canRequestAds selalu menampilkan false hingga Anda memanggil requestConsentInfoUpdateWithParameters:completionHandler:

Jika terjadi error selama proses pengumpulan izin, Anda tetap harus memeriksa apakah Anda dapat meminta iklan. UMP SDK menggunakan status izin dari sesi sebelumnya.

Kode berikut memeriksa apakah Anda dapat meminta iklan selama proses pengumpulan izin:

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

Kode berikut menyiapkan Interactive Media Ads SDK setelah izin pengguna dikumpulkan:

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

Pengujian

Jika Anda ingin menguji integrasi di aplikasi saat sedang mengembangkan, ikuti langkah-langkah berikut untuk mendaftarkan perangkat pengujian secara terprogram. Pastikan untuk menghapus kode yang menetapkan ID perangkat pengujian ini sebelum merilis aplikasi.

Catatan: Simulator tidak perlu ditambahkan ke daftar ID perangkat karena merupakan perangkat pengujian secara default.

1. Hubungi requestConsentInfoUpdateWithParameters:completionHandler:.

2. Periksa output log untuk menemukan pesan yang mirip dengan contoh berikut, yang menampilkan ID perangkat Anda dan cara menambahkannya sebagai perangkat pengujian:

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

3. Salin ID perangkat pengujian Anda ke papan klip.

4. Ubah kode Anda untuk memanggil UMPDebugSettings().testDeviceIdentifiers dan teruskan daftar ID perangkat pengujian Anda.

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

Memaksa geografi

UMP SDK menyediakan cara untuk menguji perilaku aplikasi Anda seolah-olah perangkat berada di berbagai wilayah, seperti EEA atau Inggris Raya, menggunakan UMPDebugGeography. Perhatikan bahwa setelan debug hanya berfungsi di perangkat pengujian.

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

Mereset status izin

Saat menguji aplikasi dengan UMP SDK, Anda mungkin perlu mereset status SDK agar dapat menyimulasikan pengalaman penginstalan pertama pengguna. SDK menyediakan metode reset untuk melakukannya.

Swift

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

Perhatian: Metode ini hanya ditujukan untuk tujuan pengujian. Anda tidak boleh memanggil reset dalam kode produksi.

Contoh di GitHub

Lihat contoh lengkap integrasi UMP SDK yang dibahas di halaman ini di Swift UmpExample dan Objective-C UmpExample.