Jetzt starten

Vorbereitung

• Xcode 13 oder höher

In diesem Leitfaden wird beschrieben, wie Sie das PAL SDK aufrufen, um eine Nonce zu erhalten und Wiedergabeereignisse zu überwachen. Wenn Sie die Anleitung nachvollziehen möchten, laden Sie die PAL tvOS-Beispielanwendung herunter.

PAL SDK in Ihr Projekt einbinden

PAL SDK mit Swift Package Manager installieren

Das Programmatic Access Library SDK unterstützt ab Version 2.5.3 den Swift Package Manager. Folgen Sie der Anleitung unten, um das Swift-Paket zu importieren.

1. Installieren Sie in Xcode das IMA SDK Swift-Paket, indem Sie zu File > Add Packages... gehen.

2. Suchen Sie im angezeigten Prompt nach dem GitHub-Repository für das IMA SDK Swift Package:

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

3. Wählen Sie die Version des PAL SDK Swift-Pakets aus, die Sie verwenden möchten. Für neue Projekte empfehlen wir die Verwendung von Up to Next Major Version.

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

PAL SDK manuell herunterladen und installieren

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

1. Laden Sie das PAL SDK für tvOS herunter und entpacken Sie es.
2. Folgen Sie dem Apple Developer Guide, um das Framework in Ihr Projekt einzubinden.

Nonce generieren

Eine „Nonce“ ist ein einzelner verschlüsselter String, der von PAL mit dem PALNonceLoader generiert wird. Für jede neue Streamanfrage im PAL SDK muss eine neu generierte Nonce angegeben werden. Nonces können jedoch für mehrere Anzeigenanfragen innerhalb desselben Streams wiederverwendet werden.

Alle Code-Snippets unten sind Änderungen an ViewController.m in der PAL-Beispielanwendung für tvOS.

Wenn Sie eine Einmal-ID anfordern möchten, müssen Sie zuerst die PAL-Bibliothek importieren:

@import ProgrammaticAccessLibrary;

Hinweis :Wir empfehlen, für jede Nutzersitzung in Ihrer App nur eine Instanz der Klasse PALNonceLoader zu erstellen, es sei denn, Ihre App hat mehrere Seiten oder ähnliche Konstrukte. So bleibt der Seitenkorrelator oder &correlator-Parameter für die gesamte Lebensdauer einer Seite oder die Sitzung eines Nutzers in der App unverändert.

Sie haben weiterhin die Kontrolle über den Stream-Korrelator oder &scor, der für jeden neuen Stream einmal zurückgesetzt werden sollte. Alle Anzeigenanfragen desselben Streams sollten denselben PALNonceLoader- und Stream-Korrelatorwert haben, damit Frequency Capping und Konkurrenzausschlüsse richtig funktionieren.

Erstellen Sie als Nächstes eine Instanz von PALNonceLoader und fügen Sie Stubs für die beiden Delegatmethoden 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 'directedForChildOrUnknownAge' is
  // 'NO'. Update the value after the appropriate consent has been gathered.
  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `PALSettings.forceLimitedAds` property.
  PALSettings *settings = [[PALSettings alloc] init];
  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 {
}

Stellen Sie dann eine Nonce-Anfrage, füllen Sie die zugehörigen Properties aus und verwenden Sie sie, um einen Nonce-Manager zu initialisieren:

@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 (sane) user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 *
 * The PALNonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
- (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 integers. See reference docs for more details.
  request.supportedAPIFrameworks = [NSMutableSet setWithArray:@[ @2, @7, @9 ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;

  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 Delegaten des Nonce-Loaders 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 bei Ihrem direkten VAST-Aufruf (DVC) die Einmal-ID als Wert für den Parameter givn fest. Die Nonce ist URL‑sicher und muss nicht URL‑codiert werden.

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

Schließlich müssen Sie Methoden zum Senden von Informationen zur Wiedergabesitzung und Klicks an das SDK hinzufügen. Im folgenden Beispiel werden die Methoden sendPlaybackStart, sendPlaybackEnd und sendAdClick implementiert:

...

// 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 aufgerufen werden, wenn die Wiedergabe zum ersten Mal beginnt, entweder als Reaktion auf eine vom Nutzer initiierte Aktion (Click-to-Play) oder eine von der App initiierte Aktion (automatische Wiedergabe). sendPlaybackEnd sollte aufgerufen werden, wenn die Wiedergabe endet, und sendAdClick jedes Mal, wenn der Zuschauer auf eine Anzeige klickt.

(Optional) Google Ad Manager-Signale über Ad-Server von Drittanbietern senden

Konfigurieren Sie die Anfrage des Drittanbieter-Ad-Servers für Ad Manager. Nachdem Sie die folgenden Schritte ausgeführt haben, wird der Nonce-Parameter vom PAL SDK über Ihre Vermittlungsserver an Google Ad Manager weitergegeben. So lässt sich die Monetarisierung über Google Ad Manager verbessern.

Hinweis :Wenn Sie mehrere Drittanbieterlösungen verwenden, z. B. einen Drittanbieter-SSAI-Server, der einen anderen Drittanbieter-Ad-Server 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 der Serveranfrage an Ad Manager enthalten ist. Hier sehen Sie ein Beispiel für ein Anzeigen-Tag, das auf dem Ad-Server eines Drittanbieters konfiguriert wurde:

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

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

In Ad Manager wird nach givn= gesucht, um den Nonce-Wert zu ermitteln. Der Ad‑Server des Drittanbieters muss ein eigenes Makro wie %%custom_key_for_google_nonce%% unterstützen und es 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.