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

انتخاب پلاتفرم: 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، بااستفاده از Objective-C یا Swift پروژه iOS جدیدی ایجاد کنید. از BasicExample به‌عنوان نام پروژه استفاده کنید.

۲. افزودن IMA SDK به پروژه Xcode

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

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

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

  1. در Xcode، «بسته Swift کیت توسعه نرم‌افزار IMA» را با پیمایش به File (فایل) > Add Package Dependencies… (افزودن وابستگی‌های بسته…) نصب کنید.

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

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

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

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

اگر نمی‌خواهید از «مدیر بسته Swift» استفاده کنید، «کیت توسعه نرم‌افزار IMA» را بارگیری کنید و به‌صورت دستی به پروژه‌تان اضافه کنید.

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

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

آبجکتیو-سی

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

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

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

برای وارد کردن «کیت توسعه نرم‌افزار IMA»، کارهای زیر را انجام دهید:

آبجکتیو-سی

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

۵. پیاده‌سازی ردیاب سرصفحه محتوا و ناظر پایان جاری‌سازی

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

آبجکتیو-سی

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