הגדרת IMA SDK ל-DAI

ערכות IMA SDK מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ‫IMA SDKs יכולים לשלוח בקשות למודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. באמצעות IMA DAI SDK, האפליקציות שולחות בקשה לסטרימינג של מודעות ותוכן וידאו – תוכן VOD או תוכן בשידור חי. לאחר מכן, ה-SDK מחזיר זרם וידאו משולב, כך שלא צריך לנהל את המעבר בין מודעה לתוכן וידאו באפליקציה.

בחירת פתרון DAI שמעניין אתכם

DAI בשירות מלא

במדריך הזה מוסבר איך לשלב את IMA DAI SDK באפליקציית נגן וידאו פשוטה. אם רוצים לראות או לעקוב אחרי שילוב לדוגמה, אפשר להוריד את BasicExample מ-GitHub.

סקירה כללית על IMA DAI

הטמעה של IMA DAI כוללת שלושה רכיבי SDK עיקריים, כפי שמוצג במדריך הזה:

  • IMAAdDisplayContainer: אובייקט מאגר שנמצא מעל רכיב הפעלת הווידאו ומכיל את רכיבי ממשק המשתמש של המודעה.
  • IMAAdsLoader: אובייקט שמבקש סטרימינג ומטפל באירועים שמופעלים על ידי אובייקטים של תגובות לבקשות סטרימינג. צריך ליצור רק מופע אחד של הכלי לטעינת מודעות, שאפשר לעשות בו שימוש חוזר לאורך כל חיי האפליקציה.
  • IMAStreamRequest – או IMAVODStreamRequest או IMALiveStreamRequest: אובייקט שמגדיר בקשה לשידור. בקשות לשידור יכולות להיות לווידאו על פי דרישה או לשידורים חיים. בבקשות לשידור חי מציינים מפתח נכס, ובבקשות ל-VOD מציינים מזהה CMS ומזהה סרטון. שני סוגי הבקשות יכולים לכלול אופציונלית מפתח API שנדרש כדי לגשת לסטרימינג שצוין, וקוד רשת של Google Ad Manager כדי ש-IMA SDK יטפל במזהי מודעות כמו שצוין בהגדרות של Google Ad Manager.
  • IMAStreamManager: אובייקט שמטפל בסטרימינג של הטמעת מודעות דינמיות ובאינטראקציות עם ה-Backend של DAI. מנהל השידור מטפל גם בפינגים למעקב ומעביר אירועים שקשורים לשידור ולמודעות אל בעל התוכן הדיגיטלי.

דרישות מוקדמות

לפני שמתחילים, צריך:

יצירת פרויקט חדש ב-Xcode

ב-Xcode, יוצרים פרויקט tvOS חדש באמצעות 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 :tvos, '14'
    target "BasicExample" do
      pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.15.1'
    end
    
  2. בספרייה שמכילה את קובץ ה-Podfile, מריצים את הפקודה:

    pod install --repo-update`
  3. כדי לוודא שההתקנה הצליחה, פותחים את הקובץ BasicExample.xcworkspace ומוודאים שהוא מכיל שני פרויקטים: BasicExample ו-Pods (התלויות שהותקנו על ידי CocoaPods).

התקנת ה-SDK באמצעות Swift Package Manager

החל מגרסה 4.8.2,‏ Interactive Media Ads SDK תומך ב-Swift Package Manager. כדי לייבא את חבילת Swift, פועלים לפי השלבים הבאים.

  1. ב-Xcode, מתקינים את חבילת GoogleInteractiveMediaAds Swift. לשם כך, עוברים אל File > Add Packages (קובץ > הוספת חבילות).

  2. בהודעה שמופיעה, מחפשים את מאגר GitHub של חבילת GoogleInteractiveMediaAds Swift:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. בוחרים את הגרסה של חבילת GoogleInteractiveMediaAds Swift שבה רוצים להשתמש. לפרויקטים חדשים, מומלץ להשתמש באפשרות עד הגרסה הראשית הבאה.

אחרי שתסיימו, פלטפורמת Xcode תטפל ביחסי התלות שבחבילה ותוריד אותם ברקע. לפרטים נוספים על הוספת תלות בחבילה, אפשר לעיין במאמר של Apple.

הורדה והתקנה של ה-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 ומוסיפים stub לאינטראקציה עם IMA

אחרי שמוסיפים את IMA DAI SDK לפרויקט, מייבאים את ה-SDK ומוסיפים stub לנקודות האינטראקציה העיקריות של 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 ומצרפים את תצוגת מאגר המודעות להיררכיית התצוגה.

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";
static NSString *const kNetworkCode = @"21775744923";

@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
                                                                     networkCode:kNetworkCode
                                                              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
  //                                              networkCode:kNetworkCode
  //                                       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 kNetworkCode = @"21775744923";
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.