کیتهای توسعه نرمافزار IMA ادغام تبلیغات چندرسانهای را در وبسایتها و برنامههای شما آسان میکنند. کیتهای توسعه نرمافزار IMA میتوانند از هر سرور تبلیغاتی سازگار با VAST درخواست تبلیغات کنند و پخش تبلیغات را در برنامههای شما مدیریت کنند. با کیتهای توسعه نرمافزار سمت کلاینت IMA، شما کنترل پخش ویدیوی محتوا را در دست دارید، در حالی که SDK پخش تبلیغات را مدیریت میکند. تبلیغات در یک پخشکننده ویدیوی جداگانه که در بالای پخشکننده ویدیوی محتوای برنامه قرار دارد، پخش میشوند.
این راهنما نحوه ادغام IMA SDK را در یک برنامه پخش کننده ویدیو نشان میدهد. برای مشاهده یا دنبال کردن یک نمونه ادغام تکمیل شده، BasicExample را از GitHub دانلود کنید.
مرور کلی سمت کلاینت IMA
پیادهسازی IMA سمت کلاینت شامل چهار مؤلفه اصلی SDK است که این راهنما آنها را نشان میدهد:
-
IMAAdDisplayContainer: یک شیء کانتینر که مشخص میکند IMA عناصر رابط کاربری تبلیغاتی را کجا رندر میکند و قابلیت مشاهده، از جمله نمای فعال و اندازهگیری باز را اندازهگیری میکند. -
IMAAdsLoader: شیءای که تبلیغات را درخواست میکند و رویدادهای پاسخ به درخواست تبلیغات را مدیریت میکند. شما فقط باید یک بارگذار تبلیغات را نمونهسازی کنید که میتواند در طول عمر برنامه بارها مورد استفاده قرار گیرد. -
IMAAdsRequest: شیءای که یک درخواست تبلیغات را تعریف میکند. درخواستهای تبلیغات، URL مربوط به تگ تبلیغ VAST و همچنین پارامترهای اضافی مانند ابعاد تبلیغ را مشخص میکنند. -
IMAAdsManager: شیءای که شامل پاسخ به درخواست تبلیغات است، پخش تبلیغات را کنترل میکند و به رویدادهای تبلیغاتی که توسط SDK ایجاد میشوند، گوش میدهد.
پیشنیازها
قبل از شروع، به موارد زیر نیاز دارید:
- ایکسکد ۱۳ یا بالاتر
- روش نصب IMA SDK:
- مدیر بسته Swift (ترجیحاً)
- کوکوپادز
- یک نسخه دانلود شده از IMA SDK برای iOS
۱. یک پروژه جدید Xcode ایجاد کنید
در Xcode، یک پروژه iOS جدید با استفاده از Objective-C یا Swift ایجاد کنید. از BasicExample به عنوان نام پروژه استفاده کنید.
۲. اضافه کردن IMA SDK به پروژه Xcode
برای نصب IMA SDK، یک روش ترجیحی را انتخاب کنید.
توصیه میشود: SDK را با استفاده از Swift Package Manager نصب کنید
کیت توسعه نرمافزاری تبلیغات رسانهای تعاملی (Interactive Media Ads SDK) از نسخه ۳.۱۸.۴ به بعد از Swift Package Manager پشتیبانی میکند. برای وارد کردن بسته Swift، مراحل زیر را انجام دهید:
در Xcode، با رفتن به مسیر File > Add Package Dependencies...، بسته IMA SDK Swift را نصب کنید.
در اعلان، مخزن گیتهاب IMA iOS SDK Swift Package را جستجو کنید:
swift-package-manager-google-interactive-media-ads-ios.نسخه IMA SDK Swift Package مورد نظر خود را انتخاب کنید. برای پروژههای جدید، توصیه میکنیم از Up to Next Major Version استفاده کنید.
پس از اتمام کار، Xcode وابستگیهای بسته شما را حل کرده و آنها را در پسزمینه دانلود میکند. برای جزئیات بیشتر در مورد نحوه اضافه کردن وابستگیهای بسته، به مقاله اپل مراجعه کنید.
نصب SDK با استفاده از CocoaPods
CocoaPods یک مدیر وابستگی برای پروژههای Xcode است و روش پیشنهادی برای نصب IMA SDK میباشد. برای اطلاعات بیشتر در مورد نصب یا استفاده از CocoaPods، به مستندات CocoaPods مراجعه کنید. پس از نصب CocoaPods، از دستورالعملهای زیر برای نصب IMA SDK استفاده کنید:
در همان دایرکتوری که فایل BasicExample.xcodeproj شما قرار دارد، یک فایل متنی به نام Podfile ایجاد کنید و پیکربندی زیر را به آن اضافه کنید:
از دایرکتوری که شامل Podfile است،
pod install --repo-updateرا اجرا کنید.با باز کردن فایل BasicExample.xcworkspace و تأیید اینکه شامل دو پروژه است، تأیید کنید که نصب موفقیتآمیز بوده است: BasicExample و Pods (وابستگیهای نصبشده CocoaPods).
دانلود و نصب دستی SDK
اگر نمیخواهید از Swift Package Manager استفاده کنید، IMA SDK را دانلود کرده و به صورت دستی به پروژه خود اضافه کنید.
نمایش/پنهان کردن دستورالعملها
- از صفحه دانلود iOS IMA ، آخرین نسخه iOS IMA SDK را دانلود و استخراج کنید.
- فایل BasicExample.xcodeproj را باز کنید.
- در پنل سمت چپ، روی نام پروژه کلیک کنید.
- در پنل وسط، روی «مراحل ساخت» کلیک کنید.
- بخش «پیوند دودویی با کتابخانهها» را گسترش دهید.
- در پایین لیست کتابخانهها، روی نماد بعلاوه [+] کلیک کنید.
- روی افزودن موارد دیگر کلیک کنید.
- در پوشهای که SDK دانلود شده را از حالت فشرده خارج کردهاید، GoogleInteractiveMediaAds.framework را انتخاب کرده و روی Open کلیک کنید.
- در پایین لیست کتابخانهها، دوباره روی آیکون بعلاوه [+] کلیک کنید.
- در ستون وضعیت ، تأیید کنید که
GoogleInteractiveMediaAds.frameworkرویRequiredتنظیم شده باشد. - پرچم پیونددهندهی
-ObjCرا در تنظیمات ساخت خود وارد کنید. برای اطلاعات بیشتر، به Apple QA1490 مراجعه کنید.
۳. یک پخشکننده ویدیو ایجاد کنید
ابتدا، یک پخشکنندهی ویدیو پیادهسازی کنید. در ابتدا، این پخشکننده از IMA SDK استفاده نمیکند و هیچ متدی برای شروع پخش ندارد.
هدف-سی
وابستگیهای بازیکن را وارد کنید:
#import "ViewController.h"
@import AVFoundation;
متغیرهای پخشکننده را تنظیم کنید:
@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;
پخش کننده ویدیو را هنگام بارگذاری نما آغاز میکند:
@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;
}
سویفت
وابستگیهای بازیکن را وارد کنید:
import AVFoundation
متغیرهای پخشکننده را تنظیم کنید:
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)
}()
پخش کننده ویدیو را هنگام بارگذاری نما آغاز میکند:
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()
}
۴. IMA SDK را وارد کنید
برای وارد کردن IMA SDK، موارد زیر را انجام دهید:
هدف-سی
IMA SDK را وارد کنید:
@import GoogleInteractiveMediaAds;متغیرهایی برای کلاسهای
IMAAdsLoader،IMAAVPlayerContentPlayheadوIMAAdsManagerکه در برنامه استفاده میشوند، ایجاد کنید:// 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;
سویفت
IMA SDK را وارد کنید:
import GoogleInteractiveMediaAdsمتغیرهایی برای کلاسهای
IMAAdsLoader،IMAAVPlayerContentPlayheadوIMAAdsManagerکه در برنامه استفاده میشوند، ایجاد کنید: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) }()
۵. ردیاب پخش محتوا و ناظر پایان پخش را پیادهسازی کنید
برای پخش تبلیغات میانپرده، IMA SDK باید موقعیت فعلی محتوای ویدیوی شما را ردیابی کند. برای انجام این کار، کلاسی ایجاد کنید که IMAContentPlayhead را پیادهسازی کند. اگر از AVPlayer استفاده میکنید، همانطور که در این مثال نشان داده شده است، SDK کلاس IMAAVPlayerContentPlayhead را ارائه میدهد که این کار را برای شما انجام میدهد. اگر AVPlayer استفاده نمیکنید، باید IMAContentPlayhead روی کلاس خودتان پیادهسازی کنید.
همچنین باید به SDK اطلاع دهید که چه زمانی پخش محتوای شما تمام شده است تا بتواند تبلیغات پس از پخش را نمایش دهد. این کار را با فراخوانی متد contentComplete در IMAAdsLoader و با استفاده از AVPlayerItemDidPlayToEndTimeNotification انجام دهید.
هدف-سی
نمونهی IMAAVPlayerContentPlayhead را در تنظیمات پخشکننده ایجاد کنید:
// 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];
متد contentDidFinishPlaying() را برای فراخوانی 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];
}
}
سویفت
ناظر محتوا را در تنظیمات پخشکننده ایجاد کنید:
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
متد contentDidFinishPlaying() را برای فراخوانی 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()
}
}
۶. بارگذاری تبلیغات را راهاندازی اولیه کنید و درخواست تبلیغات ارسال کنید
برای درخواست مجموعهای از تبلیغات، باید یک نمونه IMAAdsLoader ایجاد کنید. این لودر، اشیاء IMAAdsRequest مرتبط با یک URL تگ تبلیغ مشخص شده را پردازش میکند.
به عنوان یک روش بهتر، فقط یک نمونه از IMAAdsLoader را برای کل چرخه حیات برنامه خود نگه دارید. برای ایجاد درخواستهای تبلیغاتی بیشتر، یک شیء IMAAdsRequest جدید ایجاد کنید، اما از همان IMAAdsLoader دوباره استفاده کنید. برای اطلاعات بیشتر، به سوالات متداول IMA SDK مراجعه کنید.
هدف-سی
- (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];
}
سویفت
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)
}
۷. یک نماینده بارگذاری تبلیغات تنظیم کنید
در یک رویداد بارگذاری موفق، IMAAdsLoader متد adsLoadedWithData از نماینده اختصاص داده شده خود را فراخوانی میکند و نمونهای از IMAAdsManager را به آن ارسال میکند. سپس میتوانید مدیر تبلیغات را مقداردهی اولیه کنید که تبلیغات منفرد را بارگذاری میکند، همانطور که توسط پاسخ به URL تگ تبلیغ تعریف شده است.
علاوه بر این، حتماً هرگونه خطایی را که ممکن است در طول فرآیند بارگیری رخ دهد، مدیریت کنید. اگر تبلیغات بارگیری نشدند، مطمئن شوید که پخش رسانه بدون تبلیغات ادامه مییابد تا در تجربه کاربر اختلال ایجاد نشود.
هدف-سی
- (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];
}
سویفت
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()
}
۸. یک نماینده برای مدیریت تبلیغات تعیین کنید
در نهایت، برای مدیریت رویدادها و تغییرات وضعیت، مدیر تبلیغات به یک نماینده (delegate) مخصوص به خود نیاز دارد. IMAAdManagerDelegate متدهایی برای مدیریت رویدادها و خطاهای تبلیغات و همچنین متدهایی برای شروع پخش و مکث محتوای ویدیوی شما دارد.
شروع پخش
برای شروع پخش محتوا و تبلیغات، به رویداد LOADED گوش دهید. برای جزئیات بیشتر، به didReceiveAdEvent مراجعه کنید.
هدف-سی
- (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];
}
}
سویفت
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()
}
}
مدیریت خطاها
یک کنترلکننده برای خطاهای تبلیغات نیز اضافه کنید. در صورت بروز خطا، مانند مرحله قبل، پخش محتوا را از سر بگیرید.
هدف-سی
- (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];
}
سویفت
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()
}
به رویدادهای پخش و مکث گوش دهید
دو متد آخر برای پیادهسازی رویدادهای پخش و مکث روی محتوای ویدیویی اصلی، زمانی که IMA SDK درخواست میکند، مورد نیاز هستند. فعال کردن مکث و پخش در صورت درخواست، مانع از این میشود که کاربر هنگام نمایش تبلیغات، بخشهایی از محتوای ویدیو را از دست بدهد.
هدف-سی
- (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];
}
سویفت
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()
}
همین! شما اکنون با استفاده از IMA SDK درخواست و نمایش تبلیغات میدهید. برای کسب اطلاعات بیشتر در مورد ویژگیهای اضافی SDK، به راهنماهای دیگر یا نمونههای موجود در GitHub مراجعه کنید.
مراحل بعدی
برای به حداکثر رساندن درآمد حاصل از تبلیغات در پلتفرم iOS، از بخش شفافیت و ردیابی برنامه، مجوز استفاده از IDFA را درخواست کنید .