IMA SDK را تنظیم کنید

شروع به کسب درآمد از محتوای ویدیوی خود با تبلیغات کرد.

IMA SDK ادغام تبلیغات چندرسانه ای را در وب سایت ها و برنامه های شما آسان می کند. IMA SDK می‌تواند از هر سرور تبلیغاتی سازگار با VAST آگهی درخواست کند و پخش آگهی را در برنامه‌های شما مدیریت کند. با SDK های سمت سرویس گیرنده IMA، کنترل پخش ویدیوی محتوا را حفظ می کنید، در حالی که SDK پخش آگهی را کنترل می کند. تبلیغات در یک پخش کننده ویدیوی جداگانه که در بالای پخش کننده ویدیوی محتوای برنامه قرار دارد پخش می شود.

این راهنما نحوه ادغام IMA SDK را در برنامه پخش کننده ویدیو نشان می دهد. اگر می‌خواهید نمونه یکپارچه‌سازی کامل شده را مشاهده یا دنبال کنید، BasicExample را از GitHub دانلود کنید.

نمای کلی سمت مشتری IMA

پیاده سازی سمت مشتری IMA شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده است:

  • IMAAdDisplayContainer : یک شی کانتینری که مشخص می‌کند IMA عناصر رابط کاربری تبلیغات را در کجا رندر می‌کند و قابلیت مشاهده را اندازه‌گیری می‌کند، از جمله نمایش فعال و اندازه‌گیری باز .
  • IMAAdsLoader : شییی که درخواست تبلیغات می کند و رویدادها را از پاسخ های درخواست تبلیغات مدیریت می کند. شما باید فقط یک بارکننده تبلیغات را نمونه برداری کنید، که می تواند در طول عمر برنامه مجددا استفاده شود.
  • IMAAdsRequest : یک شی که یک درخواست تبلیغات را تعریف می کند. درخواست‌های تبلیغات نشانی اینترنتی تگ تبلیغات VAST و همچنین پارامترهای اضافی مانند ابعاد آگهی را مشخص می‌کنند.
  • IMAAdsManager : شیئی که حاوی پاسخ به درخواست تبلیغات است، پخش آگهی را کنترل می کند و به رویدادهای تبلیغاتی که توسط SDK اجرا می شود گوش می دهد.

پیش نیازها

قبل از شروع به موارد زیر نیاز دارید:

  • Xcode 13 یا بالاتر
  • CocoaPods (ترجیحا)، مدیریت بسته Swift، یا یک کپی دانلود شده از IMA SDK برای iOS

1. یک پروژه Xcode جدید ایجاد کنید

در Xcode، با استفاده از Objective-C یا Swift یک پروژه جدید iOS ایجاد کنید. از BasicExample به عنوان نام پروژه استفاده کنید.

2. IMA SDK را به پروژه Xcode اضافه کنید

CocoaPods یک مدیر وابستگی برای پروژه های Xcode است و روش توصیه شده برای نصب IMA SDK است. برای اطلاعات بیشتر در مورد نصب یا استفاده از CocoaPods، به مستندات CocoaPods مراجعه کنید. هنگامی که CocoaPods را نصب کردید، از دستورالعمل های زیر برای نصب IMA SDK استفاده کنید:

  1. در همان پوشه فایل BasicExample.xcodeproj خود، یک فایل متنی به نام Podfile ایجاد کنید و پیکربندی زیر را اضافه کنید:

    هدف-C

    source 'https://github.com/CocoaPods/Specs.git'  platform :ios, '12'  target "BasicExample" do   pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end  

    سویفت

    source 'https://github.com/CocoaPods/Specs.git'  platform :ios, '12'  target "BasicExample" do   pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end  
  2. از دایرکتوری حاوی Podfile، pod install --repo-update اجرا کنید.

  3. با باز کردن فایل BasicExample.xcworkspace و تأیید اینکه حاوی دو پروژه است، تأیید کنید که نصب با موفقیت انجام شده است: BasicExample و Pods (وابستگی های نصب شده توسط CocoaPods).

SDK را با استفاده از Swift Package Manager نصب کنید

Interactive Media Ads SDK از Swift Package Manager با شروع نسخه 3.18.4 پشتیبانی می کند. برای وارد کردن بسته سوئیفت، مراحل زیر را انجام دهید:

  1. در Xcode، بسته IMA SDK Swift را با رفتن به File > Add Package Dependencies... نصب کنید.

  2. در اعلان، مخزن IMA iOS SDK Swift Package GitHub را جستجو کنید: swift-package-manager-google-interactive-media-ads-ios .

  3. نسخه بسته IMA SDK Swift را که می خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از نسخه اصلی تا بعدی استفاده کنید.

پس از اتمام کار، Xcode وابستگی های بسته شما را برطرف می کند و آنها را در پس زمینه دانلود می کند. برای جزئیات بیشتر در مورد نحوه افزودن وابستگی های بسته، به مقاله اپل مراجعه کنید.

SDK را به صورت دستی دانلود و نصب کنید

اگر نمی خواهید از Swift Package Manager یا CocoaPods استفاده کنید، می توانید IMA SDK را دانلود کرده و به صورت دستی آن را به پروژه خود اضافه کنید.

3. یک پخش کننده ویدیو ایجاد کنید

ابتدا یک پخش کننده ویدئو اجرا کنید. در ابتدا، این پخش کننده از IMA SDK استفاده نمی کند و هیچ روشی برای شروع پخش ندارد.

هدف-C

وابستگی های بازیکن را وارد کنید:

#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() } 

4. IMA SDK را وارد کنید

برای وارد کردن IMA SDK، موارد زیر را انجام دهید:

هدف-C

  1. وارد کردن IMA SDK:

    @import GoogleInteractiveMediaAds; 
  2. متغیرهایی را برای کلاس های 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; 

سویفت

  1. وارد کردن IMA SDK:

    import GoogleInteractiveMediaAds  
  2. متغیرهایی را برای کلاس های 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) }() 

5. ردیاب هد پخش محتوا و ناظر پایان جریان را پیاده سازی کنید

برای پخش تبلیغات میان فیلم، IMA SDK باید موقعیت فعلی محتوای ویدیوی شما را ردیابی کند. برای انجام این کار، کلاسی ایجاد کنید که IMAContentPlayhead را پیاده سازی کند. اگر از یک AVPlayer استفاده می کنید، همانطور که در این مثال نشان داده شده است، SDK کلاس IMAAVPlayerContentPlayhead را ارائه می دهد که این کار را برای شما انجام می دهد. اگر از AVPlayer استفاده نمی کنید، باید IMAContentPlayhead در کلاس خود پیاده سازی کنید.

همچنین باید به SDK اطلاع دهید که پخش محتوای شما تمام شده است تا بتواند تبلیغات پس از پخش را نمایش دهد. این کار با فراخوانی متد contentComplete در IMAAdsLoader، با استفاده از AVPlayerItemDidPlayToEndTimeNotification انجام می شود.

هدف-C

نمونه 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()   } } 

6. تبلیغات لودر را راه اندازی کنید و یک درخواست تبلیغات بدهید

برای درخواست مجموعه ای از تبلیغات، باید یک نمونه IMAAdsLoader ایجاد کنید. این لودر را می توان برای پردازش اشیاء IMAAdsRequest مرتبط با URL تگ تبلیغاتی مشخص استفاده کرد.

به عنوان بهترین روش، فقط یک نمونه از IMAAdsLoader برای کل چرخه عمر برنامه خود حفظ کنید. برای درخواست تبلیغات اضافی، یک شی IMAAdsRequest جدید ایجاد کنید، اما دوباره از همان IMAAdsLoader استفاده کنید. برای اطلاعات بیشتر، سؤالات متداول IMA SDK را ببینید.

هدف-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]; } 

سویفت

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. یک نماینده لودر تبلیغات تنظیم کنید

در یک رویداد بارگیری موفق، IMAAdsLoader متد adsLoadedWithData نماینده اختصاص داده شده خود را فراخوانی می کند و نمونه ای از IMAAdsManager را به آن ارسال می کند. سپس می‌توانید مدیر تبلیغات را مقداردهی اولیه کنید، که آگهی‌های فردی را بارگیری می‌کند، همانطور که توسط پاسخ به URL برچسب آگهی تعریف شده است.

علاوه بر این، مطمئن شوید که با خطاهایی که ممکن است در طول فرآیند بارگذاری رخ دهد، رسیدگی کنید. اگر تبلیغات بارگیری نمی‌شوند، مطمئن شوید که پخش رسانه بدون تبلیغات ادامه می‌یابد تا در تجربه کاربر اختلال ایجاد نشود.

هدف-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]; } 

سویفت

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. یک نماینده مدیر تبلیغات راه اندازی کنید

در نهایت، برای مدیریت رویدادها و تغییرات وضعیت، مدیر تبلیغات به نماینده خود نیاز دارد. IMAAdManagerDelegate روش هایی برای مدیریت رویدادها و خطاهای تبلیغاتی و همچنین روش هایی برای فعال کردن پخش و توقف محتوای ویدیوی شما دارد.

پخش را شروع کنید

برای شروع پخش محتوا و تبلیغات، به رویداد LOADED گوش دهید. برای جزئیات بیشتر، didReceiveAdEvent ببینید.

هدف-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];   } } 

سویفت

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()   } } 

رسیدگی به خطاها

یک کنترل کننده برای خطاهای تبلیغاتی نیز اضافه کنید. اگر خطایی رخ داد، مانند مرحله قبل، پخش محتوا را از سر بگیرید.

هدف-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]; } 

سویفت

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، از دو روش آخری که باید پیاده‌سازی کنید، برای فعال کردن پخش و توقف رویدادها در محتوای ویدیویی زیربنایی استفاده می‌شود. ایجاد مکث و پخش در صورت درخواست باعث می‌شود کاربر نتواند بخش‌هایی از محتوای ویدیویی را هنگام نمایش تبلیغات از دست بدهد.

هدف-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]; } 

سویفت

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 مجوز شفافیت و ردیابی برنامه را درخواست کنید .