Mulai

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 implementasi IMA yang berfungsi dengan UMP SDK di bagian Objective-C atau Swift Aplikasi contoh UMP.

Buat jenis pesan

Buat pesan pengguna dengan salah satu Jenis pesan pengguna yang tersedia di bagian Privasi & tab pesan Pengelola Iklan menggunakan akun layanan. UMP SDK berupaya menampilkan pesan privasi yang dibuat dari Interactive Media Ads ID Aplikasi tetapkan dalam project Anda.

Untuk detail selengkapnya, lihat Tentang privasi dan pesan.

Mengimpor SDK

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

CocoaPods (lebih disarankan)

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

pod 'GoogleUserMessagingPlatform'

Lalu, jalankan perintah berikut:

pod install --repo-update

Jika Anda baru menggunakan CocoaPods, lihat Menggunakan CocoaPods untuk mengetahui detail cara untuk 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 Swift Package UMP SDK dengan membuka File > Tambahkan Paket....

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

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

3. Pilih versi Swift Package UMP SDK yang ingin Anda gunakan. Untuk baru sebaiknya gunakan Up to Next Major Version.

Xcode kemudian menyelesaikan dependensi paket Anda dan mengunduhnya di latar belakang. Untuk detail selengkapnya tentang cara menambahkan dependensi paket, lihat aplikasi artikel ini.

Menambahkan ID aplikasi

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

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

Meminta informasi izin

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

• Apakah izin diperlukan atau tidak. Misalnya, izin diperlukan untuk pertama kali, atau keputusan izin sebelumnya sudah tidak berlaku.
• Apakah titik entri opsi privasi diperlukan atau tidak. Beberapa pesan privasi mewajibkan aplikasi untuk mengizinkan pengguna mengubah opsi privasi mereka kapan saja.

Berikut adalah contoh cara memeriksa status dari UIViewController di Metode viewDidLoad().

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 privacy message form.
  }
}

- (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 privacy message form.
          }];
}

Memuat dan menampilkan formulir pesan privasi jika diperlukan

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

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

- (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.
                }];
          }];
}

Jika Anda perlu melakukan tindakan apa pun setelah pengguna membuat pilihan atau menolak formulir, tempatkan logika itu di completion handler untuk formulir Anda.

Opsi privasi

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

Untuk menerapkan titik entri opsi privasi, selesaikan langkah-langkah berikut:

1. Periksa UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus.
2. Jika titik entri opsi privasi diperlukan, tambahkan elemen UI yang terlihat dan dapat berinteraksi ke aplikasi Anda.
3. Picu formulir opsi privasi menggunakan presentPrivacyOptionsFormFromViewController:completionHandler:.

Contoh kode berikut menunjukkan langkah-langkah ini:

@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.
  }
}

@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.
                                  }
                                }];
}

Permintaan iklan

Sebelum meminta iklan di aplikasi, periksa apakah Anda telah memperoleh izin dari pengguna menggunakan UMPConsentInformation.sharedInstance.canRequestAds. Ada dua tempat yang harus diperiksa saat mengumpulkan persetujuan:

• Setelah izin dikumpulkan di sesi saat ini.
• Segera setelah Anda menelepon requestConsentInfoUpdateWithParameters:completionHandler:. Mungkin izin telah diperoleh di sesi sebelumnya. Sebagai latensi praktik terbaiknya, sebaiknya jangan menunggu callback selesai sehingga Anda bisa mulai memuat iklan sesegera mungkin setelah aplikasi diluncurkan.

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

class ViewController: UIViewController {

  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.startImaSdk()
        }
      }
    }
    
    // Check if you can initialize the IMA 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 {
      startImaSdk()
    }
  }
  
  private func startImaSdk() {
    // Create an IMAAdsLoader instance.
    adsLoader = IMAAdsLoader(settings: nil)

    // TODO: Create an IMAAdDisplayContainer and IMAAdsRequest, then make
    // a request for ads.
  }
}

@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 startImaSdk];
                  }
                }];
          }];

  // Check if you can initialize the Google IMA 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 startImaSdk];
  }
}

- (void)startImaSdk {
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    // Create an IMAAdsLoader instance.
    self.adsLoader = [[IMAAdsLoader alloc] init];

    // TODO: Create an IMAAdDisplayContainer and IMAAdsRequest, then make
    // a request for ads.
  });
}

Pengujian

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

1. Panggil requestConsentInfoUpdateWithParameters:completionHandler:.

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

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

3. Salin ID perangkat pengujian ke papan klip.

4. Ubah kode Anda untuk ditelepon 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){
                             ...
   }];
   

Paksa geografi

UMP SDK menyediakan cara untuk menguji perilaku aplikasi seolah-olah perangkat yang berlokasi di EEA atau Inggris Raya menggunakan the debugGeography property of type UMPDebugGeography on UMPDebugSettings. Perlu diketahui bahwa setelan debug hanya berfungsi di perangkat pengujian.

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
      ...
    })

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

Dalam menguji aplikasi dengan UMP SDK, sebaiknya reset SDK agar Anda bisa melakukan simulasi pengalaman penginstalan pertama pengguna. SDK menyediakan metode reset untuk melakukannya.

UMPConsentInformation.sharedInstance.reset()

[UMPConsentInformation.sharedInstance reset];

Contoh di GitHub