راه‌اندازی کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی

پلاتفرم را انتخاب کنید: HTML5 Android iOS tvOS

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

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

نمای کلی سمت کارخواه IMA

پیاده‌سازی IMA سمت کارخواه شامل چهار مؤلفه اصلی کیت توسعه نرم‌افزار است که این راهنما آن‌ها را نشان می‌دهد:

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

پیش‌نیازها

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

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

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

۲. افزودن کیت توسعه نرم‌افزار IMA به پروژه Xcode

برای نصب کردن «کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی»، روش ترجیحی را انتخاب کنید.

توصیه‌شده: نصب کیت توسعه نرم‌افزار بااستفاده از Swift Package Manager

کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی از نسخه ۳.۱۸.۴ به بعد از مدیر بسته Swift پشتیبانی می‌کند. برای وارد کردن بسته Swift، مراحل زیر را تکمیل کنید:

  1. در Xcode، با رفتن به File > Add Package Dependencies...‎، «بسته Swift کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی» را نصب کنید.

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

  3. نسخه «بسته IMA SDK Swift» را که می‌خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از Up to Next Major Version استفاده کنید.

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

بارگیری و نصب دستی کیت توسعه نرم‌افزار (SDK)

اگر نمی‌خواهید از Swift Package Manager استفاده کنید، 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;
}

Swift

وابستگی‌های پخش‌کننده را وارد کنید:

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

۴. وارد کردن کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی

برای وارد کردن کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی، کارهای زیر را انجام دهید:

آبجکتیو-سی

  1. وارد کردن کیت توسعه نرم‌افزار IMA:

    @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;
    

Swift

  1. وارد کردن کیت توسعه نرم‌افزار IMA:

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

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

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

همچنین باید به کیت توسعه نرم‌افزار اطلاع دهید که پخش محتوایتان چه زمانی تمام می‌شود تا بتواند آگهی‌های پایان پخش را نمایش دهد. این کار را با فراخوانی روش 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];
  }
}

Swift

ناظر پایان محتوا را در راه‌اندازی پخش‌کننده ایجاد کنید:

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 شیء مرتبط با نشانی وب برچسب آگهی مشخص‌شده را پردازش می‌کند.

به‌عنوان روال مطلوب، فقط یک نمونه از IMAAdsLoader را برای کل چرخه حیات برنامه‌تان حفظ کنید. برای ایجاد درخواست‌های آگهی بیشتر، شیء IMAAdsRequest جدیدی ایجاد کنید، اما از همان IMAAdsLoader مجدداً استفاده کنید. برای اطلاعات بیشتر، پرسشگان کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی را ببینید.

آبجکتیو-سی

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

‫۷. راه‌اندازی نماینده بارکننده آگهی

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

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

آبجکتیو-سی

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

‫۸. راه‌اندازی نماینده مدیر آگهی‌ها

درنهایت، برای مدیریت رویدادها و تغییرات وضعیت، مدیر آگهی‌ها به نماینده‌ای از خودش نیاز دارد. 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];
  }
}

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

مدیریت کردن خطاها

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

آبجکتیو-سی

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

گوش دادن به رویدادهای پخش و توقف موقت

دو روش نماینده آخری که باید پیاده‌سازی کنید، رویدادهای پخش و توقف موقت را در محتوای ویدیویی زیرین، زمانی که 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];
}

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

فقط همین! اکنون با کیت توسعه نرم‌افزار IMA آگهی درخواست و نمایش می‌دهید. برای آشنایی با ویژگی‌های دیگر کیت توسعه نرم‌افزار، به راهنماهای دیگر یا نمونه‌های موجود در GitHub مراجعه کنید.

مراحل بعدی

برای بیشینه‌سازی درآمد آگهی در پلاتفرم iOS، اجازه «شفاف‌سازی و ردیابی برنامه» را برای استفاده از IDFA درخواست کنید.