IMA SDK ادغام تبلیغات چندرسانه ای را در وب سایت ها و برنامه های شما آسان می کند. IMA SDK میتواند از هر سرور تبلیغاتی سازگار با VAST آگهی درخواست کند و پخش آگهی را در برنامههای شما مدیریت کند. با SDK های سمت سرویس گیرنده IMA، کنترل پخش ویدیوی محتوا را حفظ می کنید، در حالی که SDK پخش آگهی را کنترل می کند. تبلیغات در یک پخش کننده ویدیوی جداگانه که در بالای پخش کننده ویدیوی محتوای برنامه قرار دارد پخش می شود.
این راهنما نحوه ادغام IMA SDK را در یک برنامه پخش کننده ویدیوی ساده نشان می دهد. اگر میخواهید نمونه یکپارچهسازی کامل شده را مشاهده یا دنبال کنید، BasicExample را از GitHub دانلود کنید.
نمای کلی سمت مشتری IMA
پیاده سازی سمت مشتری IMA شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده است:
-
IMAAdDisplayContainer
: یک شی کانتینری که در آن تبلیغات رندر می شوند. -
IMAAdsLoader
: شییی که درخواست تبلیغات می کند و رویدادها را از پاسخ های درخواست تبلیغات مدیریت می کند. شما باید فقط یک بارکننده تبلیغات را نمونه برداری کنید، که می تواند در طول عمر برنامه مجددا استفاده شود. -
IMAAdsRequest
: یک شی که یک درخواست تبلیغات را تعریف می کند. درخواستهای تبلیغات نشانی اینترنتی تگ تبلیغات VAST و همچنین پارامترهای اضافی مانند ابعاد آگهی را مشخص میکنند. -
IMAAdsManager
: شیئی که حاوی پاسخ به درخواست تبلیغات است، پخش آگهی را کنترل می کند و به رویدادهای تبلیغاتی که توسط SDK اجرا می شود گوش می دهد.
پیش نیازها
قبل از شروع به موارد زیر نیاز دارید:
- Xcode 13 یا بالاتر
- CocoaPods (ترجیحا)، مدیریت بسته Swift، یا یک کپی دانلود شده از IMA SDK برای iOS
1. یک پروژه Xcode جدید ایجاد کنید
در Xcode، با استفاده از Objective-C یا Swift یک پروژه جدید iOS ایجاد کنید. از BasicExample به عنوان نام پروژه استفاده کنید.
2. IMA SDK را به پروژه Xcode اضافه کنید
SDK را با استفاده از CocoaPods نصب کنید (توصیه می شود)
CocoaPods یک مدیر وابستگی برای پروژه های Xcode است و روش توصیه شده برای نصب IMA SDK است. برای اطلاعات بیشتر در مورد نصب یا استفاده از CocoaPods، به مستندات CocoaPods مراجعه کنید. هنگامی که CocoaPods را نصب کردید، از دستورالعمل های زیر برای نصب IMA SDK استفاده کنید:
در همان پوشه فایل BasicExample.xcodeproj خود، یک فایل متنی به نام Podfile ایجاد کنید و پیکربندی زیر را اضافه کنید:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '14' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0' end
از دایرکتوری حاوی Podfile،
pod install --repo-update
اجرا کنیدبا باز کردن فایل BasicExample.xcworkspace و تأیید اینکه حاوی دو پروژه است، تأیید کنید که نصب با موفقیت انجام شده است: BasicExample و Pods (وابستگی های نصب شده توسط CocoaPods).
SDK را با استفاده از Swift Package Manager نصب کنید
Interactive Media Ads SDK از Swift Package Manager با شروع نسخه 3.18.4 پشتیبانی می کند. برای وارد کردن بسته سوئیفت مراحل زیر را دنبال کنید.
در Xcode، بسته IMA SDK Swift را با رفتن به File > Add Packages... نصب کنید.
در اعلان ظاهر شده، مخزن IMA SDK Swift Package GitHub را جستجو کنید:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
نسخه بسته IMA SDK Swift را که می خواهید استفاده کنید انتخاب کنید. برای پروژههای جدید، توصیه میکنیم از نسخه اصلی تا بعدی استفاده کنید.
پس از اتمام کار، Xcode وابستگی های بسته شما را برطرف می کند و آنها را در پس زمینه دانلود می کند. برای جزئیات بیشتر در مورد نحوه افزودن وابستگی های بسته، به مقاله اپل مراجعه کنید.
SDK را به صورت دستی دانلود و نصب کنید
اگر نمی خواهید از Swift Package Manager یا CocoaPods استفاده کنید، می توانید IMA SDK را دانلود کرده و به صورت دستی آن را به پروژه خود اضافه کنید.
3. یک پخش کننده ویدیوی ساده ایجاد کنید
ابتدا یک پخش کننده ویدیوی اصلی را پیاده سازی کنید. در ابتدا، این پخش کننده از IMA SDK استفاده نمی کند و هنوز هیچ روشی برای شروع پخش ندارد.
ViewController.m
هدف-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
سویفت
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 را وارد کنید
سپس، چارچوب IMA را با استفاده از عبارت import در زیر واردات موجود اضافه کنید.
ViewController.m
هدف-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";
سویفت
import AVFoundation import GoogleInteractiveMediaAds import UIKit class ViewController: UIViewController { static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
5. ردیاب هد پخش محتوا و ناظر پایان جریان را پیاده سازی کنید
برای پخش تبلیغات میان فیلم، IMA SDK باید موقعیت فعلی محتوای ویدیوی شما را ردیابی کند. برای انجام این کار، کلاسی ایجاد کنید که IMAContentPlayhead
پیاده سازی کند. اگر از یک AVPlayer
استفاده می کنید، همانطور که در این مثال نشان داده شده است، SDK کلاس IMAAVPlayerContentPlayhead
را ارائه می دهد که این کار را برای شما انجام می دهد. اگر از AVPlayer
استفاده نمی کنید، باید IMAContentPlayhead
در کلاس خود پیاده سازی کنید.
همچنین باید به SDK اطلاع دهید که پخش محتوای شما تمام شده است تا بتواند تبلیغات پس از پخش را نمایش دهد. این کار با فراخوانی contentComplete
در IMAAdsLoader
و با استفاده از AVPlayerItemDidPlayToEndTimeNotification
انجام می شود.
ViewController.m
هدف-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
سویفت
... 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. تبلیغات لودر را راه اندازی کنید و یک درخواست تبلیغات بدهید
برای درخواست مجموعه ای از تبلیغات، باید یک نمونه IMAAdsLoader
ایجاد کنید. این لودر را می توان برای پردازش اشیاء IMAAdsRequest
مرتبط با URL تگ تبلیغاتی مشخص استفاده کرد.
به عنوان بهترین روش، فقط یک نمونه از IMAAdsLoader
برای کل چرخه عمر برنامه خود حفظ کنید. برای درخواست تبلیغات اضافی، یک شی IMAAdsRequest
جدید ایجاد کنید، اما دوباره از همان IMAAdsLoader
استفاده کنید. برای اطلاعات بیشتر، سؤالات متداول IMA SDK را ببینید.
ViewController.m
هدف-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
سویفت
... 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. یک نماینده لودر تبلیغات تنظیم کنید
در یک رویداد بارگیری موفق، IMAAdsLoader
متد adsLoadedWithData
نماینده اختصاص داده شده خود را فراخوانی می کند و نمونه ای از IMAAdsManager
را به آن ارسال می کند. سپس میتوانید مدیر تبلیغات را مقداردهی اولیه کنید، که آگهیهای فردی را بارگیری میکند، همانطور که توسط پاسخ به URL برچسب آگهی تعریف شده است.
علاوه بر این، مطمئن شوید که با خطاهایی که ممکن است در طول فرآیند بارگذاری رخ دهد، رسیدگی کنید. اگر تبلیغات بارگیری نمیشوند، مطمئن شوید که پخش رسانه بدون تبلیغات ادامه مییابد تا در تجربه کاربر اختلال ایجاد نشود.
ViewController.m
هدف-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
سویفت
... 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. یک نماینده مدیر تبلیغات راه اندازی کنید
در نهایت، برای مدیریت رویدادها و تغییرات وضعیت، مدیر تبلیغات به نماینده خود نیاز دارد. IMAAdManagerDelegate
روش هایی برای مدیریت رویدادها و خطاهای تبلیغاتی و همچنین روش هایی برای فعال کردن پخش و توقف محتوای ویدیوی شما دارد.
شروع پخش
رویدادهای زیادی وجود دارد که می توان از روش didReceiveAdEvent
برای رسیدگی به آنها استفاده کرد، اما برای این مثال اساسی، به سادگی به رویداد LOADED
گوش دهید تا به مدیر تبلیغات بگویید پخش محتوا و تبلیغات را شروع کند.
ViewController.m
هدف-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]; } } ...
سویفت
... 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() } } ...
رسیدگی به خطاها
یک کنترل کننده برای خطاهای تبلیغاتی نیز اضافه کنید. اگر خطایی رخ داد، مانند مرحله قبل، پخش محتوا را از سر بگیرید.
ViewController.m
هدف-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
سویفت
... func adsManager(_ adsManager: IMAAdsManager!, didReceive error: IMAAdError!) { // Fall back to playing content print("AdsManager error: " + error.message) showContentPlayer() playerViewController.player?.play() }
فعال کردن رویدادهای پخش و توقف
در صورت درخواست IMA SDK، از دو روش آخری که باید پیادهسازی کنید، برای فعال کردن پخش و توقف رویدادها در محتوای ویدیویی زیربنایی استفاده میشود. ایجاد مکث و پخش در صورت درخواست باعث میشود کاربر نتواند بخشهایی از محتوای ویدیویی را هنگام نمایش تبلیغات از دست بدهد.
ViewController.m
هدف-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
سویفت
... 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() } }
همین! اکنون در حال درخواست و نمایش تبلیغات با IMA SDK هستید. برای آشنایی با ویژگیهای اضافی SDK، به سایر راهنماها یا نمونههای موجود در GitHub مراجعه کنید.
مراحل بعدی
برای به حداکثر رساندن درآمد تبلیغات در پلتفرم iOS، برای استفاده از IDFA مجوز شفافیت و ردیابی برنامه را درخواست کنید .