IMA DAI SDK'sını kullanmaya 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 DAI SDK'ları ile uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için bir yayın isteği gönderir. Ardından SDK, birleştirilmiş bir video akışı döndürür. Böylece uygulamanızda reklam ve içerik videosu arasında geçiş yapmanıza gerek kalmaz.

İlgilendiğiniz DAI çözümünü seçin

Tam kapsamlı DAI

Bu kılavuzda, IMA DAI SDK'sı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 DAI'ye genel bakış

IMA DAI'yi uygulamak, bu kılavuzda gösterildiği gibi üç ana SDK bileşenini içerir:

  • IMAAdDisplayContainer: Video oynatma öğesinin üzerinde bulunan ve reklam kullanıcı arayüzü öğelerini barındıran bir kapsayıcı nesnesi.
  • IMAAdsLoader: Akış isteğinde bulunan ve akış isteği yanıtı nesneleri tarafından tetiklenen etkinlikleri işleyen bir nesne. Uygulamanın ömrü boyunca yeniden kullanılabilecek tek bir reklam yükleyicisi oluşturmanız gerekir.
  • IMAStreamRequest: IMAVODStreamRequest veya IMALiveStreamRequest: Akış isteğini tanımlayan bir nesne. Akış istekleri, seç-izle videolar veya canlı yayınlar için olabilir. İstekler, bir içerik kimliğinin yanı sıra API anahtarı veya kimlik doğrulama jetonu ve diğer parametreleri belirtir.
  • IMAStreamManager: Dinamik reklam ekleme akışlarını ve DAI arka ucuyla etkileşimleri yöneten bir nesne. Yayın yöneticisi, izleme ping'lerini de yönetir ve yayın ile reklam etkinliklerini yayıncıya iletir.

Ön koşullar

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

Yeni bir Xcode projesi oluşturma

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

IMA DAI SDK'sını Xcode projesine ekleme

IMA DAI SDK'sını yüklemek için bu üç yöntemden birini kullanın.

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

CocoaPods, Xcode projeleri için bir bağımlı yöneticisidir ve IMA DAI 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 DAI SDK'sını 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 şunları çalıştırın:

    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 GoogleInteractiveMediaAds Swift paketini yükleyin.

  2. Görüntülenen istemde GoogleInteractiveMediaAds Swift Package GitHub deposunu arayın:

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

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

İşlem tamamlandığında 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

Swift Package Manager veya CocoaPods'u kullanmak istemiyorsanız IMA DAI SDK'sını indirip projenize manuel olarak ekleyebilirsiniz.

Basit bir video oynatıcı oluşturma

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

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

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

@implementation ViewController

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

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

SDK'yı içe aktarma ve IMA etkileşimi için yoksunluk dokümanı ekleme

IMA DAI SDK'sını projenize ekledikten sonra SDK'yı içe aktarın ve IMA etkileşiminin birincil noktaları için yoksunluk dokümanı ekleyin.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

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

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

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

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

IMAAdsLoader'ı uygulama

Ardından IMAAdsLoader öğesini örneklendirin ve reklam kapsayıcı görünümünü görünüm hiyerarşisine ekleyin.

ViewController.m

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

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}

Akış isteği gönderme

Akış bilgilerini tutacak birkaç sabit oluşturun ve ardından isteği yapmak için akış isteği işlevini uygulayın.

ViewController.m

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}

Akış etkinliklerini işleme

IMAAdsLoader ve IMAStreamManager, başlatma, hataları ve akış durumundaki değişiklikleri işlemek için kullanılan etkinlik tetikler. Bu etkinlikler IMAAdsLoaderDelegate ve IMAStreamManagerDelegate protokolleri üzerinden tetiklenir. Reklam yüklendi etkinliğini dinleyin ve yayını başlatın. Bir reklam yüklenemezse bunun yerine yedek bir yayın oynatın.

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

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

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

Günlüğe kaydetme ve hata etkinliklerini işleme

Akış yöneticisi temsilcisi tarafından ele alınabilecek çeşitli etkinlikler vardır ancak temel uygulamalarda en önemli kullanım alanları etkinlik günlüğü oluşturma, reklamlar oynatılırken arama işlemlerini önleme ve hataları işlemedir.

ViewController.m

#pragma mark - IMAStreamManagerDelegate

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

İşte bu kadar. Artık IMA DAI SDK'sını kullanarak reklam isteğinde bulunuyor ve reklamları görüntülüyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzları veya GitHub'daki örnekleri inceleyin.