IMA SDK'ları, multimedya reklamlarını 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 istemci taraflı SDK'larla, SDK reklam oynatmayı işlerken içerikte video oynatmanın kontrolünü size bırakırsınız. Reklamlar, uygulamanın içerik video oynatıcısının üzerine yerleştirilmiş 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. Tamamlanmış bir örnek entegrasyonu görüntülemek veya izlemek istiyorsanız GitHub'dan BasicExample'i indirin.
IMA istemci tarafına genel bakış
IMA istemci tarafını uygulamak için bu kılavuzda açıklanan dört ana SDK bileşeni vardır:
IMAAdDisplayContainer
: Reklamların oluşturulduğu kapsayıcı nesnesi.IMAAdsLoader
: Reklam isteğinde bulunan ve reklam isteği yanıtlarından gelen etkinlikleri işleyen bir nesne. Yalnızca bir reklam yükleyici başlatmalısınız. Bu reklam yükleyici, uygulamanın ömrü boyunca tekrar kullanılabilir.IMAAdsRequest
: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketi 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 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'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ükleyin (önerilir)
CocoaPods, Xcode projeleri için bir 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 edinmek için CocoaPods belgelerini inceleyin. CocoaPods'u yükledikten sonra, IMA SDK'yı yüklemek için aşağıdaki talimatları uygulayın:
BasicExample.xcodeproj dosyanızla aynı dizinde, Podfile adında 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.23.0' end
Podfile dosyasını içeren dizinde
pod install --repo-update
komutunu çalıştırın.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.
Xcode'da Dosya > Paket Ekle... seçeneğine giderek IMA SDK Swift Paketini yükleyin.
Görüntülenen istemde, IMA SDK Swift Package GitHub deposunu arayın:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
Kullanmak istediğiniz IMA SDK Swift Paketi sürümünü seçin. Yeni projeler için Bir Sonraki Ana 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ın nasıl ekleneceği hakkında daha fazla bilgi için Apple'ın makalesine bakın.
SDK'yı manuel olarak indirme ve yükleme
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. Bu oynatıcı başlangıçta IMA SDK'yı kullanmıyor ve henüz oynatmayı tetikleyecek herhangi bir yöntem içermiyor.
ViewController.m
Objective-C
#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
Swift
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ındaki bir içe aktarma ifadesi kullanarak IMA çerçevesini ekleyin.
ViewController.m
Objective-C
#import "ViewController.h" #import <AVKit/AVKit.h> #import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h> NSString *const kContentURLString = @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
Swift
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 izleyicisini ve yayın sonu gözlemleyicisini uygulayın
Videonun ortasında gösterilen reklamların oynatılabilmesi için IMA SDK'nın video içeriğinizin mevcut konumunu izlemesi gerekir. Bunu yapmak için IMAContentPlayhead
kodunu 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ın gösterilebilmesi için içeriğinizin oynatılması bittiğinde SDK'yı bilgilendirmeniz de gerekir. Bu işlem, IMAAdsLoader
üzerinde contentComplete
aranarak AVPlayerItemDidPlayToEndTimeNotification
kullanılarak gerçekleştirilir.
ViewController.m
Objective-C
... @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
Swift
... 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şlatma ve reklam isteğinde bulunma
Reklam grubu istemek için bir IMAAdsLoader
örneği oluşturmanız gerekir.
Bu yükleyici, belirli bir reklam etiketi URL'siyle ilişkilendirilmiş IMAAdsRequest
nesneleri 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 koruyun. 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 hakkında SSS bölümüne bakın.
ViewController.m
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&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
Swift
... 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 yetkisi ayarlama
Başarılı bir yükleme etkinliğinde IMAAdsLoader
, atanan temsilcinin adsLoadedWithData
yöntemini çağırarak bu yönteme IMAAdsManager
örneği iletir. Daha sonra reklam yöneticisini başlatabilirsiniz. Bu işlem, reklam etiketi URL'sine verilen yanıtla tanımlandığı şekilde reklamları tek tek yükler.
Ayrıca, yükleme işlemi sırasında oluşabilecek hataları da ele aldığınızdan emin olun. Reklamlar yüklenmiyorsa kullanıcı deneyimini sekteye uğratmamak için medya oynatmanın reklamlar olmadan devam ettiğinden emin olun.
ViewController.m
Objective-C
... @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
Swift
... 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 yetkilendirmesi oluşturma
Son olarak, etkinlikleri ve durum değişikliklerini yönetmek için reklam yöneticisinin kendi yetkilisine
ihtiyacı vardır. IMAAdManagerDelegate
, video içeriğinizde oynatma ve duraklatmayı tetiklemenin yanı sıra reklam etkinliklerini ve hataları ele almak için yöntemlere sahiptir.
Oynatma başlatılıyor
didReceiveAdEvent
yönteminin işlenebileceği birçok etkinlik vardır. Ancak bu temel örnekte, reklam yöneticisine içeriği ve reklamları oynatmaya başlamasını söylemek için LOADED
etkinliğini dinleyin.
ViewController.m
Objective-C
@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]; } } ...
Swift
... 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çerik oynatmayı devam ettirin.
ViewController.m
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]; } @end
Swift
... 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 etkinlikleri duraklatma amacıyla kullanılır. İstendiğinde duraklatma ve oynatmanın tetiklenmesi, reklamlar gösterilirken kullanıcının video içeriğinin bazı bölümlerini kaçırmasını önler.
ViewController.m
Objective-C
... - (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
Swift
... 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. Artık IMA SDK ile reklam istiyor ve görüntülüyorsunuz. Diğer SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere bakın.
Sonraki adımlar
iOS platformunda reklam gelirini en üst düzeye çıkarmak amacıyla IDFA kullanmak üzere Uygulama Şeffaflığı ve İzleme izni isteyin.