Başlama

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları, VAST ile uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'larıyla, SDK reklam oynatmayı yönetirken içerik videosunun oynatılmasını kontrol edebilirsiniz. Reklamlar, uygulamanın içerik video oynatıcının üstüne yerleştirilmiş ayrı bir video oynatıcıda oynatılır.

Bu kılavuzda, IMA SDK'nın basit bir video oynatıcı uygulamasına nasıl entegre edileceği gösterilmektedir. Tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek istiyorsanız GitHub'dan BasicExample dosyasını indirin.

IMA istemci tarafına genel bakış

IMA'yı istemci tarafında uygulamak, bu kılavuzda gösterilen dört ana SDK bileşenini içerir:

  • IMAAdDisplayContainer: Reklamların oluşturulduğu kapsayıcı nesne.
  • IMAAdsLoader: Reklam isteyen ve reklam isteği yanıtlarından gelen etkinlikleri işleyen bir nesne. Yalnızca bir reklam yükleyicisi oluşturmanız gerekir. Bu reklam yükleyici, uygulamanın ömrü boyunca yeniden kullanılabilir.
  • IMAAdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketinin URL'sini ve reklam boyutları gibi ek parametreleri belirtir.
  • IMAAdsManager: Reklam isteğine verilen yanıtı içeren, reklam oynatmayı kontrol eden ve SDK tarafından tetiklenen reklam etkinliklerini dinleyen bir nesne.

Ön koşullar

Başlamadan önce aşağıdakilere sahip olmanız gerekir:

1. Yeni bir Xcode projesi oluşturma

Xcode'da Objective-C veya Swift kullanarak yeni bir tvOS projesi oluşturun. Proje adı olarak BasicExample'ı kullanın.

2. IMA SDK'sını Xcode projesine ekleme

SDK'yı CocoaPods kullanarak yükleme (tercih edilir)

CocoaPods, Xcode projeleri için bir bağımlı yöneticisidir ve IMA SDK'sını yüklemek için önerilen yöntemdir. CocoaPods'u yükleme veya kullanma hakkında daha fazla bilgi için CocoaPods belgelerine bakın. CocoaPods'u yükledikten sonra IMA SDK'yı yüklemek için aşağıdaki talimatları uygulayın:

  1. BasicExample.xcodeproj dosyanızla aynı dizinde Podfile adlı bir metin dosyası oluşturun ve aşağıdaki yapılandırmayı ekleyin:

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

  2. Podfile dosyasını içeren dizinden pod install --repo-update

  3. BasicExample.xcworkspace dosyasını açıp iki proje içerdiğini doğrulayarak yüklemenin başarılı olduğunu doğrulayın: BasicExample ve Pods (CocoaPods tarafından yüklenen bağımlılıklar).

Swift Package Manager'ı kullanarak SDK'yı yükleme

Interactive Media Ads SDK'sı, 4.8.2 sürümünden itibaren Swift Package Manager'ı destekler. Swift paketini içe aktarmak için aşağıdaki adımları uygulayın.

  1. Xcode'da Dosya > Paket Ekle...'ye giderek IMA SDK Swift Paketi'ni yükleyin.

  2. Görünen istemde IMA SDK Swift Paketi GitHub deposunu arayın:

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

  3. Kullanmak istediğiniz IMA SDK Swift paketinin sürümünü seçin. Yeni projeler için Sonraki Büyük Sürüme Kadar seçeneğini kullanmanızı öneririz.

İşlemi tamamladığınızda Xcode, paket bağımlılıklarınıza çözüm bulur ve bunları arka planda indirir. Paket bağımlılıkları ekleme hakkında daha fazla bilgi için Apple'ın makalesine göz atın.

SDK'yı manuel olarak indirme ve yükleme

CocoaPods kullanmak istemiyorsanız IMA SDK'yı indirip projenize manuel olarak ekleyebilirsiniz.

3. Basit bir video oynatıcı oluşturma

Öncelikle temel bir video oynatıcı uygulayın. Bu oynatıcı başlangıçta IMA SDK'sını kullanmaz ve oynatmayı tetikleyecek herhangi bir yöntem içermez.

ViewController.m

Objective-C

#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

Swift

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. IMA SDK'sını içe aktarma

Ardından, mevcut içe aktarma işlemlerinin altına bir içe aktarma ifadesi kullanarak IMA çerçevesini ekleyin.

ViewController.m

Objective-C

#import "ViewController.h"

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

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

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

5. İçerik oynatma çubuğu izleyicisini ve yayın sonu gözlemcisini uygulama

Videonun ortasında gösterilen reklamları oynatmak için IMA SDK'sının video içeriğinizin mevcut konumunu izlemesi gerekir. Bunun için IMAContentPlayhead sınıfını uygulayan bir sınıf oluşturun. Bu örnekte gösterildiği gibi bir AVPlayer kullanıyorsanız SDK, bunu sizin için yapan IMAAVPlayerContentPlayhead sınıfını sağlar. AVPlayer kullanmıyorsanız IMAContentPlayhead'u kendi sınıfınızda uygulamanız gerekir.

Ayrıca, videonun ortasında gösterilen reklamları gösterebilmesi için SDK'ya içeriğinizin oynatılmasının sona erdiğini bildirmeniz gerekir. Bu işlem, IMAAdsLoader üzerinde AVPlayerItemDidPlayToEndTimeNotification kullanılarak contentComplete çağrılarak yapılır.

ViewController.m

Objective-C

...

@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

Swift

...

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. Reklam yükleyiciyi başlatma ve reklam isteği gönderme

Bir reklam grubu istemek için IMAAdsLoader örneği oluşturmanız gerekir. Bu yükleyici, belirtilen bir reklam etiketi URL'siyle ilişkili IMAAdsRequest nesnelerini işlemek için kullanılabilir.

En iyi uygulama olarak, uygulamanızın yaşam döngüsünün tamamı için yalnızca bir IMAAdsLoader örneği bulundurun. Ek reklam istekleri göndermek için yeni bir IMAAdsRequest nesnesi oluşturun ancak aynı IMAAdsLoader'yi yeniden kullanın. Daha fazla bilgi için IMA SDK SSS bölümünü inceleyin.

ViewController.m

Objective-C

...

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

Swift

...

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 your 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. Reklam yükleyici temsilcisi ayarlama

Başarılı bir yükleme etkinliğinde IMAAdsLoader, atanmış temsilcisinin adsLoadedWithData yöntemini çağırarak ona bir IMAAdsManager örneği iletir. Ardından, reklam etiketi URL'sine verilen yanıtta tanımlandığı şekilde tek tek reklamları yükleyen reklam yöneticisini başlatabilirsiniz.

Ayrıca, yükleme işlemi sırasında oluşabilecek hataları giderdiğinizden emin olun. Reklamlar yüklenmezse kullanıcı deneyimini etkilememek için medya oynatmanın reklam olmadan devam etmesini sağlayın.

ViewController.m

Objective-C

...

@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

Swift

...

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. Reklam yöneticisi temsilcisi ayarlama

Son olarak, reklam yöneticisinin etkinlikleri ve durum değişikliklerini yönetmek için kendi temsilcisine ihtiyacı vardır. IMAAdManagerDelegate, reklam etkinliklerini ve hatalarını işleme yöntemlerinin yanı sıra video içeriğinizde oynatma ve duraklatma işlemlerini tetikleme yöntemlerine sahiptir.

Oynatmayı başlatma

didReceiveAdEvent yönteminin kullanılabileceği birçok etkinlik vardır ancak bu temel örnekte, reklam yöneticisine içerik ve reklamların oynatılmasını başlatmasını söylemek için LOADED etkinliğini dinlemeniz yeterlidir.

ViewController.m

Objective-C

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

...

Swift

...

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()
    }
  }

...

Hataları işleme

Reklam hataları için de bir işleyici ekleyin. Önceki adımda olduğu gibi bir hata oluşursa içeriği oynatmaya devam edin.

ViewController.m

Objective-C

...

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

Swift

...

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

Oynat ve duraklat etkinliklerini tetikleme

Uygulamanız gereken son iki temsilci yöntemi, IMA SDK tarafından istendiğinde temel video içeriğinde oynatma ve duraklatma etkinliklerini tetiklemek için kullanılır. İstendiğinde duraklatma ve oynatma işleminin tetiklenmesi, reklamlar gösterilirken kullanıcının video içeriğinin bir kısmını kaçırmasını önler.

ViewController.m

Objective-C

...

- (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

Swift

...

  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()
  }
}

İşte bu kadar. Artık IMA SDK'sını kullanarak reklam isteğinde bulunuyor ve reklamları görüntülüyorsunuz. Diğer SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere göz atın.

Sonraki Adımlar

tvOS platformunda reklam gelirini en üst düzeye çıkarmak için IDFA'yı kullanmak üzere Uygulama Şeffaflığı ve İzleme izni isteyin.