Erste Schritte

Voraussetzungen

• Xcode 13 oder höher.

In dieser Anleitung wird beschrieben, wie Sie das PAL SDK aufrufen, um eine Nonce zu empfangen und Wiedergabeereignisse zu überwachen. Wenn Sie eine Beispiel-App sehen möchten, die PAL zum Generieren einer Nonce verwendet, laden Sie das iOS-Beispiel von GitHub herunter.

PAL SDK zum Projekt hinzufügen

PAL SDK mit dem Swift Package Manager installieren

Das Programmatic Access Library SDK unterstützt den Swift Package Manager ab Version 2.5.3. Führen Sie die folgenden Schritte aus, um das Swift-Paket zu importieren.

1. Installieren Sie in Xcode das Swift-Paket des IMA SDK. Gehen Sie dazu zu File > Add Packages... (Datei > Pakete hinzufügen...).

2. Suchen Sie in der angezeigten Eingabeaufforderung nach dem GitHub-Repository für das IMA SDK Swift Package:

   https://github.com/googleads/swift-package-manager-google-programmatic-access-library-ios
   

3. Wählen Sie die Version des PAL SDK Swift Package aus, das Sie verwenden möchten. Für neue Projekte empfehlen wir die Verwendung der Nächsten Hauptversion.

Sobald Sie fertig sind, löst Xcode die Paketabhängigkeiten auf und lädt sie im Hintergrund herunter. Weitere Informationen zum Hinzufügen von Paketabhängigkeiten finden Sie im Apple-Artikel.

PAL SDK manuell herunterladen und installieren

Wenn Sie Swift Package Manager nicht verwenden möchten, können Sie das PAL SDK herunterladen und Ihrem Projekt manuell hinzufügen.

1. Laden Sie das PAL SDK for iOS herunter und extrahieren Sie es.
2. Folgen Sie dem Apple Developer Guide, um das Framework in Ihr Projekt zu integrieren.

Nonce generieren

Eine „Nonce“ ist ein einzelner verschlüsselter String, der von PAL mit PALNonceLoader generiert wird. Das PAL SDK erfordert, dass jeder neue Stream von einer neu generierten Nonce begleitet wird. Nonces können jedoch für mehrere Anzeigenanfragen im selben Stream wiederverwendet werden.

Alle folgenden Code-Snippets sind Änderungen an ViewController.m in der PAL iOS-Beispielanwendung.

Importieren Sie zum Anfordern einer Nonce zuerst die PAL-Bibliothek:

@import ProgrammaticAccessLibrary;

Hinweis :Es empfiehlt sich, für jede Nutzersitzung in der Anwendung nur eine Instanz der PALNonceLoader-Klasse zu erstellen, es sei denn, die Anwendung hat mehrere Seiten oder gleichwertige Konstrukte. Dadurch bleibt der Seitenkorrelator oder Parameter &correlator für die Lebensdauer einer Seite oder die Nutzersitzung der App unverändert.

Sie haben weiterhin die Kontrolle über den Streamkorrelator oder &scor, der für jeden neuen Stream einmal zurückgesetzt werden sollte. Alle Anzeigenanfragen desselben Streams sollten denselben PALNonceLoader- und Streamkorrelatorwert haben, damit das Frequency Capping und die Konkurrenzausschlussfunktionen ordnungsgemäß funktionieren.

Erstellen Sie als Nächstes eine Instanz von PALNonceLoader und fügen Sie Stubs für die beiden Delegationsmethoden hinzu:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void) viewDidLoad {
  [super viewDidLoad];
  // The default value for 'allowStorage' and 'directedForChildOrUnknownAge' is
  // 'NO', but should be updated once the appropriate consent has been gathered.
  // Publishers should either integrate with a CMP or use a different method to
  // handle storage consent.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.allowStorage = YES;
  settings.directedForChildOrUnknownAge = NO;

  self.nonceLoader = [[PALNonceLoader alloc] initWithSettings:settings];
  self.nonceLoader.delegate = self;
}

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
}

Initiieren Sie dann eine Nonce-Anfrage, geben Sie ihre Eigenschaften ein und initialisieren Sie damit einen Nonce-Manager:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The nonce manager result from the last successful nonce request.
@property(nonatomic) PALNonceManager *nonceManager;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void)viewDidLoad {
  ...
  self.nonceLoader.delegate = self;
  [self requestNonceManager];
}
...
#pragma mark - UI Callback methods

/**
 * Requests a new nonce manager with a request containing arbitrary test values
 * like a user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 */
- (void)requestNonceManager {
  PALNonceRequest *request = [[PALNonceRequest alloc] init];
  request.continuousPlayback = PALFlagOff;
  request.descriptionURL = [NSURL URLWithString:@"https://example.com/desc?key=val"];
  request.iconsSupported = YES;
  request.playerType = @"AwesomePlayer";
  request.playerVersion = @"4.2.1";
  request.PPID = @"123987456";
  request.sessionID = @"Sample SID";
  // Sample API framework integer. See reference docs for more details.
  NSInteger SampleAPIFramework = 501;
  request.supportedApiFrameworks = [NSMutableSet setWithArray:@[ SampleAPIFramework ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;
  request.OMIDPartnerName = @"SamplePartner";
  request.OMIDPartnerVersion = @"6.2.1";
  request.OMIDVersion = @"1.2.3";

  if (self.nonceManager) {
    // Detach the old nonce manager's gesture recognizer before destroying it.
    [self.videoView removeGestureRecognizer:self.nonceManager.gestureRecognizer];
    self.nonceManager = nil;
  }
  [self.nonceLoader loadNonceManagerWithRequest:request];
}

Füllen Sie schließlich die Delegierung für das Nonce-Ladeprogramm aus, um generierte Nonces zu protokollieren:

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
  NSLog(@"Programmatic access nonce: %@", nonceManager.nonce);
  // Capture the created nonce manager and attach its gesture recognizer to the video view.
  self.nonceManager = nonceManager;
  [self.videoView addGestureRecognizer:self.nonceManager.gestureRecognizer];
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
  NSLog(@"Error generating programmatic access nonce: %@", error);
}

Legen Sie beim direkten VAST-Aufruf (DVC) Ihre Nonce als Wert für den Parameter givn fest. Die Nonce ist URL-sicher und muss nicht URL-codiert werden.

Achtung: Wenn Sie zuvor mit dem Parameter paln eine Nonce angegeben haben, wird dringend empfohlen, zu givn zu migrieren und paln nicht mehr zu senden. Wenn beide Parameter enthalten sind, ist das Verhalten undefiniert dazu, welche Nonce verwendet wird.

Schließlich müssen Sie Methoden hinzufügen, um das Senden von Sitzungsinformationen zur Wiedergabe von Inhalten und Klicks an das SDK zu verarbeiten. Das folgende Beispiel zeigt, wie die Methoden sendPlaybackStart, sendPlaybackEnd und sendAdClick implementiert werden:

...
// Reports the start of playback for the current content session.
- (void)sendPlaybackStart {
  [self.nonceManager sendPlaybackStart];
}

// Reports the end of playback for the current content session.
- (void)sendPlaybackEnd {
  [self.nonceManager sendPlaybackEnd];
}

// Reports an ad click for the current nonce manager, if not nil.
- (void)sendAdClick {
  [self.nonceManager sendAdClick];
}

In Ihrer Implementierung sollte sendPlaybackStart beim Start des Videoplayers zum ersten Mal aufgerufen werden, entweder als Reaktion auf eine vom Nutzer initiierte Aktion (Click-to-Play) oder eine von der App initiierte Aktion (Autoplay). sendPlaybackEnd sollte aufgerufen werden, wenn die Wiedergabe endet, und sendAdClick sollte jedes Mal aufgerufen werden, wenn der Nutzer auf eine Anzeige klickt.

Optional: Google Ad Manager-Signale über Ad-Server eines Drittanbieters senden

Konfigurieren Sie die Anfrage des Ad-Servers eines Drittanbieters für Ad Manager. Nachdem Sie die folgenden Schritte ausgeführt haben, wird der nonce-Parameter vom PAL SDK über Ihre Zwischenserver und anschließend an Google Ad Manager weitergegeben. Dies ermöglicht eine bessere Monetarisierung über Google Ad Manager.

Hinweis: Wenn Sie mehrere Drittanbieterlösungen verwenden, z. B. wenn ein Drittanbieter-SSAI-Server einen anderen Ad-Server eines Drittanbieters aufruft, müssen Sie dafür sorgen, dass die verschlüsselte Nonce des PAL SDK an jeden Drittanbieter weitergeleitet wird.

Konfigurieren Sie den Ad-Server eines Drittanbieters so, dass die Nonce in die Serveranfrage an Ad Manager aufgenommen wird. Hier sehen Sie ein Beispiel für ein Anzeigen-Tag, das im Ad-Server eines Drittanbieters konfiguriert wird:

https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...

Weitere Informationen finden Sie im Google Ad Manager-Leitfaden zur serverseitigen Implementierung.

In Ad Manager wird nach givn= gesucht, um den Nonce-Wert zu ermitteln. Der Ad-Server des Drittanbieters muss ein eigenes Makro unterstützen, z. B. %%custom_key_for_google_nonce%%, und durch den Nonce-Abfrageparameter ersetzen, den Sie im vorherigen Schritt angegeben haben. Weitere Informationen dazu finden Sie in der Dokumentation des Ad-Servers des Drittanbieters.