הגדרת IMA SDK

בחירת פלטפורמה: HTML5 Android iOS tvOS

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

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

סקירה כללית על IMA בצד הלקוח

הטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמוסברים במדריך הזה:

  • IMAAdDisplayContainer: אובייקט מאגר שמציין איפה IMA מעבד רכיבי ממשק משתמש של מודעות ומודד את הניראות, כולל Active View ו-Open Measurement.
  • IMAAdsLoader: אובייקט שמבקש מודעות ומטפל באירועים מתגובות לבקשות מודעות. צריך ליצור רק מופע אחד של Ads Loader, שאפשר לעשות בו שימוש חוזר במהלך הפעילות של האפליקציה.
  • IMAAdsRequest: אובייקט שמגדיר בקשה להצגת מודעות. בבקשות להצגת מודעות מצוינת כתובת ה-URL של תג המודעה בפורמט VAST, וגם פרמטרים נוספים כמו מידות המודעה.
  • IMAAdsManager: אובייקט שמכיל את התגובה לבקשת המודעות, שולט בהפעלת המודעות ומאזין לאירועי מודעות שהופעלו על ידי ה-SDK.

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

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

  • ‫Xcode 13 ואילך
  • CocoaPods (מומלץ), Swift Package Manager או עותק להורדה של IMA SDK ל-iOS

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

ב-Xcode, יוצרים פרויקט iOS חדש באמצעות Objective-C או Swift. משתמשים ב-BasicExample כשם הפרויקט.

2. הוספת IMA SDK לפרויקט Xcode

‫CocoaPods הוא כלי לניהול יחסי תלות בפרויקטים של Xcode, והוא השיטה המומלצת להתקנת IMA SDK. מידע נוסף על התקנה או שימוש ב-CocoaPods מופיע במסמכי העזרה של CocoaPods. אחרי שמתקינים את CocoaPods, פועלים לפי ההוראות הבאות כדי להתקין את IMA SDK:

  1. באותה תיקייה שבה נמצא הקובץ BasicExample.xcodeproj, יוצרים קובץ טקסט בשם Podfile ומוסיפים את ההגדרות הבאות:

    Objective-C

    source 'https://github.com/CocoaPods/Specs.git'  platform :ios, '12'  target "BasicExample" do   pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end  

    Swift

    source 'https://github.com/CocoaPods/Specs.git'  platform :ios, '12'  target "BasicExample" do   pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end  
  2. בספרייה שמכילה את קובץ Podfile, מריצים את הפקודה pod install --repo-update.

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

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

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

  1. ב-Xcode, מתקינים את חבילת ה-Swift של IMA SDK על ידי מעבר אל File > Add Package Dependencies...‎ (קובץ > הוספת תלות בחבילה...).

  2. בחלון ההנחיה, מחפשים את מאגר IMA iOS SDK Swift Package GitHub: swift-package-manager-google-interactive-media-ads-ios.

  3. בוחרים את הגרסה של חבילת IMA SDK Swift שרוצים להשתמש בה. לפרויקטים חדשים, מומלץ להשתמש באפשרות עד הגרסה הראשית הבאה.

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

הורדה והתקנה של ה-SDK באופן ידני

אם אתם לא רוצים להשתמש ב-Swift Package Manager או ב-CocoaPods, אתם יכולים להוריד את IMA SDK ולהוסיף אותו לפרויקט באופן ידני.

3. יצירת נגן וידאו

קודם כול, מטמיעים נגן וידאו. בתחילה, נגן הווידאו הזה לא משתמש ב-IMA SDK ולא מכיל אף שיטה להפעלת התוכן.

Objective-C

מייבאים את יחסי התלות של הנגן:

#import "ViewController.h"  @import AVFoundation; 

מגדירים את משתני הנגן:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>  /// Content video player. @property(nonatomic, strong) AVPlayer *contentPlayer;  /// Play button. @property(nonatomic, weak) IBOutlet UIButton *playButton;  /// UIView in which we will render our AVPlayer for content. @property(nonatomic, weak) IBOutlet UIView *videoView; 

הפעלת נגן הווידאו כשהתצוגה נטענת:

@implementation ViewController  // The content URL to play. NSString *const kTestAppContentUrl_MP4 =     @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";  // Ad tag NSString *const kTestAppAdTagUrl = @"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&"   @"correlator=";  - (void)viewDidLoad {   [super viewDidLoad];    self.playButton.layer.zPosition = MAXFLOAT;    [self setupAdsLoader];   [self setUpContentPlayer]; }  #pragma mark Content Player Setup  - (void)setUpContentPlayer {   // Load AVPlayer with path to our content.   NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];   self.contentPlayer = [AVPlayer playerWithURL:contentURL];    // Create a player layer for the player.   AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];    // Size, position, and display the AVPlayer.   playerLayer.frame = self.videoView.layer.bounds;   [self.videoView.layer addSublayer:playerLayer];    // Set up our content playhead and contentComplete callback.   self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];   [[NSNotificationCenter defaultCenter] addObserver:self                                            selector:@selector(contentDidFinishPlaying:)                                                name:AVPlayerItemDidPlayToEndTimeNotification                                              object:self.contentPlayer.currentItem]; }  - (IBAction)onPlayButtonTouch:(id)sender {   [self requestAds];   self.playButton.hidden = YES; } 

Swift

מייבאים את יחסי התלות של הנגן:

import AVFoundation 

מגדירים את משתני הנגן:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {   static let contentURL = URL(     string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!    private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)    private lazy var playerLayer: AVPlayerLayer = {     AVPlayerLayer(player: contentPlayer)   }() 

הפעלת נגן הווידאו כשהתצוגה נטענת:

private lazy var videoView: UIView = {   let videoView = UIView()   videoView.translatesAutoresizingMaskIntoConstraints = false   view.addSubview(videoView)    NSLayoutConstraint.activate([     videoView.bottomAnchor.constraint(       equalTo: view.safeAreaLayoutGuide.bottomAnchor),     videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),     videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),     videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),   ])   return videoView }()  // MARK: - View controller lifecycle methods  override func viewDidLoad() {   super.viewDidLoad()    videoView.layer.addSublayer(playerLayer)   adsLoader.delegate = self    NotificationCenter.default.addObserver(     self,     selector: #selector(contentDidFinishPlaying(_:)),     name: .AVPlayerItemDidPlayToEndTime,     object: contentPlayer.currentItem) }  override func viewDidAppear(_ animated: Bool) {   super.viewDidAppear(animated)   playerLayer.frame = videoView.layer.bounds }  override func viewWillTransition(   to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator ) {   coordinator.animate { _ in     // do nothing   } completion: { _ in     self.playerLayer.frame = self.videoView.layer.bounds   } }  // MARK: - Public methods  func playButtonPressed() {   requestAds() } 

4. ייבוא של IMA SDK

כדי לייבא את IMA SDK:

Objective-C

  1. מייבאים את IMA SDK:

    @import GoogleInteractiveMediaAds; 
  2. יוצרים משתנים עבור המחלקות IMAAdsLoader, IMAAVPlayerContentPlayhead ו-IMAAdsManager שמשמשות באפליקציה:

    // SDK /// Entry point for the SDK. Used to make ad requests. @property(nonatomic, strong) IMAAdsLoader *adsLoader;  /// Playhead used by the SDK to track content video progress and insert mid-rolls. @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;  /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request. @property(nonatomic, strong) IMAAdsManager *adsManager; 

Swift

  1. מייבאים את IMA SDK:

    import GoogleInteractiveMediaAds  
  2. יוצרים משתנים עבור המחלקות IMAAdsLoader, IMAAVPlayerContentPlayhead ו-IMAAdsManager שמשמשות באפליקציה:

    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&correlator="  private let adsLoader = IMAAdsLoader() private var adsManager: IMAAdsManager?  private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {   IMAAVPlayerContentPlayhead(avPlayer: contentPlayer) }() 

5. הטמעה של כלי למעקב אחר מיקום ההפעלה של תוכן ושל כלי למעקב אחר סיום הסטרימינג

כדי להציג מודעות באמצע הסרטון (mid-roll), ערכת IMA SDK צריכה לעקוב אחרי המיקום הנוכחי של תוכן הווידאו. כדי לעשות זאת, יוצרים מחלקה שמטמיעה את IMAContentPlayhead. אם אתם משתמשים ב-AVPlayer, כמו בדוגמה הזו, ה-SDK מספק את המחלקה IMAAVPlayerContentPlayhead שמבצעת את הפעולה הזו בשבילכם. אם אתם לא משתמשים ב-AVPlayer, תצטרכו להטמיע את IMAContentPlayhead בכיתה משלכם.

צריך גם להודיע ל-SDK מתי התוכן סיים את ההפעלה כדי שיוכל להציג מודעות אחרי הפעלת התוכן. כדי לעשות את זה, קוראים ל-method‏ contentComplete ב-IMAAdsLoader, באמצעות AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

יוצרים את מופע IMAAVPlayerContentPlayhead בהגדרת הנגן:

// Set up our content playhead and contentComplete callback. self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer]; [[NSNotificationCenter defaultCenter] addObserver:self                                          selector:@selector(contentDidFinishPlaying:)                                              name:AVPlayerItemDidPlayToEndTimeNotification                                            object:self.contentPlayer.currentItem]; 

יוצרים את השיטה contentDidFinishPlaying() כדי להתקשר אל IMAAdsLoader.contentComplete() כשהתוכן מסיים את ההפעלה:

- (void)contentDidFinishPlaying:(NSNotification *)notification {   // Make sure we don't call contentComplete as a result of an ad completing.   if (notification.object == self.contentPlayer.currentItem) {     [self.adsLoader contentComplete];   } } 

Swift

יוצרים את האובייקט ContentEndedObserver בהגדרת הנגן:

NotificationCenter.default.addObserver(   self,   selector: #selector(contentDidFinishPlaying(_:)),   name: .AVPlayerItemDidPlayToEndTime,   object: contentPlayer.currentItem) 

יוצרים את השיטה contentDidFinishPlaying() כדי להתקשר אל IMAAdsLoader.contentComplete() כשהתוכן מסיים את ההפעלה:

@objc func contentDidFinishPlaying(_ notification: Notification) {   // Make sure we don't call contentComplete as a result of an ad completing.   if notification.object as? AVPlayerItem == contentPlayer.currentItem {     adsLoader.contentComplete()   } } 

6. מאתחלים את הכלי לטעינת מודעות ושולחים בקשה להצגת מודעות

כדי לבקש קבוצה של מודעות, צריך ליצור מופע של IMAAdsLoader. אפשר להשתמש בטוען הזה כדי לעבד אובייקטים של IMAAdsRequest שמשויכים לכתובת URL של תג מודעה שצוינה.

מומלץ לשמור רק מופע אחד של IMAAdsLoader לאורך כל מחזור החיים של האפליקציה. כדי לשלוח בקשות נוספות להצגת מודעות, צריך ליצור אובייקט IMAAdsRequest חדש, אבל להשתמש מחדש באותו IMAAdsLoader. מידע נוסף זמין בשאלות הנפוצות בנושא IMA SDK.

Objective-C

- (void)setupAdsLoader {   self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];   self.adsLoader.delegate = self; }  - (void)requestAds {   // Create an ad display container for ad rendering.   IMAAdDisplayContainer *adDisplayContainer =       [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView                                           viewController:self                                           companionSlots:nil];   // Create an ad request with our ad tag, display container, and optional user context.   IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl                                                 adDisplayContainer:adDisplayContainer                                                    contentPlayhead:self.contentPlayhead                                                        userContext:nil];   [self.adsLoader requestAdsWithRequest:request]; } 

Swift

private func requestAds() {   // Create ad display container for ad rendering.   let adDisplayContainer = IMAAdDisplayContainer(     adContainer: videoView, viewController: self, companionSlots: nil)   // Create an ad request with our ad tag, display container, and optional user context.   let request = IMAAdsRequest(     adTagUrl: PlayerContainerViewController.adTagURLString,     adDisplayContainer: adDisplayContainer,     contentPlayhead: contentPlayhead,     userContext: nil)    adsLoader.requestAds(with: request) } 

7. הגדרת נציג לטעינת מודעות

באירוע טעינה מוצלח, הפונקציה IMAAdsLoader קוראת לשיטה adsLoadedWithData של הנציג שהוקצה לה, ומעבירה לה מופע של IMAAdsManager. לאחר מכן תוכלו להפעיל את כלי ניהול המודעות, שיטען את המודעות הבודדות, כפי שהוגדר בתגובה לכתובת ה-URL של תג המודעה.

בנוסף, חשוב לטפל בכל השגיאות שעלולות להתרחש במהלך תהליך הטעינה. אם המודעות לא נטענות, חשוב לוודא שהפעלת המדיה נמשכת ללא מודעות, כדי לא לפגוע בחוויית המשתמש.

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {   // Grab the instance of the IMAAdsManager and set ourselves as the delegate.   self.adsManager = adsLoadedData.adsManager;   self.adsManager.delegate = self;   // Create ads rendering settings to tell the SDK to use the in-app browser.   IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];   adsRenderingSettings.linkOpenerPresentingController = self;   // Initialize the ads manager.   [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings]; }  - (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {   // Something went wrong loading ads. Log the error and play the content.   NSLog(@"Error loading ads: %@", adErrorData.adError.message);   [self.contentPlayer play]; } 

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {   // Grab the instance of the IMAAdsManager and set ourselves as the delegate.   adsManager = adsLoadedData.adsManager   adsManager?.delegate = self    // Create ads rendering settings and tell the SDK to use the in-app browser.   let adsRenderingSettings = IMAAdsRenderingSettings()   adsRenderingSettings.linkOpenerPresentingController = self    // Initialize the ads manager.   adsManager?.initialize(with: adsRenderingSettings) }  func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {   if let message = adErrorData.adError.message {     print("Error loading ads: \(message)")   }   contentPlayer.play() } 

8. הגדרת נציג בניהול מודעות

לבסוף, כדי לנהל אירועים ושינויים במצב, למנהל המודעות צריך להיות נציג משלו. ל-IMAAdManagerDelegate יש שיטות לטיפול באירועי מודעות ובשגיאות, וגם שיטות להפעלת תוכן הווידאו ולהשהייתו.

להפעלה

כדי להתחיל בהפעלה של תוכן ומודעות, צריך להגדיר את המערכת לזיהוי של האירוע LOADED. פרטים נוספים זמינים בקישור didReceiveAdEvent.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {   // When the SDK notified us that ads have been loaded, play them.   if (event.type == kIMAAdEvent_LOADED) {     [adsManager start];   } } 

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {   // When the SDK notifies us the ads have been loaded, play them.   if event.type == IMAAdEventType.LOADED {     adsManager.start()   } } 

טיפול בשגיאות

כדאי להוסיף גם handler לשגיאות שקשורות למודעות. אם מתרחשת שגיאה, כמו בשלב הקודם, מפעילים מחדש את התוכן.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {   // Something went wrong with the ads manager after ads were loaded. Log the error and play the   // content.   NSLog(@"AdsManager error: %@", error.message);   [self.contentPlayer play]; } 

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {   // Something went wrong with the ads manager after ads were loaded.   // Log the error and play the content.   if let message = error.message {     print("AdsManager error: \(message)")   }   contentPlayer.play() } 

האזנה לאירועי הפעלה והשהיה

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

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {   // The SDK is going to play ads, so pause the content.   [self.contentPlayer pause]; }  - (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {   // The SDK is done playing ads (at least for now), so resume the content.   [self.contentPlayer play]; } 

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {   // The SDK is going to play ads, so pause the content.   contentPlayer.pause() }  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {   // The SDK is done playing ads (at least for now), so resume the content.   contentPlayer.play() } 

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

השלבים הבאים

כדי להגדיל את ההכנסות מפרסום בפלטפורמת iOS, צריך לבקש הרשאה לשקיפות מעקב באפליקציה כדי להשתמש ב-IDFA.