Başlama

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları, VAST uyumlu reklam sunucularından reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'ları ile içeriklerin video oynatmasının kontrolü sizdeyken SDK reklam oynatma işlemini gerçekleştirir. Reklamlar, uygulamanın içerik video oynatıcısının üst kısmında yer alan 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. Örnek bir entegrasyonla birlikte görüntülemek veya takip etmek isterseniz GitHub'dan BasicExample'i indirin.

IMA istemci tarafına genel bakış

IMA istemci tarafını uygulama, bu kılavuzda gösterilen dört ana SDK bileşeni içerir:

• IMAAdDisplayContainer: Reklamların oluşturulduğu bir kapsayıcı nesnesi.
• IMAAdsLoader: Reklam isteğinde bulunan ve reklam isteği yanıtlarından gelen etkinlikleri işleyen bir nesnedir. Uygulamanın kullanım süresi boyunca tekrar kullanılabilecek bir reklam yükleyicisi kullanmanız gerekir.
• IMAAdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketinin URL'sinin yanı sıra reklam boyutları gibi ek parametreleri de belirtir.
• IMAAdsManager: Reklam isteğine verilen yanıtı içeren, reklam oynatmayı kontrol eden ve SDK tarafından tetiklenen reklam etkinliklerini dinleyen bir nesnedir.

Ön koşullar

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

• Xcode 13 veya sonraki bir sürüm
• CocoaPods (tercih edilir), Swift Package Manager veya iOS için IMA SDK'nın indirilen bir kopyası

1. Yeni Xcode projesi oluştur

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

2. IMA SDK'yı Xcode projesine ekleme

SDK'yı CocoaPods kullanarak yükleme (önerilir)

CocoaPods, Xcode projelerinin bağımlılık yöneticisidir ve IMA SDK'yı 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, 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 :ios, '14'
   target "BasicExample" do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.22.1'
   end
   

2. Podfile'ı içeren dizinde pod install --repo-update komutunu çalıştırın.

3. BasicExample.xcworkspace dosyasını açıp dosyanın 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... seçeneğine giderek IMA SDK Swift Paketini yükleyin.

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

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

3. Kullanmak istediğiniz IMA SDK Swift Paketi sürümünü seçin. Yeni projeler için Sonraki Ana Sürüm'ü kullanmanızı öneririz.

Bitirdiğinizde Xcode paket bağımlılıklarınızı çözer ve bunları arka planda indirir. Paket bağımlılıkları 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 SDK'yı indirip projenize manuel olarak ekleyebilirsiniz.

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

İlk olarak, temel bir video oynatıcı uygulayın. Başlangıçta bu oynatıcı IMA SDK'yı kullanmaz ve henüz oynatmayı tetiklemek için herhangi bir yöntem içermez.

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

Ardından, mevcut içe aktarmaların altında bir içe aktarma ifadesi kullanarak IMA çerçevesini ekleyin.

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. İçerik video yer imleci izleyicisi ve yayın sonu gözlemcisini uygulayın

Videonun ortasında gösterilen reklamları oynatmak için IMA SDK'nın video içeriğinizin mevcut konumunu izlemesi gerekir. Bunun için, IMAContentPlayhead 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 öğesini kendi sınıfınıza uygulamanız gerekir.

Videodan sonra gösterilen reklamları görüntüleyebilmesi için içeriğinizin oynatılması bittiğinde SDK'yı bilgilendirmeniz gerekir. Bunun için IMAAdsLoader, AVPlayerItemDidPlayToEndTimeNotification ile contentComplete çağrılır.

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. Reklam yükleyiciyi başlatın ve reklam isteğinde bulunun

Bir reklam grubu istemek için IMAAdsLoader örneği oluşturmanız gerekir. Bu yükleyici, belirli 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ü boyunca yalnızca bir IMAAdsLoader örneğini sağlayın. Ek reklam istekleri yapmak için yeni bir IMAAdsRequest nesnesi oluşturun ancak aynı IMAAdsLoader öğesini yeniden kullanın. Daha fazla bilgi için IMA SDK ile ilgili SSS bölümüne bakın.

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

Başarılı bir yükleme etkinliğinde IMAAdsLoader, atandığı temsilcinin adsLoadedWithData yöntemini çağırarak buna bir IMAAdsManager örneği iletir. Daha sonra Reklam Yöneticisi'ni başlatabilirsiniz. Bu işlem, reklam etiketi URL'sine verilen yanıtın tanımlandığı şekilde tek reklamları yükler.

Ayrıca, yükleme işlemi sırasında oluşabilecek hataları ele aldığınızdan emin olun. Reklamlar yüklenmezse kullanıcı deneyimini etkilememek için medya oynatmanın reklam olmadan devam ettiğinden emin olun.

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. Reklam yöneticisi için yetki verilmiş kullanıcı oluşturma

Son olarak, etkinlikleri ve durum değişikliklerini yönetmek için reklam yöneticisinin kendine ait bir temsilciye ihtiyacı vardır. IMAAdManagerDelegate, video içeriğinizin oynatılmasını ve duraklatılmasını tetiklemenin yanı sıra reklam etkinliklerini ve hatalarını işlemeye yönelik yöntemlere sahiptir.

Oynatma başlatılıyor

didReceiveAdEvent yönteminin kullanmak için kullanılabilecek birçok etkinliği vardır ancak bu temel örnekte, reklam yöneticisine içerik ve reklamları oynatmaya başlamasını bildirmek için LOADED etkinliğini dinlemeniz yeterlidir.

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

...
      

Hataları işleme

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

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

Oynatma ve duraklatma etkinliklerini tetikleme

Uygulamanız gereken son iki yetki verme yöntemi, IMA SDK tarafından istendiğinde temel video içeriğinde oynatma ve duraklatma etkinliklerini tetiklemek için kullanılır. İstekte bulunulduğunda duraklatma ve oynatmanın tetiklenmesi, reklamlar görüntülenirken kullanıcının video içeriğinin bazı bölümlerinin eksik olmasını önler.

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

İşte bu kadar. Şu anda IMA SDK ile reklam istiyor ve gösteriyorsunuz. Ek SDK özellikleri hakkında bilgi edinmek için diğer kılavuzları veya GitHub'daki örnekleri inceleyin.

Sonraki adımlar

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