شروع کنید

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 اضافه کنید

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

  1. در همان پوشه فایل 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
    
  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 Packages... نصب کنید.

  2. در اعلان ظاهر شده، مخزن IMA SDK Swift Package GitHub را جستجو کنید:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
    
  3. نسخه بسته 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 مجوز شفافیت و ردیابی برنامه را درخواست کنید .