Le SDK Google UMP (User Messaging Platform) est un outil de confidentialité et de messagerie qui vous aide à gérer les choix de confidentialité. Pour en savoir plus, consultez la section À propos de "Confidentialité et messages". Vous pouvez voir une implémentation IMA fonctionnelle avec le SDK UMP dans les applications exemples UMP Objective-C ou Swift.
Créer un type de message
Créez des messages destinés aux utilisateurs à l'aide de l'un des types de messages disponibles dans l'onglet Confidentialité et messages de votre compte Ad Manager. Le SDK UMP tente d'afficher un message de confidentialité créé à partir de l'ID d'application Interactive Media Ads défini dans votre projet.
Pour en savoir plus, consultez la section À propos de la confidentialité et des messages.
Importer le SDK
Le SDK UMP n'est pas inclus en tant que dépendance du SDK IMA. Vous devez donc l'ajouter vous-même de manière explicite.
CocoaPods (à privilégier)
Le moyen le plus simple d'importer le SDK dans un projet iOS consiste à utiliser CocoaPods. Ouvrez le fichier Podfile de votre projet et ajoutez cette ligne à la cible de votre application :
pod 'GoogleUserMessagingPlatform'
Exécutez ensuite la commande suivante :
pod install --repo-update
Si vous débutez avec CocoaPods, consultez la page Utiliser CocoaPods pour découvrir comment créer et utiliser des Podfiles.
Swift Package Manager
Le SDK UMP est également compatible avec Swift Package Manager. Pour importer le package Swift, procédez comme suit :
Dans Xcode, installez le package Swift du SDK UMP en accédant à File > Add Packages... (Fichier > Ajouter des packages...).
Dans l'invite qui s'affiche, recherchez le dépôt GitHub du package Swift du SDK UMP :
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
Sélectionnez la version du package Swift du SDK UMP que vous souhaitez utiliser. Pour les nouveaux projets, nous vous recommandons d'utiliser l'option Jusqu'à la prochaine version majeure.
Xcode résout ensuite vos dépendances de package et les télécharge en arrière-plan. Pour en savoir plus sur l'ajout de dépendances de packages, consultez l'article d'Apple.
Ajouter l'ID application
Vous trouverez votre ID d'application dans l'interface utilisateur d'Ad Manager.
Ajoutez l'ID à votre Info.plist
avec l'extrait de code suivant :
<key>UMPApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>
Obtenir le consentement
Pour recueillir le consentement, procédez comme suit :
- Demande des informations sur le consentement de l'utilisateur les plus récentes.
- Chargez et présentez un formulaire de consentement, si nécessaire.
Demande d'informations sur le consentement
Vous devez demander la mise à jour des informations sur le consentement de l'utilisateur à chaque lancement de l'application, à l'aide de
requestConsentInfoUpdateWithParameters:completionHandler:
. Cette requête vérifie les éléments suivants :
- Indique si le consentement est requis. Par exemple, le consentement est requis pour la première fois ou la décision de consentement précédente a expiré.
- Indique si un point d'entrée pour les options de confidentialité est obligatoire. Certains messages de confidentialité exigent que les applications permettent aux utilisateurs de modifier leurs options de confidentialité à tout moment.
Charger et présenter un formulaire de message de confidentialité si nécessaire
Une fois que vous avez reçu l'état de consentement le plus récent, appelez
loadAndPresentIfRequiredFromViewController:completionHandler:
pour charger les formulaires requis pour recueillir le consentement de l'utilisateur. Une fois le chargement terminé, les formulaires s'affichent immédiatement.
Le code suivant montre comment demander les dernières informations sur le consentement de l'utilisateur. Si nécessaire, le code charge et présente un formulaire de message de confidentialité :
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);
}];
}
}];
Options de confidentialité
Certains formulaires de message de confidentialité sont présentés à partir d'un point d'entrée des options de confidentialité généré par l'éditeur, ce qui permet aux utilisateurs de gérer leurs options de confidentialité à tout moment. Pour en savoir plus sur le message que vos utilisateurs voient au point d'entrée des options de confidentialité, consultez la section Types de messages utilisateur disponibles.
Vérifier si un point d'entrée pour les options de confidentialité est requis
Après avoir appelé
requestConsentInfoUpdateWithParameters:completionHandler:
, vérifiez
UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus
pour déterminer si un point d'entrée des options de confidentialité est requis pour votre application :
Swift
var isPrivacyOptionsRequired: Bool {
return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus == .required
}
Objective-C
- (BOOL)areGDPRConsentMessagesRequired {
return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
UMPPrivacyOptionsRequirementStatusRequired;
}
Ajouter un élément visible à votre application
Si un point d'entrée de confidentialité est requis, ajoutez à votre application un élément d'interface utilisateur visible et interactif qui présente le formulaire d'options de confidentialité. Si un point d'entrée de confidentialité n'est pas requis, configurez votre élément d'interface utilisateur pour qu'il ne soit pas visible ni interactif.
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;
Présenter le formulaire d'options de confidentialité
Lorsque l'utilisateur interagit avec votre élément, présentez le formulaire d'options de confidentialité :
Swift
UMPConsentForm.presentPrivacyOptionsForm(
from: viewController, completionHandler: completionHandler)
Objective-C
[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
completionHandler:completionHandler];
Demander des annonces
Avant de demander des annonces dans votre application, vérifiez si vous avez obtenu le consentement de l'utilisateur à l'aide de
UMPConsentInformation.sharedInstance.canRequestAds
. Il existe deux endroits où vérifier le consentement lors de la collecte :
- Une fois le consentement obtenu dans la session en cours.
- Immédiatement après avoir appelé
requestConsentInfoUpdateWithParameters:completionHandler:
. Il est possible que le consentement ait été obtenu lors de la session précédente. Pour des raisons de latence, nous vous recommandons de ne pas attendre la fin du rappel. Vous pourrez ainsi commencer à charger des annonces dès que possible après le lancement de votre application.
Si une erreur se produit lors du processus de collecte du consentement, vous devez tout de même vérifier si vous pouvez demander des annonces. Le SDK UMP utilise l'état de consentement de la session précédente.
Le code suivant vérifie si vous pouvez demander des annonces lors du processus de collecte du consentement:
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
Le code suivant configure le SDK Interactive Media Ads après avoir recueilli le consentement de l'utilisateur :
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;
}
Tests
Si vous souhaitez tester l'intégration dans votre application pendant le développement, suivez ces étapes pour enregistrer votre appareil de test par programmation. Veillez à supprimer le code qui définit ces ID d'appareils de test avant de publier votre application.
- Appelez
requestConsentInfoUpdateWithParameters:completionHandler:
. Recherchez dans la sortie du journal un message semblable à l'exemple suivant, qui indique votre ID d'appareil et comment l'ajouter en tant qu'appareil de test :
<UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
Copiez l'ID de votre appareil de test dans le presse-papiers.
Modifiez votre code pour appeler
UMPDebugSettings().testDeviceIdentifiers
et transmettre une liste de vos ID d'appareils de test.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){ // ... }];
Forcer une zone géographique
Le SDK UMP permet de tester le comportement de votre application comme si l'appareil était situé dans différentes régions, telles que l'EEE ou le Royaume-Uni, à l'aide de UMPDebugGeography. Notez que les paramètres de débogage ne fonctionnent que sur les appareils de test.
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){
// ...
}];
Réinitialiser l'état du consentement
Lorsque vous testez votre application avec le SDK UMP, il peut être utile de réinitialiser l'état du SDK afin de pouvoir simuler la première expérience d'installation d'un utilisateur.
Pour ce faire, le SDK fournit la méthode reset
.
Swift
UMPConsentInformation.sharedInstance.reset()
Objective-C
[UMPConsentInformation.sharedInstance reset];
Exemples sur GitHub
Pour obtenir un exemple complet de l'intégration du SDK UMP abordée sur cette page, consultez UmpExample en Swift et UmpExample en Objective-C.