Rozpocznij

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą żądania reklam z Serwer reklam zgodny i zarządzanie odtwarzaniem reklam w aplikacjach. W przypadku pakietów IMA SDK po stronie klienta Ty kontrolujesz odtwarzanie treści wideo, a pakiet SDK obsługuje odtwarzanie reklam. Reklamy są wyświetlane w osobnego odtwarzacza wideo umieszczonego nad odtwarzaczem wideo treści w aplikacji.

Ten przewodnik pokazuje, jak zintegrować pakiet IMA SDK z prostym odtwarzaczem wideo aplikacji. Jeśli chcesz zobaczyć gotowy fragment lub zapoznać się z nim należy pobrać BasicExample od GitHub.

Przegląd po stronie klienta IMA

Implementacja IMA po stronie klienta obejmuje cztery główne komponenty pakietu SDK: w tym przewodniku:

• IMAAdDisplayContainer: Obiekt kontenera, w którym są renderowane reklamy.
• IMAAdsLoader: Obiekt, który wysyła żądania reklam i obsługuje zdarzenia z odpowiedzi na żądania reklam. Należy tylko Utworzenie jednego programu wczytującego reklamy, którego można używać wielokrotnie w całej aplikacji.
• IMAAdsRequest: Obiekt definiujący żądanie reklamy. Żądania reklam określają URL tagu reklamy VAST oraz dodatkowych parametrów, takich jak wymiary reklam.
• IMAAdsManager: obiekt zawierający odpowiedź na żądanie reklamy, steruje odtwarzaniem i nasłuchuje reklamy. zdarzeń wywoływanych przez pakiet SDK.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

• Xcode 13 lub nowsza wersja
• CocoaPods (preferowane), Menedżer pakietów Swift lub pobranej kopii IMA SDK na iOS

1. Utwórz nowy projekt Xcode

Utwórz w Xcode nowy projekt iOS w języku Objective-C lub Swift. Używaj BasicExample jako nazwę projektu.

2. Dodawanie pakietu IMA SDK do projektu Xcode

Zainstaluj pakiet SDK za pomocą CocoaPods (zalecane)

CocoaPods to menedżer zależności w projektach Xcode i jest zalecany . Więcej informacji o instalowaniu i używaniu Więcej informacji na ten temat znajdziesz w dokumentacji CocoaPods. Gdy już masz zainstalowane CocoaPods, wykonaj te instrukcje, aby zainstalować pakiet IMA SDK:

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

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

2. W katalogu zawierającym plik Podfile uruchom pod install --repo-update

3. Sprawdź, czy instalacja się powiodła, otwierając BasicExample.xcworkspace i sprawdź, czy zawiera on 2 projekty: BasicExample i Pody (zależności zainstalowane przez CocoaPods).

Zainstaluj pakiet SDK za pomocą menedżera pakietów Swift

Pakiet Interactive Media Ads SDK obsługuje pakiet Swift Menedżera od wersji 3.18.4. Postępuj zgodnie z poniższe czynności, aby zaimportować pakiet Swift.

1. Zainstaluj w Xcode pakiet IMA SDK Swift. W tym celu przejdź na stronę Plik > Dodaj pakiety...

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

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

3. Wybierz wersję pakietu IMA SDK Swift, którego chcesz użyć. W przypadku nowych projektów zalecamy używanie wersji aż do następnej wersji głównej.

Gdy skończysz, Xcode rozstrzygnie zależności pakietów pobiera je w tle. Więcej informacji o dodawaniu pakietu zależności, zobacz Artykuł Apple

Ręczne pobieranie i instalowanie pakietu SDK

Jeśli nie chcesz korzystać z Menedżera pakietów Swift ani CocoaPods, możesz pobrać pakiet IMA SDK ręcznie dodać ją do projektu.

3. Utwórz prosty odtwarzacz wideo

Najpierw zaimplementuj podstawowy odtwarzacz wideo. Początkowo odtwarzacz nie używa IMA SDK i nie zawiera jeszcze żadnej metody wyzwalania odtwarzania.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

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

- (void)setupContentPlayer {
  // Create a content video player.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

// Add the content video player as a child view controller.
- (void)showContentPlayer {
  [self addChildViewController:self.contentPlayerViewController];
  self.contentPlayerViewController.view.frame = self.view.bounds;
  [self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
  [self.contentPlayerViewController didMoveToParentViewController:self];
}

// Remove and detach the content video player.
- (void)hideContentPlayer {
  // The whole controller needs to be detached so that it doesn't capture events from the remote.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

@end
      

import AVFoundation
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var playerViewController: AVPlayerViewController!

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black
    setUpContentPlayer()
  }

  func setUpContentPlayer() {
    // Load AVPlayer with path to your content.
    let contentURL = URL(string: ViewController.ContentURLString)
    let player = AVPlayer(url: contentURL)
    playerViewController = AVPlayerViewController()
    playerViewController.player = player

    showContentPlayer()
  }

  func showContentPlayer() {
    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent:self)
  }

  func hideContentPlayer() {
    // The whole controller needs to be detached so that it doesn't capture
    // events from the remote.
    playerViewController.willMove(toParent:nil)
    playerViewController.view.removeFromSuperview()
    playerViewController.removeFromParent()
  }
}
      

4. Importowanie pakietu IMA SDK

Następnie dodaj platformę IMA, używając instrukcji importu poniżej istniejącej importowanie danych.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
      

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
      

5. Wdrożenie śledzenia suwaka odtwarzania treści oraz funkcji obserwacji zakończenia transmisji

Aby odtwarzać reklamy w trakcie filmu, pakiet IMA SDK musi śledzić bieżącą pozycję reklamy. Twoich treści wideo. Aby to zrobić, utwórz klasę, która implementuje IMAContentPlayhead Jeśli tak jak w tym przykładzie używasz AVPlayer, pakiet SDK udostępnia klasę IMAAVPlayerContentPlayhead, która robi to za Ciebie. Jeśli nie korzystasz z tagu AVPlayer, musisz zaimplementować IMAContentPlayhead w domenie do Twoich własnych zajęć.

Musisz też powiadomić pakiet SDK o zakończeniu odtwarzania treści, aby mógł wyświetlania reklam po filmie. Aby to zrobić, wywołaj contentComplete na IMAAdsLoader przy użyciu: AVPlayerItemDidPlayToEndTimeNotification.

ViewController.m

...

@interface ViewController ()
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

...

- (void)setupContentPlayer {
  // Create a content video player.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;
  self.contentPlayhead =
      [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];

  // Track end of content.
  AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
  [NSNotificationCenter.defaultCenter addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:contentPlayerItem];

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {}

- (void)dealloc {
  [NSNotificationCenter.defaultCenter removeObserver:self];
}

@end
      

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

...

  func setUpContentPlayer() {
    // Load AVPlayer with path to your content.
    let contentURL! = URL(string: ViewController.ContentURLString)
    let player = AVPlayer(url: contentURL)
    playerViewController = AVPlayerViewController()
    playerViewController.player = player

    // Set up your content playhead and contentComplete callback.
    contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
    NotificationCenter.default.addObserver(
      self,
      selector: #selector(ViewController.contentDidFinishPlaying(_:)),
      name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
      object: player.currentItem)

    showContentPlayer()
  }

...

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    adsLoader.contentComplete()
  }
}
      

6. Zainicjuj program wczytujący reklamy i wyślij żądanie reklamy

Aby zażądać zestawu reklam, musisz utworzyć wystąpienie IMAAdsLoader. Można go użyć do przetworzenia obiektów IMAAdsRequest powiązanych z adresu URL określonego tagu reklamy.

Zalecamy przechowywanie tylko jednego wystąpienia instancji IMAAdsLoader przez cały okres cyklu życia aplikacji. Aby wysyłać dodatkowe żądania reklamy, utwórz nowe IMAAdsRequest, ale użyj ponownie tego samego obiektu IMAAdsLoader. Więcej przeczytaj Najczęstsze pytania na temat pakietu IMA SDK.

ViewController.m

...

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString = @"https://pubads.g.doubleclick.net/gampad/ads?"
    @"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
    @"cust_params=sample_ar%3Dpremidpostlongpod&"
    @"ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&"
    @"env=vp&impl=s&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

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

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestAds];
}

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
}

- (void)requestAds {
  // Pass the main view as the container for ad display.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view];
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

...

@end
      

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
  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&impl=s&correlator="

  var adsLoader: IMAAdsLoader!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black
    setUpContentPlayer()
    setUpAdsLoader()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    requestAds()
  }

...

  func setUpAdsLoader() {
    adsLoader = IMAAdsLoader(settings: nil)
  }

  func requestAds() {
    // Create ad display container for ad rendering.
    let adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view)
    // Create an ad request with our ad tag, display container, and optional user context.
    let request = IMAAdsRequest(
        adTagUrl: ViewController.AdTagURLString,
        adDisplayContainer: adDisplayContainer,
        contentPlayhead: contentPlayhead,
        userContext: nil)

    adsLoader.requestAds(with: request)
  }

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    adsLoader.contentComplete()
  }
}
      

7. Konfigurowanie przedstawiciela wczytywania reklam

Po udanym zdarzeniu wczytywania IMAAdsLoader wywołuje metodę adsLoadedWithData. przypisanego przedstawiciela, przekazując do niego instancję IMAAdsManager. Ty może następnie zainicjować menedżera reklam, który wczytuje poszczególne reklamy, zgodnie z definicją przez odpowiedź na adres URL tagu reklamy.

Ponadto pamiętaj o usunięciu wszelkich błędów, które mogą wystąpić podczas wczytywania proces tworzenia konta. Jeśli reklamy nie są wczytywane, upewnij się, że odtwarzanie multimediów jest kontynuowane, bez reklam, aby nie zakłócać wrażeń użytkownika.

ViewController.m

...

@interface ViewController () <IMAAdsLoaderDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

...

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

...

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayerViewController.player play];
}

@end
      

...

class ViewController: UIViewController, IMAAdsLoaderDelegate {

...

  var adsLoader: IMAAdsLoader!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

  func setUpAdsLoader() {
    adsLoader = IMAAdsLoader(settings: nil)
    adsLoader.delegate = self
  }

...

  // MARK: - IMAAdsLoaderDelegate

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    adsManager = adsLoadedData.adsManager
    adsManager.initialize(with: nil)
  }

  func adsLoader(_ loader: IMAAdsLoader!, failedWith adErrorData: IMAAdLoadingErrorData!) {
    print("Error loading ads: " + adErrorData.adError.message)
    showContentPlayer()
    playerViewController.player?.play()
  }
}
      

8. Wyznaczanie przedstawiciela menedżera Google Ads

Aby zarządzać wydarzeniami i zmianami stanu, menedżer Google ds. reklam potrzebuje przedstawiciela i w swojej organizacji. IMAAdManagerDelegate ma metody obsługi zdarzeń reklamowych i błędów, a także metody uruchamiania i wstrzymywania treści wideo.

Rozpoczynam odtwarzanie

Za pomocą metody didReceiveAdEvent można obsługiwać wiele zdarzeń, ale w tym podstawowym przykładzie wystarczy nasłuchiwać zdarzenia LOADED, które przekazują reklamy aby rozpocząć odtwarzanie treści i reklam.

ViewController.m

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

...

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

...

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // Play each ad once it has loaded.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

...
      

...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {

...

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    // Grab the instance of the IMAAdsManager and set yourself as the delegate.
    adsManager = adsLoadedData.adsManager
    adsManager.delegate = self
    adsManager.initialize(with: nil)
  }

...

  // MARK: - IMAAdsManagerDelegate

  func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
    // Play each ad once it has been loaded
    if event.type == IMAAdEventType.LOADED {
      adsManager.start()
    }
  }

...
      

Obsługa błędów

Dodaj też moduł obsługi błędów w reklamach. Jeśli wystąpi błąd, jak w poprzednim kroku aby wznowić odtwarzanie treści.

ViewController.m

...

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing content.
  NSLog(@"AdsManager error: %@", error.message);
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}
@end
      

...

  func adsManager(_ adsManager: IMAAdsManager!, didReceive error: IMAAdError!) {
    // Fall back to playing content
    print("AdsManager error: " + error.message)
    showContentPlayer()
    playerViewController.player?.play()
  }
      

Aktywowanie zdarzeń odtwarzania i wstrzymywania

Dwie ostatnie metody przekazywania dostępu, które musisz zaimplementować, są używane do uruchamiania odtwarzania oraz zdarzeń wstrzymywania zdarzeń w odpowiednich treściach wideo na żądanie pakietu IMA SDK. Aktywowanie wstrzymywania i odtwarzania na żądanie zapobiega pomijaniu fragmentów przez użytkownika. podczas wyświetlania reklam.

ViewController.m

...

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

@end
      

...

  func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager!) {
    // Pause the content for the SDK to play ads.
    playerViewController.player?.pause()
    hideContentPlayer()
  }

  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager!) {
    // Resume the content since the SDK is done playing ads (at least for now).
    showContentPlayer()
    playerViewController.player?.play()
  }
}
      

Znakomicie. Zamawiasz i wyświetlasz reklamy za pomocą pakietu IMA SDK. Aby się uczyć o dodatkowych funkcjach pakietu SDK, znajdziesz w innych przewodnikach lub znajdziesz na GitHubie.

Dalsze kroki

Aby zmaksymalizować przychody z reklam na platformie iOS, poproś o uprawnienia App Transparency i śledzenie dotyczące identyfikatora IDFA.