Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam do dowolnego serwera reklam zgodnego ze standardem VAST i zarządzać odtwarzaniem reklam w aplikacjach. Dzięki pakietom IMA SDK po stronie klienta, zachowujesz kontrolę nad odtwarzaniem treści wideo, a pakiet SDK obsługuje odtwarzanie reklam. Reklamy są odtwarzane w osobnym odtwarzaczu wideo umieszczonym nad odtwarzaczem treści wideo w aplikacji.
Ten przewodnik pokazuje, jak zintegrować pakiet IMA SDK z aplikacją odtwarzacza wideo. Aby wyświetlić lub śledzić gotową przykładową integrację, pobierz BasicExample z GitHub.
Omówienie pakietu IMA SDK po stronie klienta
Implementacja pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK. Ten przewodnik zawiera omówienie tych komponentów:
IMAAdDisplayContainer: Obiekt kontenera, który określa, gdzie pakiet IMA SDK renderuje elementy interfejsu reklam i mierzy widoczność, w tym Widok aktywny i Open Measurement.IMAAdsLoader: obiekt, który wysyła żądania reklam i obsługuje zdarzenia z odpowiedzi na żądania reklam. Należy utworzyć tylko jeden moduł wczytywania reklam, który można ponownie wykorzystać przez cały okres działania aplikacji.IMAAdsRequest: Obiekt, który definiuje żądanie reklamy. Żądania reklam określają adres URL tagu reklamy VAST oraz dodatkowe parametry, takie jak wymiary reklamy.IMAAdsManager: Obiekt, który zawiera odpowiedź na żądanie reklamy, kontroluje odtwarzanie reklam i nasłuchuje zdarzeń reklam uruchamianych przez pakiet SDK.
Wymagania wstępne
Zanim zaczniesz, musisz mieć:
- Xcode 13 lub nowszy
- Metoda instalacji pakietu IMA SDK:
- Preferowana: Swift Package Manager
- CocoaPods
- Pobrana kopia pakietu IMA SDK dla tvOS
1. Utwórz nowy projekt Xcode
W Xcode utwórz nowy projekt tvOS w Objective-C lub Swift. Jako nazwę projektu użyj BasicExample.
2. Dodaj pakiet IMA SDK do projektu Xcode
Aby zainstalować pakiet IMA SDK, wybierz preferowaną metodę.
Zalecane: zainstaluj pakiet IMA SDK za pomocą menedżera pakietów Swift
Pakiet SDK do interaktywnych reklam medialnych obsługuje menedżera pakietów Swift od wersji 4.8.2. Aby zaimportować pakiet Swift, wykonaj te czynności.
W Xcode zainstaluj pakiet IMA SDK Swift, wybierając kolejno File > Add Packages... (Plik > Dodaj pakiety...).
W wyświetlonym oknie wyszukaj repozytorium GitHub pakietu IMA SDK Swift:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosWybierz wersję pakietu IMA SDK Swift, której chcesz używać. W przypadku nowych projektów zalecamy używanie opcji Up to Next Major Version (Do następnej wersji głównej).
Gdy skończysz, Xcode przetworzy zależności pakietu i pobierze je w tle. Więcej informacji o dodawaniu zależności pakietu znajdziesz w artykule Apple.
Zainstaluj pakiet IMA SDK za pomocą CocoaPods
Aby zainstalować pakiet IMA SDK, użyj CocoaPods. Więcej informacji o instalowaniu i używaniu CocoaPods znajdziesz w dokumentacji CocoaPods. Po zainstalowaniu CocoaPods wykonaj te czynności:
W tym samym katalogu co plik BasicExample.xcodeproj utwórz plik tekstowy o nazwie Podfile i dodaj tę konfigurację:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endW katalogu zawierającym plik Podfile uruchom
pod install --repo-update.Sprawdź, czy instalacja się powiodła, otwierając plik BasicExample.xcworkspace i upewniając się, że zawiera on 2 projekty: BasicExample i Pods (zależności zainstalowane przez CocoaPods).
Ręczne pobieranie i instalowanie pakietu IMA SDK
Jeśli nie chcesz używać menedżera pakietów Swift, pobierz i ręcznie dodaj pakiet IMA SDK do projektu.
3. Zaimportuj pakiet IMA SDK
Dodaj platformę IMA za pomocą instrukcji importu.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. Utwórz odtwarzacz wideo i zintegruj go z pakietem IMA SDK
Ten przykład pokazuje, jak zainicjować pakiet IMA SDK:
Objective-C
NSString *const kContentURLString =
@"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString =
@"https://pubads.g.doubleclick.net/gampad/ads?"
@"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
@"cust_params=sample_ar%3Dpremidpostlongpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&"
@"output=vmap&unviewed_position_start=1&env=vp&cmsid=496&vid=short_onecue&correlator=";
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
[self setupContentPlayer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestAds];
}
// Add the content video player as a child view controller.
- (void)showContentPlayer {
[self addChildViewController:self.contentPlayerViewController];
self.contentPlayerViewController.view.frame = self.view.bounds;
[self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
[self.contentPlayerViewController didMoveToParentViewController:self];
}
// Remove and detach the content video player.
- (void)hideContentPlayer {
// The whole controller needs to be detached so that it doesn't capture resume events from the
// remote and play content underneath the ad.
[self.contentPlayerViewController willMoveToParentViewController:nil];
[self.contentPlayerViewController.view removeFromSuperview];
[self.contentPlayerViewController removeFromParentViewController];
}
Swift
class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURLString =
"https://devstreaming-cdn.apple.com/videos/streaming/examples/"
+ "img_bipbop_adv_example_fmp4/master.m3u8"
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="
var adsLoader: IMAAdsLoader!
var adDisplayContainer: IMAAdDisplayContainer!
var adsManager: IMAAdsManager!
var contentPlayhead: IMAAVPlayerContentPlayhead?
var playerViewController: AVPlayerViewController!
var adBreakActive = false
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setUpContentPlayer()
setUpAdsLoader()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestAds()
}
W tym przykładzie funkcja viewDidLoad() inicjuje IMAAdsLoader, a funkcja viewDidAppear() wysyła żądania reklam, gdy widok jest widoczny. Metody pomocnicze showContentPlayer() i hideContentPlayer() przełączają widoczność treści podczas odtwarzania reklam.
W tym przykładzie stała zmienna adTagURLString służy do definiowania tagu reklamy VAST na potrzeby żądania reklamy, a te komponenty służą do zarządzania pakietem IMA SDK:
adsLoader: obsługuje żądania i odpowiedzi na żądania reklam. Zalecamy używanie jednej instancji przez cały okres działania aplikacji.adDisplayContainer: określa widok renderowania reklam.adsManager: zarządza odtwarzaniem reklam i nasłuchuje zdarzeń reklam.contentPlayhead: śledzi postęp treści, aby uruchamiać przerwy na reklamy w trakcie filmu.adBreakActive: wskazuje, czy odtwarzana jest przerwa na reklamę, aby zapobiec przewijaniu reklam.
5. Zaimplementuj śledzenie suwaka odtwarzania treści i obserwatora końca strumienia
Aby odtwarzać reklamy w trakcie filmu, pakiet IMA SDK musi śledzić bieżącą pozycję treści wideo. Aby przekazać bieżącą pozycję do pakietu IMA SDK, utwórz klasę, która implementuje IMAContentPlayhead. Jeśli używasz AVPlayer, jak pokazano w tym przykładzie
, pakiet IMA SDK udostępnia klasę IMAAVPlayerContentPlayhead, która przekazuje informacje o bieżącej
pozycji. Jeśli nie używasz AVPlayer, zaimplementuj IMAContentPlayhead w swojej klasie.
Objective-C
- (void)setupContentPlayer {
// Create a content video player. Create a playhead to track content progress so the SDK knows
// when to play ads in a VMAP playlist.
NSURL *contentURL = [NSURL URLWithString:kContentURLString];
AVPlayer *player = [AVPlayer playerWithURL:contentURL];
self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
self.contentPlayerViewController.player = player;
self.contentPlayerViewController.view.frame = self.view.bounds;
self.contentPlayhead =
[[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];
// Track end of content.
AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(contentDidFinishPlaying:)
name:AVPlayerItemDidPlayToEndTimeNotification
object:contentPlayerItem];
// Attach content video player to view hierarchy.
[self showContentPlayer];
}
Swift
func setUpContentPlayer() {
// Load AVPlayer with path to our content.
let contentURL = URL(string: ViewController.contentURLString)!
let player = AVPlayer(url: contentURL)
playerViewController = AVPlayerViewController()
playerViewController.player = player
// Set up our content playhead and contentComplete callback.
contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
NotificationCenter.default.addObserver(
self,
selector: #selector(ViewController.contentDidFinishPlaying(_:)),
name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
object: player.currentItem)
showContentPlayer()
}
Skonfiguruj odbiornik, aby wywoływał contentComplete w IMAAdsLoader po zakończeniu treści, używając AVPlayerItemDidPlayToEndTimeNotification. Wywołanie contentComplete informuje pakiet IMA SDK, kiedy kończy się odtwarzanie treści, aby wyświetlać reklamy po filmie.
Objective-C
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Notify the SDK that the postrolls should be played.
[self.adsLoader contentComplete];
}
- (void)dealloc {
[[NSNotificationCenter defaultCenter] removeObserver:self];
}
Swift
@objc func contentDidFinishPlaying(_ notification: Notification) {
adsLoader.contentComplete()
}
6. Zainicjuj moduł wczytywania reklam i wyślij żądanie reklamy
Aby poprosić o zestaw reklam, utwórz instancję IMAAdsLoader.
Ten moduł wczytywania przetwarza obiekty IMAAdsRequest powiązane z określonym adresem URL tagu reklamy.
Zalecamy utrzymywanie tylko jednej instancji IMAAdsLoader przez cały okres działania aplikacji. Aby wysłać dodatkowe żądania reklam, utwórz nowy obiekt IMAAdsRequest, ale użyj ponownie tego samego IMAAdsLoader. Więcej
informacji znajdziesz w sekcji Najczęstsze pytania dotyczące pakietu IMA SDK.
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Pass the main view as the container for ad display.
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
viewController:self];
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
adDisplayContainer:self.adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Swift
func setUpAdsLoader() {
adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
}
func requestAds() {
// Create ad display container for ad rendering.
adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
// Create an ad request with our ad tag, display container, and optional user context.
let request = IMAAdsRequest(
adTagUrl: ViewController.adTagURLString,
adDisplayContainer: adDisplayContainer,
contentPlayhead: contentPlayhead,
userContext: nil)
adsLoader.requestAds(with: request)
}
7. Skonfiguruj delegata modułu wczytywania reklam
W przypadku pomyślnego zdarzenia wczytania IMAAdsLoader wywołuje metodę adsLoadedWithData przypisanego delegata, przekazując mu instancję IMAAdsManager.
Po uzyskaniu instancji IMAAdsManager zainicjuj menedżera reklam, który wczytuje poszczególne reklamy na podstawie odpowiedzi adresu URL tagu reklamy.
W przypadku nieudanych zdarzeń wczytania skonfiguruj delegata IMAAdsLoader, aby obsługiwał błędy występujące podczas procesu wczytywania. Jeśli reklamy się nie wczytują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby użytkownicy mogli wyświetlać treści multimedialne.
Objective-C
#pragma mark - IMAAdsLoaderDelegate
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Initialize and listen to the ads manager loaded for this request.
self.adsManager = adsLoadedData.adsManager;
self.adsManager.delegate = self;
[self.adsManager initializeWithAdsRenderingSettings:nil];
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Fall back to playing content.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self.contentPlayerViewController.player 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
adsManager.initialize(with: nil)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
8. Skonfiguruj delegata menedżera reklam
Na koniec, aby zarządzać zdarzeniami i zmianami stanu, menedżer reklam wymaga własnego delegata. IMAAdManagerDelegate ma metody obsługi zdarzeń i błędów reklam oraz metody uruchamiania i wstrzymywania odtwarzania treści wideo.
Rozpoczynanie odtwarzania
Metoda didReceiveAdEvent obsługuje wszystkie zdarzenia IMAAdEvent.
W tym podstawowym przykładzie nasłuchuj zdarzenia LOADED, aby poinformować menedżera reklam o rozpoczęciu odtwarzania treści i reklam. Pakiet IMA SDK uruchamia zdarzenie ICON_FALLBACK_IMAGE_CLOSED, gdy użytkownik zamknie okno rezerwowe ikony po kliknięciu ikony. Po tej czynności odtwarzanie reklamy zostanie wznowione.
Objective-C
#pragma mark - IMAAdsManagerDelegate
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
switch (event.type) {
case kIMAAdEvent_LOADED: {
// Play each ad once it has loaded.
[adsManager start];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume ad after user has closed dialog.
[adsManager resume];
break;
}
default:
break;
}
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
switch event.type {
case IMAAdEventType.LOADED:
// Play each ad once it has been loaded.
adsManager.start()
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
adsManager.resume()
default:
break
}
}
Obsługa błędów
Dodaj też moduł obsługi błędów reklam. Jeśli wystąpi błąd, tak jak w poprzednim kroku, wznow odtwarzanie treści.
Objective-C
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing content.
NSLog(@"AdsManager error: %@", error.message);
[self showContentPlayer];
[self.contentPlayerViewController.player play];
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Fall back to playing content
print("AdsManager error: \(error.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
Uruchamianie zdarzeń odtwarzania i wstrzymywania
Ostatnie 2 metody delegata, które implementujesz, uruchamiają zdarzenia odtwarzania i wstrzymywania w podstawowych treściach wideo, gdy pakiet IMA SDK o nie poprosi. Uruchamianie wstrzymywania i odtwarzania, gdy pakiet IMA SDK o nie poprosi, zapobiega pominięciu przez użytkownika części treści wideo podczas wyświetlania reklam.
Objective-C
- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
// Pause the content for the SDK to play ads.
[self.contentPlayerViewController.player pause];
[self hideContentPlayer];
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// Resume the content since the SDK is done playing ads (at least for now).
[self showContentPlayer];
[self.contentPlayerViewController.player play];
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
}
Swift
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// Pause the content for the SDK to play ads.
playerViewController.player?.pause()
hideContentPlayer()
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// Resume the content since the SDK is done playing ads (at least for now).
showContentPlayer()
playerViewController.player?.play()
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
}
To wszystko. Teraz możesz wysyłać żądania reklam i wyświetlać reklamy za pomocą pakietu IMA SDK. Aby dowiedzieć się więcej o dodatkowych funkcjach pakietu SDK, zapoznaj się z innymi przewodnikami lub przykładami na GitHub.
Następne kroki
Aby zmaksymalizować przychody z reklam na platformie tvOS, poproś o zgodę na przejrzystość i śledzenie aplikacji, aby używać identyfikatora IDFA.