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 isterseniz 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
- Swift Package Manager, CocoaPods veya tvOS 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 tvOS projesi oluşturun. Proje adı olarak BasicExample'ı kullanın.
2. IMA SDK'yı Xcode projesine ekleme
IMA SDK'yı Swift Package Manager ile yükleme
Interactive Media Ads SDK'sı, 4.8.2 sürümünden itibaren Swift Package Manager'ı desteklemektedir. Swift paketini içe aktarmak için aşağıdaki adımları uygulayın.
Xcode'da File > Add Packages... (Dosya > Paket Ekle...) seçeneğine giderek IMA SDK Swift Paketini yükleyin.
Görünen istemde IMA SDK Swift Package GitHub deposunu arayın:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosKullanmak 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 göz atın.
CocoaPods'u kullanarak IMA SDK'yı yükleme
IMA SDK'yı yüklemek için CocoaPods'u kullanın. CocoaPods'u yükleme veya kullanma hakkında daha fazla bilgi için CocoaPods belgelerine bakın. CocoaPods'u yükledikten sonra şunları yapın:
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, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endPodfile dosyasını içeren dizinden
pod install --repo-updatekomutunu çalıştırın.BasicExample.xcworkspace dosyasını açıp iki proje içerdiğini (BasicExample ve Pods) doğrulayarak yüklemenin başarılı olduğunu onaylayın. Pods, CocoaPods tarafından yüklenen bağımlılıkları ifade eder.
IMA SDK'yı manuel olarak indirme ve yükleme
CocoaPods kullanmak istemiyorsanız IMA SDK'yı indirip projenize manuel olarak ekleyebilirsiniz.
3. IMA SDK'sını içe aktarma
İçe aktarma ifadesini kullanarak IMA çerçevesini ekleyin.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. Video oynatıcı oluşturma ve IMA SDK'yı entegre etme
Aşağıdaki örnekte IMA SDK başlatılıyor:
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&cmsid=496&vid=short_onecue&correlator=";
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
[self setupContentPlayer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestAds];
}
// 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 resume events from the
// remote and play content underneath the ad.
[self.contentPlayerViewController willMoveToParentViewController:nil];
[self.contentPlayerViewController.view removeFromSuperview];
[self.contentPlayerViewController removeFromParentViewController];
}
Swift
class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURLString =
"https://devstreaming-cdn.apple.com/videos/streaming/examples/"
+ "img_bipbop_adv_example_fmp4/master.m3u8"
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="
var adsLoader: IMAAdsLoader!
var adDisplayContainer: IMAAdDisplayContainer!
var adsManager: IMAAdsManager!
var contentPlayhead: IMAAVPlayerContentPlayhead?
var playerViewController: AVPlayerViewController!
var adBreakActive = false
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setUpContentPlayer()
setUpAdsLoader()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestAds()
}
Bu örnekte viewDidLoad(), IMAAdsLoader öğesini başlatır ve viewDidAppear(), görünüm görünür hale geldiğinde reklam isteğinde bulunur. Yardımcı yöntemler
showContentPlayer() ve hideContentPlayer(), reklam oynatma sırasında
içerik görünürlüğünü değiştirir.
Bu örnekte, reklam isteği için VAST reklam etiketini tanımlamak üzere adTagURLString sabit değişkeni ve IMA SDK'yı yönetmek için aşağıdaki bileşenler kullanılmaktadır:
adsLoader: Reklam isteklerini ve yanıtlarını işler. Uygulamanın yaşam döngüsü için tek bir örnek kullanmanızı öneririz.adDisplayContainer: Reklamların oluşturulacağı görünümü belirtir.adsManager: Reklam oynatmayı yönetir ve reklam etkinliklerini dinler.contentPlayhead: Videonun ortasında gösterilen reklam aralarını tetiklemek için içerik ilerleme durumunu izler.adBreakActive: Reklamların üzerine sarılmasını önlemek için reklam arasının oynatılıp oynatılmadığını gösterir.
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.
Objective-C
- (void)setupContentPlayer {
// Create a content video player. Create a playhead to track content progress so the SDK knows
// when to play ads in a VMAP playlist.
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];
}
Swift
func setUpContentPlayer() {
// Load AVPlayer with path to our content.
let contentURL = URL(string: ViewController.contentURLString)!
let player = AVPlayer(url: contentURL)
playerViewController = AVPlayerViewController()
playerViewController.player = player
// Set up our 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()
}
Ayrıca, SDK'nın videonun sonunda gösterilen reklamları görüntüleyebilmesi için içeriğinizin oynatılması tamamlandığında SDK'yı bilgilendirmeniz gerekir. Bu işlem, IMAAdsLoader üzerinde contentComplete çağrılarak ve AVPlayerItemDidPlayToEndTimeNotification kullanılarak yapılır.
Objective-C
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Notify the SDK that the postrolls should be played.
[self.adsLoader contentComplete];
}
- (void)dealloc {
[[NSNotificationCenter defaultCenter] removeObserver:self];
}
Swift
@objc func contentDidFinishPlaying(_ notification: Notification) {
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] init];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Pass the main view as the container for ad display.
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
viewController:self];
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
adDisplayContainer:self.adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Swift
func setUpAdsLoader() {
adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
}
func requestAds() {
// Create ad display container for ad rendering.
adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
// 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)
}
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
#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.delegate = self;
[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];
}
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
adsManager.initialize(with: nil)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.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.
Oynatmayı başlatma
didReceiveAdEvent yöntemi, birçok etkinliği işlemek için kullanılabilir.
Bu temel örnekte, içerik ve reklamların oynatılmasını başlatması için reklam yöneticisine talimat vermek üzere LOADED etkinliğini dinleyin. IMA SDK, kullanıcı bir simgeye dokunduktan sonra simge geri dönüşü iletişim kutusunu kapattığında ICON_FALLBACK_IMAGE_CLOSED etkinliğini tetikler. Bu işlemden sonra reklam oynatma devam eder.
Objective-C
#pragma mark - IMAAdsManagerDelegate
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
switch (event.type) {
case kIMAAdEvent_LOADED: {
// Play each ad once it has loaded.
[adsManager start];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume ad after user has closed dialog.
[adsManager resume];
break;
}
default:
break;
}
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
switch event.type {
case IMAAdEventType.LOADED:
// Play each ad once it has been loaded.
adsManager.start()
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
adsManager.resume()
default:
break
}
}
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 {
// Fall back to playing content.
NSLog(@"AdsManager error: %@", error.message);
[self showContentPlayer];
[self.contentPlayerViewController.player play];
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Fall back to playing content
print("AdsManager error: \(error.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
Oynatma ve duraklatma 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ş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 {
// Pause the content for the SDK to play ads.
[self.contentPlayerViewController.player pause];
[self hideContentPlayer];
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// Resume the content since the SDK is done playing ads (at least for now).
[self showContentPlayer];
[self.contentPlayerViewController.player play];
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
}
Swift
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// Pause the content for the SDK to play ads.
playerViewController.player?.pause()
hideContentPlayer()
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// Resume the content since the SDK is done playing ads (at least for now).
showContentPlayer()
playerViewController.player?.play()
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
}
İş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
tvOS platformunda reklam gelirini en üst düzeye çıkarmak için IDFA'yı kullanmak üzere Uygulama Şeffaflığı ve İzleme izni isteyin.