تسهّل حِزم تطوير البرامج لإعلانات الوسائط التفاعلية (IMA SDK) دمج الإعلانات المتعددة الوسائط في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم IMA SDK can طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم IMA SDK من جهة العميل، يمكنك التحكّم في تشغيل فيديو المحتوى، بينما تتولّى حزمة SDK تشغيل الإعلانات. يتم تشغيل الإعلانات في مشغّل فيديو منفصل موضوع أعلى مشغّل فيديو محتوى التطبيق.
يوضّح هذا الدليل كيفية دمج حزمة IMA SDK في تطبيق مشغّل فيديو. لعرض نموذج تكامل مكتمل أو اتّباعه، نزِّل BasicExample من GitHub.
نظرة عامة على حزمة IMA SDK من جهة العميل
يتضمّن استخدام حزمة IMA SDK من جهة العميل أربعة مكوّنات رئيسية لحزمة SDK. يوضّح هذا الدليل هذه المكوّنات:
IMAAdDisplayContainer: هو كائن حاوية يحدّد المكان الذي تعرض فيه حزمة IMA عناصر واجهة مستخدِم الإعلان وتقيس إمكانية العرض، بما في ذلك العرض النشط و Open Measurement.IMAAdsLoader: هو كائن يطلب الإعلانات ويتعامل مع الأحداث من ردود طلبات الإعلانات. يجب إنشاء أداة تحميل إعلانات واحدة فقط، ويمكن إعادة استخدامها طوال فترة استخدام التطبيق.IMAAdsRequest: هو كائن يحدّد طلب إعلان. تحدّد طلبات الإعلانات عنوان URL لعلامة إعلان VAST، بالإضافة إلى مَعلمات إضافية، مثل أبعاد الإعلان.IMAAdsManager: هو كائن يحتوي على الردّ على طلب الإعلان، ويتحكّم في تشغيل الإعلان، ويستمع إلى أحداث الإعلانات التي تُطلِقها حزمة SDK.
المتطلبات الأساسية
قبل البدء، يجب أن يتوفّر لديك ما يلي:
- الإصدار 13 أو الإصدارات الأحدث من Xcode
- طريقة لتثبيت حزمة IMA SDK:
- Preferred: Swift Package Manager
- CocoaPods
- نسخة قابلة للتنزيل من حزمة IMA SDK لنظام التشغيل tvOS
1- إنشاء مشروع جديد على Xcode
في Xcode، أنشئ مشروعًا جديدًا على tvOS باستخدام Objective-C أو Swift. استخدِم BasicExample كاسم للمشروع.
2- إضافة حزمة IMA SDK إلى مشروع Xcode
لتثبيت حزمة IMA SDK، اختَر طريقة مفضّلة.
ننصحك بتثبيت حزمة IMA SDK باستخدام Swift Package Manager
تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية مع Swift Package Manager بدءًا من الإصدار 4.8.2. اتّبِع الخطوات التالية لاستيراد حزمة Swift.
في Xcode، ثبِّت حزمة IMA SDK Swift Package من خلال الانتقال إلى ملف > إضافة حِزم....
في الرسالة التي تظهر، ابحث عن مستودع IMA SDK Swift Package على GitHub:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosاختَر إصدار حزمة IMA SDK Swift Package الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدارات حتى الإصدار الرئيسي التالي.
بعد الانتهاء، يحلّ Xcode التبعيات المرتبطة بحِزمك وينزِّلها في الخلفية. لمزيد من التفاصيل حول كيفية إضافة التبعيات المرتبطة بالحِزم، يُرجى الاطّلاع على مقالة Apple.
تثبيت حزمة IMA SDK باستخدام CocoaPods
لتثبيت حزمة IMA SDK، استخدِم CocoaPods. لمزيد من المعلومات عن تثبيت CocoaPods أو استخدامه ، يُرجى الاطّلاع على مستندات CocoaPods. بعد تثبيت CocoaPods، اتّبِع الخطوات التالية:
في الدليل نفسه الذي يحتوي على ملف BasicExample.xcodeproj ، أنشئ ملفًا نصيًا باسم Podfile وأضِف الإعدادات التالية:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endمن الدليل الذي يحتوي على ملف Podfile، شغِّل
pod install --repo-updateتأكَّد من نجاح عملية التثبيت من خلال فتح ملف BasicExample.xcworkspace والتأكّد من أنّه يحتوي على مشروعَين: BasicExample وPods (التبعيات التي ثبَّتها CocoaPods).
تنزيل حزمة IMA SDK وتثبيتها يدويًا
إذا كنت لا تريد استخدام Swift Package Manager، نزِّل حزمة IMA SDK وأضِفها يدويًا إلى مشروعك.
3- استيراد حزمة IMA SDK
أضِف إطار عمل IMA باستخدام عبارة استيراد.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4- إنشاء مشغّل فيديو ودمج حزمة IMA SDK
يوضّح المثال التالي كيفية إعداد حزمة 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()
}
في هذا المثال، تُعدّ الدالة viewDidLoad() أداة IMAAdsLoader، وتطلب الدالة viewDidAppear() الإعلانات بعد ظهور طريقة العرض. تبدّل الطريقتان المساعدتان showContentPlayer() وhideContentPlayer() عرض المحتوى أثناء تشغيل الإعلان.
يستخدم هذا المثال متغيّر adTagURLString الثابت لتحديد علامة إعلان VAST لطلب عرض الإعلان، والمكوّنات التالية لإدارة حزمة IMA SDK:
adsLoader: يتعامل مع طلبات الإعلانات والردود عليها. ننصحك باستخدام مثيل واحد طوال فترة استخدام التطبيق.adDisplayContainer: يحدّد طريقة العرض لعرض الإعلانات.adsManager: يدير تشغيل الإعلانات ويستمع إلى أحداث الإعلانات.contentPlayhead: يتتبّع تقدّم المحتوى لتشغيل الفواصل الإعلانية أثناء التشغيل.adBreakActive: يشير إلى ما إذا كان يتم تشغيل فاصل إعلاني لمنع الانتقال إلى الإعلانات.
5- تنفيذ أداة تتبّع رأس التشغيل للمحتوى ومراقب نهاية البث
لعرض الإعلانات أثناء التشغيل، يجب أن تتتبّع حزمة IMA SDK الموضع الحالي لمحتوى الفيديو. لتمرير الموضع الحالي إلى حزمة IMA SDK، أنشئ فئة تنفّذ IMAContentPlayhead. إذا كنت تستخدم AVPlayer، كما يوضّح هذا المثال
، توفّر حزمة IMA SDK الفئة IMAAVPlayerContentPlayhead لتمرير معلومات الموضع الحالي
نيابةً عنك. إذا كنت لا تستخدم AVPlayer، نفِّذ IMAContentPlayhead على فئة خاصة بك.
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()
}
يمكنك إعداد متتبِّع لاستدعاء contentComplete على IMAAdsLoader عند انتهاء المحتوى، وذلك باستخدام AVPlayerItemDidPlayToEndTimeNotification. يسمح استدعاء contentComplete لحزمة IMA SDK بمعرفة متى ينتهي تشغيل المحتوى لعرض إعلانات ما بعد التشغيل.
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- إعداد أداة تحميل الإعلانات وإرسال طلب إعلان
لطلب مجموعة من الإعلانات، أنشئ مثيلاً من IMAAdsLoader.
تعالج أداة التحميل هذه كائنات IMAAdsRequest المرتبطة بعنوان URL محدّد لعلامة الإعلان.
ننصحك بالاحتفاظ بمثيل واحد فقط من IMAAdsLoader طوال مراحل نشاط تطبيقك. لإرسال طلبات عرض الإعلانات الإضافية، أنشئ عنصر IMAAdsRequest جديدًا، ولكن أعِد استخدام IMAAdsLoader نفسه. لمزيد من
المعلومات، يُرجى الاطّلاع على الأسئلة الشائعة عن حزمة 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- إعداد مفوّض أداة تحميل الإعلانات
عند حدوث حدث تحميل ناجح، تستدعي IMAAdsLoader الطريقة adsLoadedWithData للمفوّض الذي تم تعيينه، وتمرِّر إليه مثيلاً من IMAAdsManager.
بعد الحصول على مثيل IMAAdsManager، عليك إعداد مدير الإعلانات الذي يحمِّل الإعلانات الفردية استنادًا إلى الردّ على عنوان URL لعلامة الإعلان.
بالنسبة إلى أحداث التحميل غير الناجحة، عليك إعداد مفوّض IMAAdsLoader للتعامل مع الأخطاء التي تحدث أثناء عملية التحميل. إذا لم يتم تحميل الإعلانات، تأكَّد من استمرار تشغيل الوسائط بدون إعلانات للسماح للمستخدمين بمشاهدة محتوى الوسائط.
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- إعداد مفوّض مدير الإعلانات
أخيرًا، لإدارة الأحداث والتغييرات في الحالة، يتطلّب مدير الإعلانات مفوّضًا خاصًا به. يحتوي IMAAdManagerDelegate على طرق للتعامل مع أحداث الإعلانات والأخطاء، بالإضافة إلى طرق لتشغيل محتوى الفيديو وإيقافه مؤقتًا.
بدء التشغيل
تتعامل الطريقة didReceiveAdEvent مع جميع أحداث IMAAdEvent.
بالنسبة إلى هذا المثال الأساسي، استمع إلى حدث LOADED لإخبار مدير الإعلانات ببدء تشغيل المحتوى والإعلانات. تُطلِق حزمة IMA SDK حدث ICON_FALLBACK_IMAGE_CLOSED عندما يغلق المستخدم مربّع حوار بديل الرمز بعد النقر على رمز. بعد هذا الإجراء، يستأنف تشغيل الإعلان.
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
}
}
التعامل مع الأخطاء
أضِف معالجًا لأخطاء الإعلانات أيضًا. إذا حدث خطأ، كما في الخطوة السابقة، استأنِف تشغيل المحتوى.
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()
}
تشغيل أحداث التشغيل والإيقاف المؤقت
تُطلِق طريقتَا المفوّض الأخيرتان اللتان تنفّذهما أحداث التشغيل والإيقاف المؤقت على محتوى الفيديو الأساسي عندما تطلبهما حزمة IMA SDK. يؤدي تشغيل الإيقاف المؤقت والتشغيل عندما تطلبهما حزمة IMA SDK إلى منع المستخدم من تفويت أجزاء من محتوى الفيديو عند عرض الإعلانات.
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()
}
هذا كل شيء! أنت الآن تطلب الإعلانات وتعرضها باستخدام حزمة IMA SDK. للتعرّف على ميزات حزمة SDK الإضافية، يُرجى الاطّلاع على الأدلة الأخرى أو الـ نماذج على GitHub.
الخطوات التالية
لتحقيق أقصى قدر من الإيرادات من الإعلانات على منصة tvOS، اطلب إذن "شفافية تتبُّع التطبيقات" لاستخدام معرّف المعلِنين.