راه‌اندازی با «درج آگهی پویا» با خدمات کامل

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

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

نمای کلی IMA DAI

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

  • IMAAdDisplayContainer – شیء نگهدارنده‌ای که روی عنصر بازپخش ویدیو قرار می‌گیرد و عناصر میانای کاربر آگهی را در خود جای می‌دهد.
  • IMAAdsLoader – شیئی که درخواست جاری‌سازی می‌کند و رویدادهای راه‌اندازی‌شده توسط اشیای پاسخ درخواست جاری‌سازی را مدیریت می‌کند. باید فقط یک بارگذارنده آگهی را نمونه‌سازی کنید که بتواند درطول عمر برنامه دوباره استفاده شود.
  • IMAStreamRequest – یا IMAVODStreamRequest یا IMALiveStreamRequest. شیئی که درخواست جاری‌سازی را تعریف می‌کند. درخواست‌های جاری‌سازی می‌تواند برای ویدیو به‌درخواست یا جاری‌سازی زنده باشد. درخواست‌های جاری‌سازی زنده کلید دارایی را مشخص می‌کنند، درحالی‌که درخواست‌های VOD شناسه CMS و شناسه ویدیو را مشخص می‌کنند. هر دو نوع درخواست می‌توانند به‌طور اختیاری شامل یک کلید API باشند که برای دسترسی به جریان‌های مشخص‌شده لازم است، و یک کد شبکه Google Ad Manager برای IMA SDK تا شناسه‌های تبلیغات را طبق تنظیمات Google Ad Manager مدیریت کند.
  • IMAStreamManager – شیئی که جریان‌های درج آگهی پویا و تعاملات با پس‌بخش DAI را مدیریت می‌کند. مدیر جاری‌سازی همچنین پینگ‌های ردیابی را مدیریت می‌کند و رویدادهای جاری‌سازی و آگهی را به ناشر بازارسال می‌کند.

پیش‌نیازها

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

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

پارامترهای جاری‌سازی زنده
کلید دارایی کلید دارایی که جاری‌سازی زنده شما را در Google Ad Manager شناسایی می‌کند.
مثال: c-rArva4ShKVIAkNfy6HUQ
پارامترهای جاری‌سازی ویدیو به‌درخواست
شناسه منبع محتوا شناسه منبع محتوا از Google Ad Manager.
مثال: 2548831
شناسه ویدیو شناسه ویدیو از «مدیر Google Ads».
مثال: tears-of-steel
پارامترهای رایج (ویدیو به‌درخواست و جاری‌سازی زنده)
کد شبکه کد شبکه Google Ad Manager شما.
مثال: 21775744923

ایجاد پروژه Xcode جدید

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

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

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

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

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

  1. در Xcode، بسته IMA DAI SDK Swift را نصب کنید: به File > Add Packages بروید.

  2. در پیام‌واره‌ای که ظاهر می‌شود، مخزن GitHub بسته Swift مربوط به IMA DAI SDK را جستجو کنید:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

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

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

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

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

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

پخش‌کننده ویدیو را در کنترل‌کننده نمای اصلی‌تان پیاده‌سازی کنید؛ پخش‌کننده AV را در نمای واسط کاربر قرار دهید. کیت توسعه نرم‌افزار IMA از نمای میانای کاربر برای نمایش عناصر میانای کاربر آگهی استفاده می‌کند.

آبجکتیو-سی

#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end

Swift

// Copyright 2024 Google LLC. All rights reserved.
//
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under
// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
// ANY KIND, either express or implied. See the License for the specific language governing
// permissions and limitations under the License.

import AVFoundation
import UIKit

class ViewController: UIViewController {

  /// Content URL.
  static let backupStreamURLString =
    "http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8"

  /// Play button.
  @IBOutlet private weak var playButton: UIButton!

  @IBOutlet private weak var videoView: UIView!
  /// Video player.
  private var videoPlayer: AVPlayer?

  override func viewDidLoad() {
    super.viewDidLoad()

    playButton.layer.zPosition = CGFloat(MAXFLOAT)

    // Load AVPlayer with path to our content.
    // note: this unwrap is safe because the URL is a constant string.
    let contentURL = URL(string: ViewController.backupStreamURLString)!
    videoPlayer = AVPlayer(url: contentURL)

    // Create a player layer for the player.
    let playerLayer = AVPlayerLayer(player: videoPlayer)

    // Size, position, and display the AVPlayer.
    playerLayer.frame = videoView.layer.bounds
    videoView.layer.addSublayer(playerLayer)
  }

  @IBAction func onPlayButtonTouch(_ sender: Any) {
    videoPlayer?.play()
    playButton.isHidden = true
  }
}

راه‌اندازی بارکننده آگهی

«کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی» را به کنترل‌کننده نمای خود وارد کنید و پروتکل‌های IMAAdsLoaderDelegate و IMAStreamManagerDelegate را برای مدیریت رویدادهای بارکننده آگهی و مدیر جاری‌سازی اتخاذ کنید.

این ویژگی‌های خصوصی را برای ذخیره کردن مؤلفه‌های کلیدی کیت توسعه نرم‌افزار IMA اضافه کنید:

  • IMAAdsLoader
    • درخواست‌های جاری‌سازی را در طول عمر برنامه‌تان مدیریت می‌کند.
  • IMAAdDisplayContainer
    • مدیریت درج و مدیریت عناصر میانای کاربر آگهی.
  • IMAAVPlayerVideoDisplay - بین کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی و پخش‌کننده رسانه شما ارتباط برقرار می‌کند و فراداده‌های زمان‌بندی‌شده را مدیریت می‌کند.
  • IMAStreamManager - بازپخش جاری‌سازی را مدیریت می‌کند و رویدادهای مرتبط با آگهی را فعال می‌کند.

بارکننده آگهی، محفظه نمایش آگهی، و نمایش ویدیو را پس‌از بار شدن نما مقداردهی اولیه کنید.

آبجکتیو-سی

@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}

Swift

import GoogleInteractiveMediaAds
// ...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAStreamManagerDelegate {
  // ...

  /// The entry point for the IMA DAI SDK to make DAI stream requests.
  private var adsLoader: IMAAdsLoader?
  /// The container where the SDK renders each ad's user interface elements and companion slots.
  private var adDisplayContainer: IMAAdDisplayContainer?
  /// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
  /// metadata.
  private var imaVideoDisplay: IMAAVPlayerVideoDisplay!
  /// References the stream manager from the IMA DAI SDK after successfully loading the DAI stream.
  private var streamManager: IMAStreamManager?

  // ...

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    adsLoader = IMAAdsLoader(settings: nil)
    adsLoader?.delegate = self

    // Create an ad display container for rendering ad UI elements and the companion ad.
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: videoView,
      viewController: self,
      companionSlots: nil)

    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    imaVideoDisplay = IMAAVPlayerVideoDisplay(avPlayer: videoPlayer)
  }

درخواست جاری‌سازی

وقتی کاربر دکمه پخش را فشار می‌دهد، درخواست جاری‌سازی جدیدی ایجاد کنید. از کلاس IMALiveStreamRequest برای جاری‌سازی‌های زنده استفاده کنید. برای جاری‌سازی‌های «ویدیو به‌درخواست»، از کلاس IMAVODStreamRequest استفاده کنید.

درخواست جاری‌سازی به پارامترهای جاری‌سازی شما و همچنین ارجاع به محفظه نمایش آگهی و نمایش ویدیو شما نیاز دارد.

آبجکتیو-سی

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the asset key with your value.
    IMALiveStreamRequest *request =
        [[IMALiveStreamRequest alloc] initWithAssetKey:kLiveStreamAssetKey
                                           networkCode:kNetworkCode
                                    adDisplayContainer:self.adDisplayContainer
                                          videoDisplay:self.imaVideoDisplay
                                           userContext:nil];
    request.useHLSInterstitials = YES;
    [self.adsLoader requestStreamWithRequest:request];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    IMAVODStreamRequest *request =
        [[IMAVODStreamRequest alloc] initWithContentSourceID:kVODContentSourceID
                                                     videoID:kVODVideoID
                                                 networkCode:kNetworkCode
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
    [self.adsLoader requestStreamWithRequest:request];
  }
}

Swift

@IBAction func onPlayButtonTouch(_ sender: Any) {
  requestStream()
  playButton.isHidden = true
}

func requestStream() {
  // Create a stream request. Use one of "Livestream request" or "VOD request".
  if ViewController.requestType == StreamType.live {
    // Livestream request.
    let request = IMALiveStreamRequest(
      assetKey: ViewController.assetKey,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    request.useHLSInterstitials = true
    adsLoader?.requestStream(with: request)
  } else {
    // VOD stream request.
    let request = IMAVODStreamRequest(
      contentSourceID: ViewController.contentSourceID,
      videoID: ViewController.videoID,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  }
}

گوش دادن به رویدادهای بار کردن جاری‌سازی

کلاس IMAAdsLoader روش‌های IMAAdsLoaderDelegate را درصورت موفقیت یا عدم موفقیت راه‌اندازی درخواست جاری‌سازی فراخوانی می‌کند.

در روش نماینده adsLoadedWithData، IMAStreamManagerDelegate خود را تنظیم کنید. مدیر جاری‌سازی را مقداردهی اولیه کنید. در مقداردهی اولیه، مدیر جاری‌سازی بازپخش را شروع می‌کند.

در روش نماینده failedWithErrorData ، خطا را ثبت کنید. درصورت تمایل، جاری‌سازی پشتیبان را پخش کنید. روال‌های مطلوب درج آگهی پویا را ببینید.

آبجکتیو-سی

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  print("DAI stream loaded. Stream session ID: \(adsLoadedData.streamManager!.streamId!)")
  streamManager = adsLoadedData.streamManager!
  streamManager!.delegate = self
  streamManager!.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading DAI stream. Error message: \(adErrorData.adError.message!)")
  // Play the backup stream.
  videoPlayer.play()
}

گوش دادن به رویدادهای آگهی

IMAStreamManager روش‌های IMAStreamManagerDelegate را برای ارسال رویدادها و خطاهای جاری‌سازی به برنامه‌تان فراخوانی می‌کند.

برای این مثال، رویدادهای آگهی اصلی را در کنسول ثبت کنید:

آبجکتیو-سی

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"Ad event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %ld/%ld, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %ld, time offset: %lf, max duration: %lf.",
                         (long)event.ad.adPodInfo.adPosition, (long)event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType,
                         (long)event.ad.adPodInfo.podIndex, event.ad.adPodInfo.timeOffset,
                         event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}

Swift

func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("Ad event \(event.typeString).")
  switch event.type {
  case IMAAdEventType.STARTED:
    // Log extended data.
    if let ad = event.ad {
      let extendedAdPodInfo = String(
        format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
          + "description: %@, contentType:%@, pod index: %zd, "
          + "time offset: %lf, max duration: %lf.",
        ad.adPodInfo.adPosition,
        ad.adPodInfo.totalAds,
        ad.adPodInfo.isBumper ? "YES" : "NO",
        ad.adTitle,
        ad.adDescription,
        ad.contentType,
        ad.adPodInfo.podIndex,
        ad.adPodInfo.timeOffset,
        ad.adPodInfo.maxDuration)

      print("\(extendedAdPodInfo)")
    }
    break
  case IMAAdEventType.AD_BREAK_STARTED:
    print("Ad break started.")
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    print("Ad break ended.")
    break
  case IMAAdEventType.AD_PERIOD_STARTED:
    print("Ad period started.")
    break
  case IMAAdEventType.AD_PERIOD_ENDED:
    print("Ad period ended.")
    break
  default:
    break
  }
}

func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
  print("StreamManager error with type: \(error.type)")
  print("code: \(error.code)")
  print("message: \(error.message ?? "Unknown Error")")
}

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