Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam z 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 aplikacji.
Z tego przewodnika dowiesz się, jak zintegrować pakiet IMA SDK z aplikacją odtwarzacza wideo. Aby wyświetlić lub śledzić ukończoną 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, które zostały opisane w tym przewodniku:
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. Powinna być tylko jedna instancja modułu wczytywania reklam, której można używać 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ń reklamowych wywoływanych przez pakiet SDK.
Wymagania wstępne
Zanim zaczniesz, musisz mieć:
- Xcode 13 lub nowszy
- Metoda instalacji pakietu IMA SDK:
- Swift Package Manager (preferowana)
- CocoaPods
- Pobrana kopia pakietu IMA SDK na iOS
1. Utwórz nowy projekt w Xcode
W Xcode utwórz nowy projekt na iOS w języku Objective-C lub Swift. Jako nazwę projektu użyj BasicExample.
2. Dodaj pakiet IMA SDK do projektu w Xcode
Aby zainstalować pakiet IMA SDK, wybierz preferowaną metodę.
Zalecane: zainstaluj pakiet SDK za pomocą menedżera pakietów Swift
Pakiet SDK do interaktywnych reklam medialnych obsługuje Swift Package Manager od wersji 3.18.4. Aby zaimportować pakiet Swift, wykonaj te czynności:
W Xcode zainstaluj pakiet IMA SDK Swift, wybierając kolejno File > Add Package Dependencies... (Plik > Dodaj zależności pakietu).
W wyświetlonym oknie wyszukaj repozytorium GitHub pakietu IMA iOS SDK Swift:
swift-package-manager-google-interactive-media-ads-ios.Wybierz 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 SDK za pomocą CocoaPods
CocoaPods to menedżer zależności dla projektów w Xcode i zalecana metoda instalacji pakietu IMA SDK. Więcej informacji o instalowaniu i używaniu CocoaPods znajdziesz w dokumentacji CocoaPods. Po zainstalowaniu CocoaPods wykonaj te instrukcje, aby zainstalować pakiet IMA SDK:
W tym samym katalogu co plik BasicExample.xcodeproj utwórz plik tekstowy o nazwie Podfile i dodaj tę konfigurację:
W katalogu zawierającym plik Podfile uruchom polecenie
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ęcznie pobierz i zainstaluj pakiet SDK
Jeśli nie chcesz używać menedżera pakietów Swift, pobierz i ręcznie dodaj pakiet IMA SDK do projektu.
3. Utwórz odtwarzacz wideo
Najpierw zaimplementuj odtwarzacz wideo. Początkowo ten odtwarzacz nie korzysta z pakietu IMA SDK i nie zawiera żadnej metody wyzwalania odtwarzania.
Objective-C
Zaimportuj zależności odtwarzacza:
#import "ViewController.h"
@import AVFoundation;
Skonfiguruj zmienne odtwarzacza:
@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;
Zainicjuj odtwarzacz wideo po wczytaniu widoku:
@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
Zaimportuj zależności odtwarzacza:
import AVFoundation
Skonfiguruj zmienne odtwarzacza:
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)
}()
Zainicjuj odtwarzacz wideo po wczytaniu widoku:
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. Zaimportuj pakiet IMA SDK
Aby zaimportować pakiet IMA SDK:
Objective-C
Zaimportuj pakiet IMA SDK:
@import GoogleInteractiveMediaAds;Utwórz zmienne dla klas
IMAAdsLoader,IMAAVPlayerContentPlayheadiIMAAdsManagerużywanych w aplikacji:// 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
Zaimportuj pakiet IMA SDK:
import GoogleInteractiveMediaAdsUtwórz zmienne dla klas
IMAAdsLoader,IMAAVPlayerContentPlayheadiIMAAdsManagerużywanych w aplikacji: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. 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 to zrobić, utwórz klasę, która implementuje IMAContentPlayhead. Jeśli używasz AVPlayer, jak pokazano w tym przykładzie,
pakiet SDK udostępnia klasę IMAAVPlayerContentPlayhead, która wykonuje to zadanie.
Jeśli nie używasz AVPlayer, musisz zaimplementować IMAContentPlayhead w swojej klasie.
Musisz też poinformować pakiet SDK, kiedy odtwarzanie treści się zakończy, aby mógł wyświetlać reklamy po filmie. Aby to zrobić, wywołaj metodę
contentComplete
w IMAAdsLoader, używając AVPlayerItemDidPlayToEndTimeNotification.
Objective-C
Utwórz instancję IMAAVPlayerContentPlayhead w konfiguracji odtwarzacza:
// 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];
Utwórz metodę contentDidFinishPlaying(), aby wywołać IMAAdsLoader.contentComplete() po zakończeniu odtwarzania treści:
- (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
Utwórz obserwatora końca treści w konfiguracji odtwarzacza:
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
Utwórz metodę contentDidFinishPlaying(), aby wywołać IMAAdsLoader.contentComplete() po zakończeniu odtwarzania treści:
@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. Zainicjuj moduł wczytywania reklam i wyślij żądanie reklamy
Aby wysłać żądanie zestawu reklam, musisz utworzyć instancję IMAAdsLoader.
Ten moduł wczytywania przetwarza obiekty IMAAdsRequest powiązane z określonym adresem URL tagu reklamy.
Zalecamy, aby przez cały okres działania aplikacji utrzymywać tylko jedną instancję IMAAdsLoader. Aby wysłać dodatkowe żądania reklam, utwórz nowy obiekt IMAAdsRequest, ale użyj 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] 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. Skonfiguruj delegata modułu wczytywania reklam
W przypadku pomyślnego zdarzenia wczytania IMAAdsLoader wywołuje metodę
adsLoadedWithData
przypisanego delegata, przekazując mu instancję IMAAdsManager. Następnie możesz zainicjować menedżera reklam, który wczytuje poszczególne reklamy zgodnie z odpowiedzią na adres URL tagu reklamy.
Pamiętaj też, aby obsługiwać błędy, które mogą wystąpić podczas wczytywania. Jeśli reklamy się nie wczytują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby nie zakłócać wrażeń użytkownika.
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. Skonfiguruj delegata menedżera reklam
Na koniec, aby zarządzać zdarzeniami i zmianami stanu, menedżer reklam potrzebuje własnego delegata. IMAAdManagerDelegate ma metody obsługi zdarzeń i błędów reklam oraz metody wyzwalania odtwarzania i wstrzymywania treści wideo.
Rozpocznij odtwarzanie
Nasłuchuj zdarzenia LOADED, aby rozpocząć odtwarzanie treści i reklam. Więcej
informacji znajdziesz w
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()
}
}
Obsługuj błędy
Dodaj też obsługę 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 {
// 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()
}
Nasłuchuj zdarzeń odtwarzania i wstrzymywania
Ostatnie 2 metody delegata, które musisz zaimplementować, wyzwalają zdarzenia odtwarzania i wstrzymywania w podstawowych treściach wideo, gdy pakiet IMA SDK o to poprosi. Wyzwalanie wstrzymywania i odtwarzania na żądanie zapobiega pomijaniu przez użytkownika fragmentów treści wideo podczas wyświetlania reklam.
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()
}
To wszystko. Teraz możesz wysyłać żądania reklam i wyświetlać je 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 iOS, poproś o zgodę na przejrzystość i śledzenie aplikacji, aby móc używać identyfikatora IDFA.