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 z 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 wideo z treściami aplikacji.
W tym przewodniku pokazujemy, jak zintegrować pakiet IMA SDK z aplikacją odtwarzacza wideo. Aby wyświetlić gotową przykładową integrację lub postępować zgodnie z nią, pobierz BasicExample z GitHub.
Omówienie IMA po stronie klienta
Wdrożenie pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK, które opisujemy w tym przewodniku:
IMAAdDisplayContainer: obiekt kontenera, który określa, gdzie IMA renderuje elementy interfejsu reklamy 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. Powinieneś utworzyć tylko jeden moduł wczytywania reklam, którego 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, a także 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 (zalecane)
- CocoaPods
- Pobrana kopia pakietu IMA SDK na iOS
1. Tworzenie nowego projektu Xcode
W Xcode utwórz nowy projekt iOS w języku Objective-C lub Swift. Użyj nazwy projektu BasicExample.
2. Dodawanie pakietu IMA SDK do projektu w Xcode
Aby zainstalować pakiet IMA SDK, wybierz preferowaną metodę.
Zalecane: instalowanie pakietu SDK za pomocą menedżera pakietów Swift
Pakiet SDK do wyświetlania 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 SDK IMA Swift, klikając File > Add Package Dependencies... (Plik > Dodaj zależności pakietu...).
W prompcie wyszukaj repozytorium GitHub pakietu IMA SDK na iOS w Swift Package:
swift-package-manager-google-interactive-media-ads-iosWybierz wersję pakietu IMA SDK Swift Package, której chcesz używać. W przypadku nowych projektów zalecamy używanie opcji 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 pakietów znajdziesz w artykule Apple.
Instalowanie pakietu SDK za pomocą CocoaPods
CocoaPods to menedżer zależności dla projektów Xcode. Jest to zalecana metoda instalowania 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, w którym znajduje się 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. W tym celu otwórz plik BasicExample.xcworkspace i upewnij się, że zawiera 2 projekty: BasicExample i Pods (zależności zainstalowane przez CocoaPods).
Ręczne pobieranie i instalowanie pakietu SDK
Jeśli nie chcesz używać menedżera pakietów Swift, pobierz i ręcznie dodaj do projektu pakiet IMA SDK.
Pokaż/ukryj instrukcje
- Na stronie pobierania pakietu IMA SDK na iOS pobierz i rozpakuj najnowszą wersję pakietu IMA SDK na iOS.
- Otwórz BasicExample.xcodeproj.
- W panelu po lewej stronie kliknij nazwę projektu.
- W panelu środkowym kliknij Fazy kompilacji.
- Rozwiń sekcję Link Binary With Libraries (Połącz plik binarny z bibliotekami).
- U dołu listy bibliotek kliknij ikonę plusa [+].
- Kliknij Dodaj inne.
- W katalogu, w którym został wyodrębniony pobrany pakiet SDK, wybierz GoogleInteractiveMediaAds.framework i kliknij Otwórz.
- U dołu listy bibliotek ponownie kliknij ikonę plusa [+].
- W kolumnie Stan sprawdź, czy
GoogleInteractiveMediaAds.frameworkjest ustawiony naRequired. - W ustawieniach kompilacji umieść flagę linkera
-ObjC. Więcej informacji znajdziesz w dokumencie Apple QA1490.
3. Tworzenie odtwarzacza wideo
Najpierw wdróż odtwarzacz wideo. Początkowo ten odtwarzacz nie korzysta z pakietu IMA SDK i nie zawiera żadnej metody wywoływania odtwarzania.
Objective-C
Zaimportuj zależności od 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;
Uruchom 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 od 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)
}()
Uruchom 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. Wdrożenie narzędzia do śledzenia pozycji odtwarzania treści i obserwatora końca transmisji
Aby wyświetlać reklamy w trakcie filmu, pakiet IMA SDK musi śledzić bieżącą pozycję treści wideo. Aby to zrobić, utwórz klasę, która implementuje interfejs IMAContentPlayhead. Jeśli używasz AVPlayer, jak pokazano w tym przykładzie, pakiet SDK udostępnia klasę IMAAVPlayerContentPlayhead, która wykonuje to za Ciebie.
Jeśli nie używasz AVPlayer, musisz zaimplementować IMAContentPlayhead w klasie własnej.
Musisz też poinformować pakiet SDK, kiedy odtwarzanie treści się zakończy, aby mógł wyświetlać reklamy po zakończeniu filmu. Aby to zrobić, wywołaj metodę contentComplete na obiekcie 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 zakończenia 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 poprosić o zestaw reklam, musisz utworzyć instancję IMAAdsLoader.
Ten moduł wczytujący przetwarza obiekty IMAAdsRequest powiązane z określonym adresem URL tagu reklamy.
Zalecamy utrzymywanie tylko jednej instancji IMAAdsLoader przez cały cykl życia aplikacji. Aby wysłać dodatkowe żądania reklamy, utwórz nowy obiekt IMAAdsRequest, ale użyj tego samego obiektu IMAAdsLoader. Więcej informacji znajdziesz w odpowiedziach na 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. Konfigurowanie delegata modułu wczytywania reklam
Po pomyślnym wczytaniu zdarzenia IMAAdsLoader wywołuje metodę adsLoadedWithData przypisanego delegata, przekazując jej 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ć wszelkie błędy, które mogą wystąpić podczas wczytywania. Jeśli reklamy się nie ładują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby nie zakłócać korzystania z aplikacji przez użytkowników.
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. Konfigurowanie delegata menedżera reklam
Na koniec, aby zarządzać zdarzeniami i zmianami stanu, menedżer reklam potrzebuje własnego delegata. Obiekt IMAAdManagerDelegate ma metody obsługi zdarzeń i błędów związanych z reklamami, a także metody uruchamiania i wstrzymywania odtwarzania treści wideo.
Rozpocznij odtwarzanie
Nasłuchuj zdarzenia LOADED, aby rozpocząć odtwarzanie treści i reklam. Więcej informacji znajdziesz w sekcji 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ż 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 {
// 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łuchiwanie zdarzeń odtwarzania i wstrzymywania
Ostatnie 2 metody delegowania, które musisz zaimplementować, wywołują zdarzenia odtwarzania i wstrzymywania w przypadku podstawowych treści wideo, gdy pakiet IMA SDK o nie poprosi. Wywoływanie wstrzymania 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. Żądania reklam i ich wyświetlanie odbywa się teraz za pomocą pakietu IMA SDK. Więcej informacji o dodatkowych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub w przykładach na GitHubie.
Następne kroki
Aby zmaksymalizować przychody z reklam na platformie iOS, poproś o uprawnienia do przejrzystości i śledzenia aplikacji, aby móc korzystać z identyfikatora IDFA.