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 uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA DAI SDK'ları sayesinde uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için akış isteğinde bulunur. SDK, daha sonra birleştirilmiş bir video akışı döndürür. Böylece, uygulamanız içinde reklam ve içerik videosu arasında geçişi yönetmeniz gerekmez.

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

Tam hizmet 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 isterseniz GitHub'dan BasicExample'i indirin.

IMA DAI'ya genel bakış

IMA DAI'yı uygulamak, bu kılavuzda gösterildiği gibi dört ana SDK bileşeni içerir:

  • IMAAdDisplayContainer: Video oynatma öğesinin en üstünde bulunan ve reklam kullanıcı arayüzü öğelerini barındıran bir kapsayıcı nesne.
  • IMAAdsLoader: Akış isteği yanıt nesneleri tarafından tetiklenen etkinlikleri akış isteğinde bulunan ve işleyen bir nesnedir. Uygulamanın kullanım süresi boyunca yeniden kullanılabilecek tek bir reklam yükleyicisi örneklendirmelisiniz.
  • IMAStreamRequest – IMAVODStreamRequest veya IMALiveStreamRequest: Akış isteğini tanımlayan bir nesnedir. Akış istekleri seç-izle video 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şimlerini işleyen bir nesne. Akış yöneticisi ayrıca izleme ping'lerini yönetir ve akış ile reklam etkinliklerini yayıncıya yönlendirir.

Ön koşullar

Başlamadan önce şunlara ihtiyacınız vardır:

Yeni bir Xcode projesi oluşturun

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

IMA DAI SDK'sını Xcode projesine ekleyin

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

CocoaPods'u kullanarak SDK'yı yükleyin (tercih edilir)

CocoaPods, Xcode projeleri için bir bağımlılık 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 belgelerini inceleyin. CocoaPods'u yükledikten sonra aşağıdaki talimatları uygulayarak IMADAI SDK'sını yükleyin:

  1. BasicExample.xcodeproj dosyasıyla 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 :ios, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.22.1'
end

  2. Podfile dosyasını içeren dizinde şu komutu çalıştırın:

    pod install --repo-update`

  3. BasicExample.xcworkspace dosyasını açıp iki proje içerdiğini onaylayarak 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ı, 3.18.4 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 DAI SDK'sı Swift Paketini yükleyin.

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

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

  3. Kullanmak istediğiniz IMA DAI SDK Swift Paketi sürümünü seçin. Yeni projeler için En Yeni Büyük Sürümü kullanmanızı öneririz.

İşiniz bittiğinde Xcode paket bağımlılıklarınızı çözer ve bunları arka planda indirir. Paket bağımlılıklarını ekleme hakkında daha fazla bilgi için Apple makalesini inceleyin.

SDK'yı manuel olarak indirip yükleyin

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

İlk olarak, temel bir video oynatıcı uygulayın. Başlangıçta bu oynatıcı IMA DAI SDK'sını kullanmaz ve oynatmayı tetiklemek için 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 aktarın ve IMA etkileşimi için saplamalar ekleyin

IMA DAI SDK'sını projenize ekledikten sonra SDK'yı içe aktarın ve IMA etkileşiminin birincil noktaları için saplamalar 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 örneğini somutlaştırın ve reklam kapsayıcısı 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ğinde bulunma

Akış bilgilerini saklayacak birkaç sabit değer oluşturun ve ardından istekte bulunmak 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 yönetme

IMAAdsLoader ve IMAStreamManager tetikleme etkinlikleri başlatma, hata ve akış durumundaki değişiklikleri işlemek için kullanılır. Bu etkinlikler, IMAAdsLoaderDelegate ve IMAStreamManagerDelegate protokolleri üzerinden tetiklenir. Reklam yüklenmiş bir etkinliği dinleyin ve akışı başlatın. Bir reklam yüklenemezse bunun yerine yedek bir akış 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ük kaydı ve hata etkinliklerini işleme

Akış yöneticisi temsilcisi tarafından işlenebilecek birkaç etkinlik vardır ancak temel uygulamalar için en önemli kullanımlar etkinlik günlük kaydı gerçekleştirmek, reklamlar oynatılırken arama işlemlerini önlemek ve hataları işlemektir.

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 ile reklam istiyor ve yayınlıyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örnekleri inceleyin.