با IMA DAI SDK شروع کنید

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

راه حل DAI مورد علاقه خود را انتخاب کنید

خدمات کامل DAI

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

نمای کلی IMA DAI

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

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

پیش نیازها

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

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

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

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

برای نصب IMA DAI SDK از یکی از این سه روش استفاده کنید.

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

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

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

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.22.1'
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 DAI SDK Swift را با رفتن به File > Add Packages نصب کنید.

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

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

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

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

SDK را به صورت دستی دانلود و نصب کنید

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

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

ابتدا یک پخش کننده ویدیوی اصلی را پیاده سازی کنید. در ابتدا، این پخش‌کننده از IMA DAI 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

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

پس از اینکه IMA DAI 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

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

درخواست پخش جریانی بدهید

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

ViewController.m

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
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];
}

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

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

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
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

مدیریت ورود به سیستم و رویدادهای خطا

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

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 and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      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 DAI SDK هستید. برای آشنایی با ویژگی‌های پیشرفته‌تر SDK، به سایر راهنماها یا نمونه‌های موجود در GitHub مراجعه کنید.