شروع کنید

IMA SDK ادغام تبلیغات چندرسانه ای را در وب سایت ها و برنامه های شما آسان می کند. IMA SDK می‌تواند از هر سرور تبلیغاتی سازگار با VAST آگهی درخواست کند و پخش آگهی را در برنامه‌های شما مدیریت کند. با IMA DAI SDK، برنامه‌ها درخواست پخش جریانی برای آگهی و ویدیوی محتوا را ارائه می‌کنند - اعم از VOD یا محتوای زنده. سپس SDK یک جریان ویدیوی ترکیبی را برمی‌گرداند، به طوری که نیازی به مدیریت جابجایی بین آگهی و ویدیوی محتوا در برنامه خود ندارید.

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

نمای کلی IMA DAI

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

  • IMAAdDisplayContainer : یک شی کانتینری که در بالای عنصر پخش ویدیو قرار می گیرد و عناصر رابط کاربری تبلیغات را در خود جای می دهد.
  • IMAAdsLoader : شی‌ای که جریان‌ها را درخواست می‌کند و رویدادهای ایجاد شده توسط اشیاء پاسخ درخواست جریان را مدیریت می‌کند. شما باید فقط یک بارکننده تبلیغات را نمونه برداری کنید، که می تواند در طول عمر برنامه مجددا استفاده شود.
  • IMAStreamRequest – یک IMAVODStreamRequest یا یک IMALiveStreamRequest : یک شی که یک درخواست جریان را تعریف می کند. درخواست‌های جریان می‌تواند برای ویدیوی درخواستی یا پخش مستقیم باشد. درخواست ها یک شناسه محتوا و همچنین یک کلید API یا نشانه احراز هویت و سایر پارامترها را مشخص می کنند.
  • IMAStreamManager : شی‌ای که جریان‌های درج آگهی پویا و تعاملات با باطن DAI را مدیریت می‌کند. مدیر جریان همچنین پینگ‌های ردیابی را مدیریت می‌کند و جریان‌ها و رویدادهای تبلیغاتی را به ناشر ارسال می‌کند.

پیش نیازها

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

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

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

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

نصب SDK با استفاده از CocoaPods (ترجیحا)

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

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

    source 'https://github.com/CocoaPods/Specs.git'
platform :tvos, '10'
target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.2'
end

  2. از دایرکتوری حاوی Podfile، pod install --repo-update اجرا کنید

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

دانلود و نصب دستی SDK

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

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

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

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

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

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

4. SDK را وارد کنید و برای تعامل IMA، خرد اضافه کنید

هنگامی که IMA SDK را به پروژه خود اضافه کردید، SDK را وارد کنید و برای نقاط اصلی تعامل IMA، موارد خرد اضافه کنید.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

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

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

5. IMAAdsLoader را پیاده سازی کنید

سپس، IMAAdsLoader را نمونه‌سازی کنید و نمای کانتینر تبلیغات را به سلسله‌مراتب view وصل کنید.

ViewController.m

...
- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}
...

6. درخواست استریم کنید

چند ثابت برای نگهداری اطلاعات جریان ایجاد کنید و سپس تابع درخواست جریان را برای ایجاد درخواست پیاده سازی کنید.

ViewController.m

...
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}
...

7. رویدادهای جریان را مدیریت کنید

رویدادهای IMAAdsLoader و IMAStreamManager که برای مدیریت مقداردهی اولیه، خطاها و تغییرات در وضعیت جریان استفاده می‌شوند، آتش می‌زنند. این رویدادها از طریق پروتکل های IMAAdsLoaderDelegate و IMAStreamManagerDelegate فعال می شوند. به رویداد بارگذاری شده تبلیغات گوش دهید و جریان را مقداردهی کنید. اگر تبلیغی بارگیری نشد، به جای آن یک جریان پشتیبان پخش کنید.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}


#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}


#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

8. ورود به سیستم و رویدادهای خطا را مدیریت کنید

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

ViewController.m

...
#pragma mark - IMAStreamManagerDelegate

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts.
      self.playerViewController.requiresLinearPlayback = YES;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow users to seek through after an ad ends.
      self.playerViewController.requiresLinearPlayback = NO;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

خودشه! اکنون در حال درخواست و نمایش تبلیغات با IMA SDK هستید. برای آشنایی با ویژگی‌های پیشرفته‌تر SDK، به سایر راهنماها یا نمونه‌های موجود در GitHub مراجعه کنید.

مراحل بعدی

برای به حداکثر رساندن درآمد تبلیغات در پلتفرم tvOS، برای استفاده از IDFA مجوز شفافیت و ردیابی برنامه را درخواست کنید .