IMA SDK'sını ayarlama

Platform seçin: HTML5 Android iOS tvOS

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmeyi kolaylaştırır. IMA SDK'ları, herhangi bir VAST uyumlu reklam sunucusundan reklam isteğinde bulunabilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'ları ile SDK reklam oynatmayı yönetirken içerik video oynatmayı kontrol etmeye devam edersiniz. Reklamlar, uygulamanın içerik video oynatıcısının üstüne yerleştirilmiş ayrı bir video oynatıcıda oynatılır.

Bu kılavuzda, IMA SDK'nın 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'ı indirin.

IMA istemci tarafına genel bakış

IMA'yı istemci tarafında uygulama işlemi dört ana SDK bileşenini içerir. Bu bileşenler bu kılavuzda gösterilmektedir:

  • IMAAdDisplayContainer: IMA'nın reklam kullanıcı arayüzü öğelerini oluşturduğu ve Aktif Görüntüleme ile Open Measurement dahil olmak üzere görüntülenebilirliği ölçtüğü yeri belirten bir kapsayıcı nesne.
  • IMAAdsLoader: Reklam isteyen ve reklam isteği yanıtlarındaki etkinlikleri işleyen bir nesne. Yalnızca bir reklam yükleyici oluşturmanız gerekir. Bu yükleyici, uygulamanın kullanım ömrü boyunca yeniden kullanılabilir.
  • IMAAdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam isteklerinde VAST reklam etiketinin URL'si ve reklam boyutları gibi ek parametreler belirtilir.
  • 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 ihtiyacınız vardır:

  • Xcode 13 veya sonraki sürümler
  • CocoaPods (tercih edilen), Swift Package Manager veya iOS için IMA SDK'nın indirilmiş bir kopyası

1. Yeni bir Xcode projesi oluşturma

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

2. IMA SDK'yı Xcode projesine ekleme

CocoaPods, Xcode projeleri için bir bağımlı 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 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:

    Objective-C

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

    Swift

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '12'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
    end
    
    
  2. Podfile dosyasını içeren dizinden şu komutu çalıştırın: pod install --repo-update.

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

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

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

  1. Xcode'da File > Add Package Dependencies... (Dosya > Paket Bağımlılıkları Ekle...) seçeneğine giderek IMA SDK Swift paketini yükleyin.

  2. İstemde, IMA iOS SDK Swift Package GitHub deposunu arayın: 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 Bir Sonraki Ana Sürüme Kadar'ı 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ını ekleme hakkında daha fazla bilgi için Apple'ın makalesine bakın.

SDK'yı manuel olarak indirip yükleme

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

3. Video oynatıcı oluşturma

Öncelikle bir video oynatıcı uygulayın. Başlangıçta bu oynatıcı, IMA SDK'yı kullanmaz ve oynatmayı tetikleyecek herhangi bir yöntem içermez.

Objective-C

Oynatıcı bağımlılıklarını içe aktarın:

#import "ViewController.h"

@import AVFoundation;

Oynatıcı değişkenlerini ayarlayın:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;

/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;

Görünüm yüklendiğinde video oynatıcıyı başlatın:

@implementation ViewController

// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
    @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";

// Ad tag
NSString *const kTestAppAdTagUrl = @"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&"
  @"correlator=";

- (void)viewDidLoad {
  [super viewDidLoad];

  self.playButton.layer.zPosition = MAXFLOAT;

  [self setupAdsLoader];
  [self setUpContentPlayer];
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestAds];
  self.playButton.hidden = YES;
}

Swift

Oynatıcı bağımlılıklarını içe aktarın:

import AVFoundation

Oynatıcı değişkenlerini ayarlayın:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURL = URL(
    string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!

  private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)

  private lazy var playerLayer: AVPlayerLayer = {
    AVPlayerLayer(player: contentPlayer)
  }()

Görünüm yüklendiğinde video oynatıcıyı başlatın:

private lazy var videoView: UIView = {
  let videoView = UIView()
  videoView.translatesAutoresizingMaskIntoConstraints = false
  view.addSubview(videoView)

  NSLayoutConstraint.activate([
    videoView.bottomAnchor.constraint(
      equalTo: view.safeAreaLayoutGuide.bottomAnchor),
    videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
    videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
  ])
  return videoView
}()

// MARK: - View controller lifecycle methods

override func viewDidLoad() {
  super.viewDidLoad()

  videoView.layer.addSublayer(playerLayer)
  adsLoader.delegate = self

  NotificationCenter.default.addObserver(
    self,
    selector: #selector(contentDidFinishPlaying(_:)),
    name: .AVPlayerItemDidPlayToEndTime,
    object: contentPlayer.currentItem)
}

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  playerLayer.frame = videoView.layer.bounds
}

override func viewWillTransition(
  to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
  coordinator.animate { _ in
    // do nothing
  } completion: { _ in
    self.playerLayer.frame = self.videoView.layer.bounds
  }
}

// MARK: - Public methods

func playButtonPressed() {
  requestAds()
}

4. IMA SDK'sını içe aktarma

IMA SDK'yı içe aktarmak için aşağıdakileri yapın:

Objective-C

  1. IMA SDK'yı içe aktarın:

    @import GoogleInteractiveMediaAds;
    
  2. Uygulamada kullanılan IMAAdsLoader, IMAAVPlayerContentPlayhead ve IMAAdsManager sınıfları için değişkenler oluşturun:

    // SDK
    /// Entry point for the SDK. Used to make ad requests.
    @property(nonatomic, strong) IMAAdsLoader *adsLoader;
    
    /// Playhead used by the SDK to track content video progress and insert mid-rolls.
    @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;
    
    /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request.
    @property(nonatomic, strong) IMAAdsManager *adsManager;
    

Swift

  1. IMA SDK'yı içe aktarın:

    import GoogleInteractiveMediaAds
    
    
  2. Uygulamada kullanılan IMAAdsLoader, IMAAVPlayerContentPlayhead ve IMAAdsManager sınıfları için değişkenler oluşturun:

    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&correlator="
    
    private let adsLoader = IMAAdsLoader()
    private var adsManager: IMAAdsManager?
    
    private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {
      IMAAVPlayerContentPlayhead(avPlayer: contentPlayer)
    }()
    

5. İçerik oynatma başlığı izleyicisini ve akış sonu gözlemcisini uygulama

Videonun ortasında gösterilen reklamları oynatmak için IMA SDK'nın video içeriğinizin mevcut konumunu izlemesi gerekir. Bunu yapmak 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 özelliğini kendi sınıfınızda uygulamanız gerekir.

Ayrıca, SDK'ya içeriğinizin oynatılması tamamlandığında bilgi vermeniz gerekir. Böylece SDK, videonun sonunda gösterilen reklamları görüntüleyebilir. Bu işlem, IMAAdsLoader'da contentComplete yöntemini çağırarak AVPlayerItemDidPlayToEndTimeNotification kullanılarak yapılır.

Objective-C

Oynatıcı kurulumunda IMAAVPlayerContentPlayhead örneğini oluşturun:

// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:self.contentPlayer.currentItem];

İçerik oynatıldıktan sonra contentDidFinishPlaying() yöntemini oluşturun: IMAAdsLoader.contentComplete()

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}

Swift

Oynatıcı kurulumunda içeriğin sonunu izleyen gözlemciyi oluşturun:

NotificationCenter.default.addObserver(
  self,
  selector: #selector(contentDidFinishPlaying(_:)),
  name: .AVPlayerItemDidPlayToEndTime,
  object: contentPlayer.currentItem)

İçerik oynatıldıktan sonra contentDidFinishPlaying() yöntemini oluşturun: IMAAdsLoader.contentComplete()

@objc func contentDidFinishPlaying(_ notification: Notification) {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if notification.object as? AVPlayerItem == contentPlayer.currentItem {
    adsLoader.contentComplete()
  }
}

6. Reklam yükleyiciyi başlatma ve reklam isteğinde bulunma

Bir dizi reklam 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 tüm yaşam döngüsü boyunca yalnızca bir IMAAdsLoader örneği bulundurun. Ek reklam istekleri göndermek için yeni bir IMAAdsRequest nesnesi oluşturun ancak aynı IMAAdsLoader öğesini yeniden kullanın. Daha fazla bilgi için IMA SDK SSS bölümüne bakın.

Objective-C

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

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

Swift

private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: PlayerContainerViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}

7. Reklam yükleyici temsilcisi ayarlama

Yükleme etkinliği başarılı olduğunda IMAAdsLoader, adsLoadedWithData yöntemini çağırır ve IMAAdsManager örneğini geçirir. 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ı da ele aldığınızdan emin olun. Reklamlar yüklenmezse kullanıcının deneyimini engellememek için medya oynatmanın reklamsız olarak devam ettiğinden emin olun.

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  adsManager = adsLoadedData.adsManager
  adsManager?.delegate = self

  // Create ads rendering settings and tell the SDK to use the in-app browser.
  let adsRenderingSettings = IMAAdsRenderingSettings()
  adsRenderingSettings.linkOpenerPresentingController = self

  // Initialize the ads manager.
  adsManager?.initialize(with: adsRenderingSettings)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  if let message = adErrorData.adError.message {
    print("Error loading ads: \(message)")
  }
  contentPlayer.play()
}

8. Reklam yöneticisi temsilcisi ayarlama

Son olarak, etkinlikleri ve durum değişikliklerini yönetmek için reklam yöneticisinin 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.

Çalmaya başla

İçerik ve reklamların oynatılmasını başlatmak için LOADED etkinliğini dinleyin. Daha fazla bilgi için didReceiveAdEvent başlıklı makaleyi inceleyin.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  // When the SDK notifies us the ads have been loaded, play them.
  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ğin oynatılmasına devam edin.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Something went wrong with the ads manager after ads were loaded.
  // Log the error and play the content.
  if let message = error.message {
    print("AdsManager error: \(message)")
  }
  contentPlayer.play()
}

Oynatma ve duraklatma etkinliklerini dinleme

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

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // The SDK is going to play ads, so pause the content.
  contentPlayer.pause()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // The SDK is done playing ads (at least for now), so resume the content.
  contentPlayer.play()
}

İşte bu kadar. Artık IMA SDK ile reklam isteğinde bulunup reklam görüntüleyebilirsiniz. Ek SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere göz atın.

Sonraki Adımlar

iOS platformunda reklam gelirini en üst düzeye çıkarmak için IDFA'yı kullanmak üzere App Tracking Transparency izni isteyin.