Rozpocznij

Wymagania wstępne

• Xcode 13 lub nowsza

W tym przewodniku opisano, jak wywoływać pakiet SDK PAL w celu otrzymania liczby jednorazowej i monitorowania zdarzeń odtwarzania. Aby przeczytać cały przewodnik, pobierz przykładową aplikację PAL tvOS.

Dodaj do projektu pakiet SDK PAL

Instalowanie pakietu PAL SDK za pomocą menedżera pakietów Swift

Pakiet SDK biblioteki dostępu zautomatyzowanego obsługuje Menedżera pakietów Swift od wersji 2.5.3. Aby zaimportować pakiet Swift, wykonaj poniższe czynności.

1. Zainstaluj w Xcode pakiet IMA SDK Swift, klikając Plik > Dodaj pakiety...

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

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

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

Gdy skończysz, Xcode rozstrzygnie zależności pakietów 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 PAL SDK

Jeśli nie chcesz używać Menedżera pakietów Swift, możesz pobrać pakiet SDK PAL i ręcznie dodać go do projektu.

1. Pobierz i wyodrębnij pakiet PAL SDK na iOS.
2. Aby wdrożyć platformę w swoim projekcie, postępuj zgodnie z przewodnikiem Apple dla programistów.

Generowanie liczby jednorazowej

Element „nonce” to pojedynczy zaszyfrowany ciąg znaków wygenerowany przez platformę PAL za pomocą metody PALNonceLoader. Pakiet PAL SDK wymaga, aby każde nowe żądanie strumienia prowadziło do nowo wygenerowanej liczby jednorazowej. Jednorazowych liczb można jednak używać na potrzeby wielu żądań reklamy w tym samym strumieniu.

Wszystkie podane niżej fragmenty kodu to modyfikacje ViewController.m w przykładowej aplikacji PAL tvOS.

Aby zażądać liczby jednorazowej, zacznij od zaimportowania biblioteki PAL:

@import ProgrammaticAccessLibrary;

Uwaga: zalecamy utworzenie tylko jednego wystąpienia klasy PALNonceLoader na każdą sesję użytkownika w aplikacji, chyba że aplikacja ma wiele stron lub równoważne konstrukcje. Dzięki temu korelator strony (parametr &correlator) pozostaje niezmieniony przez cały czas istnienia strony lub sesji aplikacji przez użytkownika.

Nadal masz kontrolę nad korelatorem strumienia (&scor), który należy zresetować raz przy każdym nowym strumieniu. Aby funkcje ograniczania liczby wyświetleń i wykluczania konkurencji działały prawidłowo, wszystkie żądania reklam z tego samego strumienia powinny mieć tę samą wartość parametru PALNonceLoader i korelatora strumienia.

Następnie utwórz wystąpienie obiektu PALNonceLoader i dodaj do niego kreski dla 2 metod przekazywania dostępu:

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

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

@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.
 */
- (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;

  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 uzupełnij delegacje wczytujące jednorazowe, aby rejestrować wygenerowane liczby jednorazowe:

#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 bezpośredniego wywołania VAST (DVC) ustaw liczbę jednorazową jako wartość parametru givn. Liczba jednorazowa jest bezpieczna dla adresu URL – nie musisz jej kodować w adresie URL.

Uwaga: jeśli liczba jednorazowa była wcześniej podana za pomocą parametru paln, zdecydowanie zalecamy przejście na givn i zaprzestanie wysyłania paln. Jeśli użyjesz obu parametrów, nie będzie można określić, która z nich zostanie użyta.

Na koniec musisz dodać metody obsługi wysyłania do pakietu SDK informacji o sesji odtwarzania treści i kliknięć. Zapoznaj się z przykładem 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 Twojej implementacji element sendPlaybackStart powinien być wywoływany przy „uruchamianiu odtwarzacza wideo”, ponieważ odtwarzanie rozpoczyna się po raz pierwszy w odpowiedzi na działanie inicjowane przez użytkownika (kliknij, aby odtworzyć) lub działanie w aplikacji (autoodtwarzanie), sendPlaybackEnd – po zakończeniu odtwarzania, a metodę sendAdClick – za każdym razem, gdy użytkownik kliknie reklamę.

(Opcjonalnie) Wysyłanie sygnałów do Google Ad Managera za pomocą serwerów reklamowych firm zewnętrznych

Skonfiguruj żądanie serwera reklamowego firmy zewnętrznej na potrzeby Ad Managera. Gdy wykonasz podane niżej czynności, parametr jednorazowy zostanie przekazany z pakietu PAL SDK przez serwery pośrednie, a następnie do Google Ad Managera. Umożliwia to zwiększanie przychodów dzięki usłudze Google Ad Manager.

Uwaga: jeśli korzystasz z wielu rozwiązań innych firm, np. z serwera SSAI innej firmy wywołującego inny serwer reklamowy firmy zewnętrznej, musisz się upewnić, że zaszyfrowana liczba jednorazowa z pakietu PAL SDK jest przekazywana do każdej firmy zewnętrznej.

Skonfiguruj serwer reklamowy firmy zewnętrznej tak, by uwzględniał liczbę jednorazową w żądaniu serwera wysyłanym do Ad Managera. 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 Google Ad Managera.

Ad Manager wyszukuje wartość givn=, aby zidentyfikować wartość jednorazową. Zewnętrzny serwer reklamowy musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastąpić je parametrem zapytania jednorazowym podanym w poprzednim kroku. Więcej informacji na ten temat można znaleźć w dokumentacji serwera reklamowego firmy zewnętrznej.