Pakiet SDK platformy do personalizowania wiadomości wyświetlanych użytkownikom (UMP) od Google to narzędzie do zarządzania prywatnością i wyświetlania wiadomości, które ułatwia Ci zarządzanie ustawieniami prywatności. Więcej informacji znajdziesz w artykule Informacje o narzędziu Prywatność i wyświetlanie wiadomości. Działającą implementację IMA z pakietem UMP SDK możesz zobaczyć w aplikacji UMP Sample w językach Objective-C lub Swift.
Tworzenie typu wiadomości
Utwórz wiadomości dla użytkowników za pomocą jednej z dostępnych opcji wiadomości dla użytkowników na karcie Prywatność i wyświetlanie wiadomości w swoim koncie Ad Managera. Pakiet UMP SDK próbuje wyświetlić wiadomość dotyczącą prywatności utworzoną na podstawie identyfikatora aplikacji reklam interaktywnych medialnych określonego w Twoim projekcie.
Więcej informacji znajdziesz w artykule na temat prywatności i wyświetlania wiadomości.
Importowanie pakietu SDK
Pakiet UMP SDK nie jest uwzględniany jako zależność pakietu IMA SDK, dlatego musisz go dodać samodzielnie.
CocoaPods (preferowane)
Najłatwiejszym sposobem importowania pakietu SDK do projektu na iOS jest użycie CocoaPods. Otwórz plik Podfile projektu i dodaj ten wiersz do środowiska docelowego aplikacji:
pod 'GoogleUserMessagingPlatform'
Następnie uruchom to polecenie:
pod install --repo-update
Jeśli nie znasz CocoaPods, zapoznaj się z artykułem Korzystanie z CocoaPods, aby dowiedzieć się, jak tworzyć i używać plików Pod.
Menedżer pakietów Swift
Pakiet UMP SDK obsługuje też menedżera pakietów Swift. Aby zaimportować pakiet Swift, wykonaj te czynności.
W Xcode zainstaluj pakiet Swift pakietu SDK UMP, wybierając Plik > Dodaj pakiety….
W wyświetlonym oknie wyszukaj repozytorium UMP SDK Swift pakietu GitHub:
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
Wybierz wersję pakietu UMP SDK Swift, której chcesz użyć. W przypadku nowych projektów zalecamy użycie opcji Aktualizacja do następnej głównej wersji.
Następnie Xcode wykrywa zależności pakietu i pobiera je w tle. Więcej informacji o dodawaniu zależności pakietu znajdziesz w artykule Apple.
Dodawanie identyfikatora aplikacji
Identyfikator aplikacji znajdziesz w interfejsie Ad Managera.
Dodaj identyfikator do pliku Info.plist
za pomocą tego fragmentu kodu:
<key>UMPApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>
Zbieranie zgody
Aby uzyskać zgodę użytkowników, wykonaj te czynności:
- Prośba o najnowsze informacje o zgodzie użytkownika.
- W razie potrzeby wyświetl formularz zgody.
Prośba o informacje dotyczące zgody
Za każdym razem, gdy uruchamiasz aplikację, powinnaś poprosić o zaktualizowanie informacji o zgodzie użytkownika, używając do tego tagu
requestConsentInfoUpdateWithParameters:completionHandler:
. Ta prośba sprawdza te kwestie:
- Określ, czy wymagana jest zgoda. Może to być na przykład pierwsza zgoda na wykorzystanie danych lub zgoda udzielona wcześniej wygasła.
- Czy wymagany jest punkt wejścia opcji prywatności. Niektóre wiadomości dotyczące ochrony prywatności wymagają, aby aplikacje umożliwiały użytkownikom zmianę opcji prywatności w dowolnym momencie.
W razie potrzeby wczytaj i wyświetl formularz wiadomości dotyczącej ochrony prywatności
Po uzyskaniu najbardziej aktualnego stanu zgody wywołaj
loadAndPresentIfRequiredFromViewController:completionHandler:
, aby wczytać wszelkie formularze wymagane do uzyskiwania zgody użytkowników. Po załadowaniu formularze są od razu widoczne.
Poniższy kod pokazuje, jak poprosić o najnowsze informacje o zgodzie użytkownika. W razie potrzeby kod wczyta i wyświetli formularz z wiadomością dotyczącą prywatności:
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)
}
}
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);
}];
}
}];
Opcje prywatności
Niektóre formularze wiadomości dotyczące prywatności są wyświetlane w punktach wejścia opcji prywatności przygotowanych przez wydawcę, co pozwala użytkownikom w dowolnym momencie zarządzać opcjami prywatności. Aby dowiedzieć się więcej o tym, która wiadomość wyświetla się użytkownikom w punkcie wejścia do ustawień prywatności, zapoznaj się z artykułem Dostępne typy wiadomości dla użytkowników.
Sprawdzanie, czy punkt wejścia opcji prywatności jest wymagany
Po wywołaniu
requestConsentInfoUpdateWithParameters:completionHandler:
sprawdź
UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus
, by określić, czy punkt wejścia opcji prywatności jest wymagany w aplikacji:
Swift
var isPrivacyOptionsRequired: Bool {
return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus == .required
}
Objective-C
- (BOOL)areGDPRConsentMessagesRequired {
return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
UMPPrivacyOptionsRequirementStatusRequired;
}
Dodawanie widocznego elementu do aplikacji
Jeśli punkt wejścia prywatności jest wymagany, dodaj do aplikacji widoczny i interaktywny element interfejsu przedstawiający formularz opcji prywatności. Jeśli punkt wejścia prywatności nie jest wymagany, skonfiguruj element interfejsu w taki sposób, aby nie był widoczny i nie wymagał interakcji.
Swift
self.privacySettingsButton.isEnabled = ConsentManager.shared.isPrivacyOptionsRequired
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;
Wyświetl formularz opcji prywatności.
Gdy użytkownik wejdzie w interakcję z elementem, wyświetl formularz opcji prywatności:
Swift
UMPConsentForm.presentPrivacyOptionsForm(
from: viewController, completionHandler: completionHandler)
Objective-C
[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
completionHandler:completionHandler];
Wyślij żądanie
Zanim wyślesz prośbę o reklamy w aplikacji, sprawdź, czy masz zgodę użytkownika za pomocą
UMPConsentInformation.sharedInstance.canRequestAds
. Podczas zbierania zgody należy sprawdzić 2 miejsca:
- Po wyrażeniu zgody w bieżącej sesji.
- Natychmiast po zakończeniu rozmowy
requestConsentInfoUpdateWithParameters:completionHandler:
. Możliwe, że zgoda została uzyskana w poprzedniej sesji. W ramach najlepszej praktyki dotyczącej opóźnień zalecamy, aby nie czekać na zakończenie wywołania zwrotnego, aby można było jak najszybciej rozpocząć wczytywanie reklam po uruchomieniu aplikacji.
Jeśli podczas procesu zbierania zgód wystąpi błąd, sprawdź, czy możesz nadal wysyłać żądania reklam. Pakiet UMP SDK używa stanu zgody z poprzedniej sesji.
Ten kod sprawdza, czy możesz wysyłać żądania reklam w trakcie procesu uzyskiwania zgody użytkowników:
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)")
}
// ...
}
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
Poniższy kod konfiguruje pakiet Interactive Media Ads SDK po uzyskaniu zgody użytkownika:
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)
}
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
self.adsLoader.delegate = self;
}
Testowanie
Jeśli chcesz przetestować integrację z aplikacją podczas jej programowania, wykonaj te czynności, aby automatycznie zarejestrować urządzenie testowe. Zanim opublikujesz aplikację, usuń kod, który ustawia te identyfikatory testowych urządzeń.
- Zadzwoń do firmy
requestConsentInfoUpdateWithParameters:completionHandler:
. Sprawdź dane wyjściowe dziennika pod kątem komunikatu podobnego do tego, który zawiera identyfikator urządzenia i informacje o dodaniu go jako urządzenia testowego:
<UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
Skopiuj identyfikator testowego urządzenia do schowka.
Zmodyfikuj kod, aby wywołać funkcję
UMPDebugSettings().testDeviceIdentifiers
i przekazać listę identyfikatorów urządzeń testowych.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){ // ... }];
Wymuszenie lokalizacji geograficznej
Pakiet SDK UMP umożliwia testowanie działania aplikacji tak, jakby urządzenie znajdowało się w różnych regionach, np. w Europejskim Obszarze Gospodarczym lub Wielkiej Brytanii, za pomocą parametru UMPDebugGeography. Pamiętaj, że ustawienia debugowania działają tylko na urządzeniach testowych.
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){
// ...
}];
Resetowanie stanu zgody
Podczas testowania aplikacji za pomocą pakietu UMP SDK warto zresetować stan pakietu SDK, aby można było symulować pierwsze uruchomienie aplikacji przez użytkownika.
W tym celu pakiet SDK udostępnia metodę reset
.
Swift
UMPConsentInformation.sharedInstance.reset()
Objective-C
[UMPConsentInformation.sharedInstance reset];
Przykłady w GitHub
Pełny przykład integracji pakietu UMP SDK omówionego na tej stronie znajdziesz w plikach Swift UmpExample i Objective-C UmpExample.