Rozpocznij

Wymagania wstępne

• Xcode 13 lub nowszy

Z tego przewodnika dowiesz się, jak wywołać pakiet SDK PAL, aby otrzymać liczbę jednorazową i monitorować zdarzenia odtwarzania. Aby skorzystać z gotowego przewodnika, pobierz przykładową aplikację PAL na tvOS.

Dodawanie pakietu SDK PAL do projektu

Instalowanie pakietu SDK PAL za pomocą narzędzia Swift Package Manager

Pakiet SDK biblioteki dostępu programowego obsługuje Swift Package Manager od wersji 2.5.3. Aby zaimportować pakiet Swift, wykonaj te czynności:

1. W Xcode zainstaluj pakiet IMA SDK Swift, klikając File > Add Packages... (Plik > Dodaj pakiety...).

2. W wyświetlonym oknie wyszukaj repozytorium pakietu IMA SDK Swift Package w GitHubie:

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

3. Wybierz wersję pakietu PAL SDK Swift Package, której chcesz użyć. W przypadku nowych projektów zalecamy używanie opcji Do następnej wersji głównej.

Gdy skończysz, Xcode przetworzy zależności pakietu i pobierze je w tle. Więcej informacji o dodawaniu zależności pakietów znajdziesz w artykule Apple.

Ręczne pobieranie i instalowanie pakietu SDK PAL

Jeśli nie chcesz używać narzędzia Swift Package Manager, możesz pobrać pakiet PAL SDK i ręcznie dodać go do projektu.

1. Pobierz i rozpakuj pakiet SDK PAL na tvOS.
2. Aby włączyć platformę do projektu, postępuj zgodnie z przewodnikiem dla programistów Apple.

Wygeneruj nonce

„Nonce” to pojedynczy zaszyfrowany ciąg znaków wygenerowany przez PAL za pomocą funkcji PALNonceLoader. Pakiet SDK PAL wymaga, aby każdemu nowemu żądaniu strumienia towarzyszyła nowo wygenerowana liczba jednorazowa. Jednak wartości nonce mogą być ponownie używane w wielu żądaniach reklam w ramach tego samego strumienia.

Wszystkie poniższe fragmenty kodu to modyfikacje pliku ViewController.m w przykładowej aplikacji PAL tvOS.

Aby poprosić o wartość nonce, zacznij od zaimportowania biblioteki PAL:

@import ProgrammaticAccessLibrary;

Uwaga: zalecamy utworzenie tylko 1 instancji klasy PALNonceLoader na sesję użytkownika w aplikacji, chyba że aplikacja ma wiele stron lub równoważnych konstrukcji. Dzięki temu korelator strony lub parametr &correlator pozostaje niezmieniony przez cały okres istnienia strony lub sesji użytkownika w aplikacji.

Nadal masz kontrolę nad korelatorem strumienia, czyli &scor, który należy zresetować raz dla każdego nowego strumienia. Wszystkie żądania reklam w tym samym strumieniu powinny mieć tę samą wartość parametru PALNonceLoader i wartość korelatora strumienia, aby funkcje ograniczenia liczby wyświetleń i wykluczeń konkurencji działały prawidłowo.

Następnie utwórz instancję klasy PALNonceLoader i dodaj szablony 2 metod delegowania:

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

Następnie zainicjuj żądanie nonce, wypełnij jego właściwości i użyj go do zainicjowania menedżera nonce:

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

Na koniec wypełnij delegaty modułu wczytywania nonce, aby rejestrować wygenerowane wartości nonce:

#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);
}

Podczas wykonywania bezpośredniego wywołania VAST (DVC) ustaw wartość parametru givn jako wartość nonce. Liczba jednorazowa jest bezpieczna w adresach URL, więc nie trzeba jej kodować w adresie URL.

Uwaga: jeśli wcześniej przesłano liczbę jednorazową za pomocą parametru paln, zdecydowanie zalecamy przejście na parametr givn i zaprzestanie wysyłania parametru paln. Jeśli oba parametry są uwzględnione, nie wiadomo, która liczba jednorazowa zostanie użyta.

Jeśli wysyłasz żądania reklam do Google i je renderujesz, musisz renderować ikonę i nakładkę AdChoices. Szczegółowe informacje o analizowaniu odpowiedzi VAST i renderowaniu ikon znajdziesz w sekcji Ikona Informacja i nakładka.

Na koniec musisz dodać metody obsługi wysyłania do pakietu SDK informacji o sesji odtwarzania treści i kliknięć. Poniżej znajdziesz przykład implementacji metod sendPlaybackStart, sendPlaybackEnd i sendAdClick:

...

// 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];
}

W swojej implementacji wywołuj funkcję sendPlaybackStart w momencie „rozpoczęcia odtwarzania filmu”, gdy odtwarzanie rozpoczyna się po raz pierwszy w odpowiedzi na działanie zainicjowane przez użytkownika (kliknięcie w celu odtworzenia) lub działanie zainicjowane przez aplikację (autoodtwarzanie). Funkcję sendPlaybackEnd wywołuj po zakończeniu odtwarzania, a funkcję sendAdClick – za każdym razem, gdy widz kliknie reklamę.

(Opcjonalnie) Wysyłanie sygnałów Google Ad Managera przez serwery reklamowe firm zewnętrznych

Skonfiguruj żądanie serwera reklam innej firmy wysyłane do Ad Managera. Po wykonaniu tych czynności parametr nonce będzie przekazywany z pakietu PAL SDK przez serwery pośredniczące do Google Ad Managera. Umożliwia to lepsze zarabianie dzięki Google Ad Managerowi.

Uwaga: jeśli używasz kilku rozwiązań innych firm, np. serwera SSAI firmy zewnętrznej, który wywołuje inny serwer reklamowy firmy zewnętrznej, musisz dopilnować, aby zaszyfrowana liczba jednorazowa z pakietu PAL SDK była przekazywana do każdej firmy zewnętrznej.

Skonfiguruj serwer reklamowy firmy zewnętrznej tak, aby w żądaniu wysyłanym do Ad Managera uwzględniał wartość nonce. Oto przykład tagu reklamy skonfigurowanego na serwerze reklamowym firmy zewnętrznej:

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

Więcej informacji znajdziesz w przewodniku po implementacji po stronie serwera w Google Ad Managerze.

Ad Manager szuka znaku givn=, aby zidentyfikować wartość nonce. Serwer reklamowy firmy zewnętrznej musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastąpić je parametrem zapytania nonce podanym w poprzednim kroku. Więcej informacji o tym, jak to zrobić, znajdziesz w dokumentacji serwera reklam firmy zewnętrznej.