Pierwsze kroki z pakietem IMA DAI SDK

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą żądać reklam z dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w aplikacjach. Dzięki pakietom IMA DAI SDK aplikacje wysyłają żądanie strumienia reklamy i treści wideo (VOD lub treści na żywo). Pakiet SDK zwraca następnie połączony strumień wideo, dzięki czemu nie musisz zarządzać przełączaniem się między reklamą a filmem z treściami w aplikacji.

Wybierz interesujące Cię rozwiązanie DAI

Pełna obsługa DAI

Ten przewodnik pokazuje, jak zintegrować pakiet IMA DAI SDK z prostym odtwarzaczem wideo. Jeśli chcesz zobaczyć lub prześledzić przykładową integrację, pobierz z GitHuba plik BasicExample.

Omówienie IMA DAI

Wdrożenie interfejsu IMA DAI wymaga 4 głównych komponentów pakietu SDK, jak opisano w tym przewodniku:

• IMAAdDisplayContainer – obiekt kontenera, który znajduje się nad elementem odtwarzania filmu i zawiera elementy interfejsu reklamy.
• IMAAdsLoader – obiekt, który żąda strumieni i obsługuje zdarzenia wywoływane przez obiekty odpowiedzi żądania strumienia. Należy utworzyć tylko 1 ładowarkę reklam, którą można ponownie wykorzystać w trakcie działania aplikacji.
• IMAStreamRequest – może to być IMAVODStreamRequest lub IMALiveStreamRequest. Obiekt definiujący żądanie strumienia. Żądania strumieni mogą dotyczyć filmów na żądanie lub transmisji na żywo. Żądania zawierają identyfikator treści, a także klucz interfejsu API lub token uwierzytelniający oraz inne parametry.
• IMAStreamManager – obiekt obsługujący strumienie dynamicznego wstawiania reklam i interakcje z systemem backendowym DAI. Menedżer strumienia odpowiada też za pingi śledzenia i przekazuje wydawcy zdarzenia związane z reklamą i strumieniem.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

• Xcode 13 lub nowsza
• CocoaPods (preferowana opcja), menedżer pakietów Swift lub pobrana kopia pakietu IMA DAI SDK na iOS.

Potrzebujesz też parametrów używanych do żądania strumienia z pakietu IMA SDK. Przykłady parametrów żądania znajdziesz w sekcji Przykładowe strumienie.

Tworzenie nowego projektu Xcode

W Xcode utwórz nowy projekt na iOS w języku Objective-C. Jako nazwę projektu użyj ciągu BasicExample.

Dodawanie pakietu IMA DAI SDK do projektu Xcode

Aby zainstalować pakiet IMA DAI SDK, użyj jednej z tych 3 metod.

Zainstaluj pakiet SDK za pomocą CocoaPods (zalecane).

CocoaPods to menedżer zależności dla projektów Xcode i zalecana metoda instalowania pakietu IMA DAI SDK. Więcej informacji o instalowaniu i używaniu CocoaPods znajdziesz w dokumentacji CocoaPods. Po zainstalowaniu CocoaPods wykonaj te instrukcje, aby zainstalować pakiet IMA DAI SDK:

1. W tym samym katalogu, w którym znajduje się plik BasicExample.xcodeproj, utwórz plik tekstowy o nazwie Podfile i dodaj tę konfigurację:

   Podfile
   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14'
   
   target 'BasicExample' do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
   end
   Podfile

2. W katalogu, który zawiera plik Podfile, uruchom:

   pod install --repo-update`

3. Aby sprawdzić, czy instalacja przebiegła pomyślnie, otwórz plik BasicExample.xcworkspace i sprawdź, czy zawiera on 2 projekty: BasicExample i Pods (zależność zainstalowana przez CocoaPods).

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

Pakiet SDK do wyświetlania interaktywnych reklam medialnych obsługuje Swift Package Manager od wersji 3.18.4. Aby zaimportować pakiet Swift, wykonaj te czynności.

1. W Xcode zainstaluj pakiet Swift IMA DAI SDK, wybierając Plik > Dodaj pakiety.

2. W wyświetlonym promptzie wyszukaj repozytorium GitHub pakietu IMA DAI SDK Swift Package:

   https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
   

3. Wybierz wersję pakietu IMA DAI SDK Swift, której chcesz używać. W przypadku nowych projektów zalecamy użycie opcji Aktualizuj do następnej głównej wersji.

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

Ręczne pobieranie i instalowanie pakietu SDK

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

Tworzenie prostego odtwarzacza wideo

W głównym kontrolerze widoku zaimplementuj odtwarzacz wideo, korzystając z odtwarzacza AV ujętego w ramy widoku interfejsu użytkownika. Pakiet IMA SDK używa widoku interfejsu użytkownika do wyświetlania elementów interfejsu reklamy.

#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end
ViewController.m

Inicjowanie ładowarki reklam

Zaimportuj pakiet IMA SDK do kontrolera widoku i zaimplementuj protokoły IMAAdsLoaderDelegate i IMAStreamManagerDelegate, aby obsługiwać zdarzenia ładowarki reklam i menedżera strumienia.

Dodaj te prywatne właściwości, aby przechowywać kluczowe komponenty pakietu IMA SDK:

• IMAAdsLoader – zarządza żądaniami strumieniowania przez cały czas działania aplikacji.
• IMAAdDisplayContainer – odpowiada za wstawianie elementów interfejsu użytkownika reklamy i zarządzanie nimi.
• IMAAVPlayerVideoDisplay – umożliwia komunikację między pakietem IMA SDK a odtwarzaczem multimediów oraz obsługuje otagowane metadanymi treści.
• IMAStreamManager – zarządza odtwarzaniem strumienia i uruchamia zdarzenia związane z reklamami.

Po załadowaniu widoku zainicjuj ładowarkę reklam, kontener wyświetlania reklam i wyświetlanie filmu.

@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}
ViewController.m

Przesyłanie żądania strumienia

Gdy użytkownik naciśnie przycisk odtwarzania, prześlij nowe żądanie strumienia. Użyj klasy IMALiveStreamRequest do transmisji na żywo. W przypadku strumieni VOD użyj klasy IMAVODStreamRequest.

Żądanie strumienia wymaga parametrów strumienia, a także odwołania do kontenera wyświetlania reklamy i wyświetlania filmu.

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  IMAStreamRequest *request;
  // Switch this variable to NO to make a VOD request.
  BOOL useLiveStream = YES;
  if (useLiveStream) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:@"c-rArva4ShKVIAkNfy6HUQ"
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    request = [[IMAVODStreamRequest alloc] initWithContentSourceID:@"2548831"
                                                           videoID:@"tears-of-steel"
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

Nasłuchiwanie zdarzeń wczytywania strumienia

Klasa IMAAdsLoader wywołuje metody IMAAdsLoaderDelegate w przypadku udanej inicjalizacji lub błędu żądania strumienia.

W delegowanej metodzie adsLoadedWithData ustaw zmienną IMAStreamManagerDelegatei zainicjuj menedżera strumienia. Po uruchomieniu menedżer strumienia rozpoczyna odtwarzanie.

W metodzie delegowanej failedWithErrorData zapisz błąd. Opcjonalnie odtwórz strumień zapasowy. Zapoznaj się ze sprawdzonymi metodami dotyczącymi automatycznego wyświetlania reklam.

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}
ViewController.m

Nasłuchiwanie zdarzeń reklamowych

IMAStreamManagerwywołuje metody IMAStreamManagerDelegate, aby przekazywać zdarzenia i błędy strumienia do aplikacji.

W tym przykładzie rejestruj w konsoli podstawowe zdarzenia reklamy:

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"Ad event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %ld/%ld, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %ld, time offset: %lf, max duration: %lf.",
                         (long)event.ad.adPodInfo.adPosition, (long)event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType,
                         (long)event.ad.adPodInfo.podIndex, event.ad.adPodInfo.timeOffset,
                         event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}
ViewController.m

Uruchom aplikację. Jeśli wszystko się powiedzie, możesz poprosić o odtworzenie strumienia Google DAI i odtworzyć go za pomocą pakietu IMA SDK. Więcej informacji o zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach wymienionych w lewym panelu bocznym lub w przykładach na GitHubie.