Konfigurowanie pakietu IMA SDK

Wybierz platformę: HTML5 Android iOS tvOS

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam do dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w aplikacjach. Dzięki pakietom IMA SDK po stronie klienta zachowujesz kontrolę nad odtwarzaniem treści wideo, a pakiet SDK obsługuje odtwarzanie reklam. Reklamy są odtwarzane w osobnym odtwarzaczu wideo umieszczonym nad odtwarzaczem wideo z treściami aplikacji.

Z tego przewodnika dowiesz się, jak zintegrować pakiet IMA SDK z aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć gotowy przykład integracji lub postępować zgodnie z nim, pobierz BasicExample z GitHub.

Omówienie IMA po stronie klienta

Wdrażanie pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK, które są opisane w tym przewodniku:

  • IMAAdDisplayContainer: obiekt kontenera, który określa, gdzie IMA renderuje elementy interfejsu reklamy i mierzy widoczność, w tym Widok aktywnyOpen Measurement.
  • IMAAdsLoader: obiekt, który wysyła żądania reklam i obsługuje zdarzenia z odpowiedzi na żądania reklam. Powinieneś utworzyć tylko jeden moduł wczytywania reklam, którego można używać przez cały okres działania aplikacji.
  • IMAAdsRequest: obiekt, który definiuje żądanie reklamy. Żądania reklam określają adres URL tagu reklamy VAST, a także dodatkowe parametry, takie jak wymiary reklamy.
  • IMAAdsManager: Obiekt, który zawiera odpowiedź na żądanie reklamy, kontroluje odtwarzanie reklam i nasłuchuje zdarzeń reklamowych wywoływanych przez pakiet SDK.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

1. Tworzenie nowego projektu Xcode

W Xcode utwórz nowy projekt iOS w języku Objective-C lub Swift. Użyj nazwy projektu BasicExample.

2. Dodawanie pakietu IMA SDK do projektu w Xcode

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

    Objective-C

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

    Swift

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '12'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
    end
    
    
  2. W katalogu zawierającym plik Podfile uruchom polecenie pod install --repo-update.

  3. Aby sprawdzić, czy instalacja się powiodła, otwórz plik BasicExample.xcworkspace i upewnij się, że zawiera on 2 projekty: BasicExamplePods (zależności zainstalowane 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 SDK IMA Swift, klikając File > Add Package Dependencies... (Plik > Dodaj zależności pakietu...).

  2. W prompcie wyszukaj repozytorium GitHub pakietu IMA SDK na iOS w formacie Swift Package:swift-package-manager-google-interactive-media-ads-ios

  3. Wybierz wersję pakietu IMA SDK Swift Package, której chcesz używać. 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

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

3. Tworzenie odtwarzacza wideo

Najpierw wdróż odtwarzacz wideo. Początkowo ten odtwarzacz nie korzysta z pakietu IMA SDK i nie zawiera żadnej metody wywoływania odtwarzania.

Objective-C

Zaimportuj zależności od odtwarzacza:

#import "ViewController.h"

@import AVFoundation;

Skonfiguruj zmienne odtwarzacza:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;

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

/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;

Uruchom odtwarzacz wideo po wczytaniu widoku:

@implementation ViewController

// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
    @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";

// Ad tag
NSString *const kTestAppAdTagUrl = @"https://pubads.g.doubleclick.net/gampad/ads?"
  @"iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&"
  @"ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&"
  @"correlator=";

- (void)viewDidLoad {
  [super viewDidLoad];

  self.playButton.layer.zPosition = MAXFLOAT;

  [self setupAdsLoader];
  [self setUpContentPlayer];
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

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

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

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

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

Swift

Zaimportuj zależności od odtwarzacza:

import AVFoundation

Skonfiguruj zmienne odtwarzacza:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURL = URL(
    string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!

  private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)

  private lazy var playerLayer: AVPlayerLayer = {
    AVPlayerLayer(player: contentPlayer)
  }()

Uruchom odtwarzacz wideo po wczytaniu widoku:

private lazy var videoView: UIView = {
  let videoView = UIView()
  videoView.translatesAutoresizingMaskIntoConstraints = false
  view.addSubview(videoView)

  NSLayoutConstraint.activate([
    videoView.bottomAnchor.constraint(
      equalTo: view.safeAreaLayoutGuide.bottomAnchor),
    videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
    videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
  ])
  return videoView
}()

// MARK: - View controller lifecycle methods

override func viewDidLoad() {
  super.viewDidLoad()

  videoView.layer.addSublayer(playerLayer)
  adsLoader.delegate = self

  NotificationCenter.default.addObserver(
    self,
    selector: #selector(contentDidFinishPlaying(_:)),
    name: .AVPlayerItemDidPlayToEndTime,
    object: contentPlayer.currentItem)
}

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  playerLayer.frame = videoView.layer.bounds
}

override func viewWillTransition(
  to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
  coordinator.animate { _ in
    // do nothing
  } completion: { _ in
    self.playerLayer.frame = self.videoView.layer.bounds
  }
}

// MARK: - Public methods

func playButtonPressed() {
  requestAds()
}

4. Zaimportuj pakiet IMA SDK

Aby zaimportować pakiet IMA SDK:

Objective-C

  1. Zaimportuj pakiet IMA SDK:

    @import GoogleInteractiveMediaAds;
    
  2. Utwórz zmienne dla klas IMAAdsLoader, IMAAVPlayerContentPlayheadIMAAdsManager używanych w aplikacji:

    // SDK
    /// Entry point for the SDK. Used to make ad requests.
    @property(nonatomic, strong) IMAAdsLoader *adsLoader;
    
    /// Playhead used by the SDK to track content video progress and insert mid-rolls.
    @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;
    
    /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request.
    @property(nonatomic, strong) IMAAdsManager *adsManager;
    

Swift

  1. Zaimportuj pakiet IMA SDK:

    import GoogleInteractiveMediaAds
    
    
  2. Utwórz zmienne dla klas IMAAdsLoader, IMAAVPlayerContentPlayheadIMAAdsManager używanych w aplikacji:

    static let adTagURLString =
      "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
      + "single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&"
      + "gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator="
    
    private let adsLoader = IMAAdsLoader()
    private var adsManager: IMAAdsManager?
    
    private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {
      IMAAVPlayerContentPlayhead(avPlayer: contentPlayer)
    }()
    

5. Wdrożenie narzędzia do śledzenia pozycji odtwarzania treści i obserwatora końca transmisji

Aby odtwarzać reklamy w trakcie filmu, pakiet IMA SDK musi śledzić bieżącą pozycję treści wideo. Aby to zrobić, utwórz klasę, która implementuje interfejs IMAContentPlayhead. Jeśli używasz AVPlayer, jak pokazano w tym przykładzie, pakiet SDK udostępnia klasę IMAAVPlayerContentPlayhead, która wykonuje to za Ciebie. Jeśli nie używasz AVPlayer, musisz zaimplementować IMAContentPlayhead w klasie własnej.

Musisz też poinformować pakiet SDK, kiedy odtwarzanie treści się zakończy, aby mógł wyświetlić reklamy po filmie. W tym celu wywołaj metodę contentComplete w obiekcie IMAAdsLoader, używając AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

Utwórz instancję IMAAVPlayerContentPlayhead w konfiguracji odtwarzacza:

// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:self.contentPlayer.currentItem];

Utwórz metodę contentDidFinishPlaying() do wywołaniaIMAAdsLoader.contentComplete() po zakończeniu odtwarzania treści:

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}

Swift

Utwórz obserwatora zakończenia treści w konfiguracji odtwarzacza:

NotificationCenter.default.addObserver(
  self,
  selector: #selector(contentDidFinishPlaying(_:)),
  name: .AVPlayerItemDidPlayToEndTime,
  object: contentPlayer.currentItem)

Utwórz metodę contentDidFinishPlaying() do wywołaniaIMAAdsLoader.contentComplete() po zakończeniu odtwarzania treści:

@objc func contentDidFinishPlaying(_ notification: Notification) {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if notification.object as? AVPlayerItem == contentPlayer.currentItem {
    adsLoader.contentComplete()
  }
}

6. Zainicjuj moduł wczytywania reklam i wyślij żądanie reklamy

Aby poprosić o zestaw reklam, musisz utworzyć instancję IMAAdsLoader. Ten moduł wczytujący może służyć do przetwarzania obiektów IMAAdsRequest powiązanych z określonym adresem URL tagu reklamy.

Zalecamy utrzymywanie tylko 1 instancji IMAAdsLoader przez cały cykl życia aplikacji. Aby wysłać dodatkowe żądania reklamy, utwórz nowy obiekt IMAAdsRequest, ale użyj tego samego obiektu IMAAdsLoader. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania dotyczące pakietu IMA SDK.

Objective-C

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;
}

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

Swift

private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: PlayerContainerViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}

7. Konfigurowanie delegata modułu wczytywania reklam

Po pomyślnym załadowaniu element IMAAdsLoader wywołuje metodę adsLoadedWithData przypisanego delegata, przekazując mu instancję IMAAdsManager. Następnie możesz zainicjować menedżera reklam, który wczytuje poszczególne reklamy zgodnie z odpowiedzią na adres URL tagu reklamy.

Pamiętaj też, aby obsługiwać wszelkie błędy, które mogą wystąpić podczas wczytywania. Jeśli reklamy się nie ładują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby nie zakłócać wrażeń użytkownika.

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  adsManager = adsLoadedData.adsManager
  adsManager?.delegate = self

  // Create ads rendering settings and tell the SDK to use the in-app browser.
  let adsRenderingSettings = IMAAdsRenderingSettings()
  adsRenderingSettings.linkOpenerPresentingController = self

  // Initialize the ads manager.
  adsManager?.initialize(with: adsRenderingSettings)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  if let message = adErrorData.adError.message {
    print("Error loading ads: \(message)")
  }
  contentPlayer.play()
}

8. Konfigurowanie delegata menedżera reklam

Na koniec, aby zarządzać zdarzeniami i zmianami stanu, menedżer reklam potrzebuje własnego delegata. Interfejs IMAAdManagerDelegate ma metody obsługi zdarzeń i błędów związanych z reklamami, a także metody uruchamiania i wstrzymywania odtwarzania treści wideo.

Rozpocznij odtwarzanie

Nasłuchuj zdarzenia LOADED, aby rozpocząć odtwarzanie treści i reklam. Więcej informacji znajdziesz w sekcji didReceiveAdEvent.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  // When the SDK notifies us the ads have been loaded, play them.
  if event.type == IMAAdEventType.LOADED {
    adsManager.start()
  }
}

Obsługuj błędy

Dodaj też moduł obsługi błędów reklam. Jeśli wystąpi błąd, tak jak w poprzednim kroku, wznow odtwarzanie treści.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Something went wrong with the ads manager after ads were loaded.
  // Log the error and play the content.
  if let message = error.message {
    print("AdsManager error: \(message)")
  }
  contentPlayer.play()
}

Nasłuchiwanie zdarzeń odtwarzania i wstrzymywania

Ostatnie 2 metody delegowania, które musisz zaimplementować, służą do wywoływania zdarzeń odtwarzania i wstrzymywania w bazowych treściach wideo, gdy zażąda tego pakiet IMA SDK. Wstrzymywanie i odtwarzanie na żądanie zapobiega pomijaniu przez użytkownika fragmentów treści wideo podczas wyświetlania reklam.

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // The SDK is going to play ads, so pause the content.
  contentPlayer.pause()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // The SDK is done playing ads (at least for now), so resume the content.
  contentPlayer.play()
}

Znakomicie. Żądania reklam i ich wyświetlanie odbywa się teraz za pomocą pakietu IMA SDK. Więcej informacji o dodatkowych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub przykładach w GitHubie.

Następne kroki

Aby zmaksymalizować przychody z reklam na platformie iOS, poproś o uprawnienia związane z przejrzystością i śledzeniem aplikacji, aby móc korzystać z identyfikatora IDFA.