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
SDK'yı CocoaPods kullanarak yükleyin (önerilir).
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:
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
Podfile dosyasını içeren dizinden şu komutu çalıştırın:
pod install --repo-update
.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:
Xcode'da File > Add Package Dependencies... (Dosya > Paket Bağımlılıkları Ekle...) seçeneğine giderek IMA SDK Swift paketini yükleyin.
İstemde, IMA iOS SDK Swift Package GitHub deposunu arayın:
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ü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
IMA SDK'yı içe aktarın:
@import GoogleInteractiveMediaAds;
Uygulamada kullanılan
IMAAdsLoader
,IMAAVPlayerContentPlayhead
veIMAAdsManager
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
IMA SDK'yı içe aktarın:
import GoogleInteractiveMediaAds
Uygulamada kullanılan
IMAAdsLoader
,IMAAVPlayerContentPlayhead
veIMAAdsManager
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.