الأحداث المخصّصة لإعلانات البانر
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المتطلبات الأساسية
أكمِل إعداد الأحداث المخصّصة.
طلب إعلان بانر
عند الوصول إلى عنصر سعر الحدث المخصّص في سلسلة توسّط العرض الإعلاني بدون انقطاع، يتم استدعاء الطريقة loadBanner:adConfiguration:completionHandler:
في اسم الفئة الذي قدّمته عند إنشاء حدث مخصّص. في هذه الحالة، تكون الطريقة في SampleCustomEvent
، والتي تستدعي بعد ذلك الطريقة loadBanner:adConfiguration:completionHandler:
في SampleCustomEventBanner
.
لطلب إعلان بانر، أنشئ أو عدِّل فئة تنفّذ
GADMediationAdapter
وloadBanner:adConfiguration:completionHandler:
. إذا كان هناك صف
يمتد إلى GADMediationAdapter
، نفِّذ
loadBanner:adConfiguration:completionHandler:
هناك. بالإضافة إلى ذلك، أنشئ فئة جديدة لتنفيذ GADMediationBannerAd
.
في مثال الحدث المخصّص،
تنفّذ SampleCustomEvent
الواجهة GADMediationAdapter
ثم تفوّض إلى
SampleCustomEventBanner
.
Swift
import GoogleMobileAds
class SampleCustomEvent: NSObject, MediationAdapter {
fileprivate var bannerAd: SampleCustomEventBanner?
...
func loadBanner(
for adConfiguration: MediationBannerAdConfiguration,
completionHandler: @escaping GADMediationBannerLoadCompletionHandler
) {
self.bannerAd = SampleCustomEventBanner()
self.bannerAd?.loadBanner(
for: adConfiguration, completionHandler: completionHandler)
}
}
Objective-C
#import "SampleCustomEvent.h"
@implementation SampleCustomEvent
...
SampleCustomEventBanner *sampleBanner;
- (void)loadBannerForAdConfiguration:
(GADMediationBannerAdConfiguration *)adConfiguration
completionHandler:(GADMediationBannerLoadCompletionHandler)
completionHandler {
sampleBanner = [[SampleCustomEventBanner alloc] init];
[sampleBanner loadBannerForAdConfiguration:adConfiguration
completionHandler:completionHandler];
}
يتحمّل "SampleCustomEventBanner
" مسؤولية المهام التالية:
تحميل إعلان البانر واستدعاء طريقة GADMediationBannerLoadCompletionHandler
مرة واحدة بعد اكتمال عملية التحميل
تنفيذ بروتوكول GADMediationBannerAd
تلقّي عمليات ردّ الاتصال الخاصة بأحداث الإعلانات وإعداد تقارير عنها في حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"
يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم "مدير إعلانات Google" في إعدادات الإعلان.
يمكن الوصول إلى المَعلمة من خلال
adConfiguration.credentials.settings[@"parameter"]
. تكون هذه المَعلمة عادةً معرّف وحدة إعلانية تتطلّبه حزمة تطوير البرامج (SDK) التابعة لشبكة إعلانية عند إنشاء مثيل لكائن إعلان.
Swift
class SampleCustomEventBanner: NSObject, MediationBannerAd {
/// The Sample Ad Network banner ad.
var bannerAd: SampleBanner?
/// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
var delegate: MediationBannerAdEventDelegate?
/// Completion handler called after ad load
var completionHandler: GADMediationBannerLoadCompletionHandler?
func loadBanner(
for adConfiguration: MediationBannerAdConfiguration,
completionHandler: @escaping GADMediationBannerLoadCompletionHandler
) {
// Create the bannerView with the appropriate size.
let adSize = adConfiguration.adSize
bannerAd = SampleBanner(
frame: CGRect(x: 0, y: 0, width: adSize.size.width, height: adSize.size.height))
bannerAd?.delegate = self
bannerAd?.adUnit = adConfiguration.credentials.settings["parameter"] as? String
let adRequest = SampleAdRequest()
adRequest.testMode = adConfiguration.isTestRequest
self.completionHandler = completionHandler
bannerAd?.fetchAd(adRequest)
}
}
Objective-C
#import "SampleCustomEventBanner.h"
@interface SampleCustomEventBanner () <SampleBannerAdDelegate,
GADMediationBannerAd> {
/// The sample banner ad.
SampleBanner *_bannerAd;
/// The completion handler to call when the ad loading succeeds or fails.
GADMediationBannerLoadCompletionHandler _loadCompletionHandler;
/// The ad event delegate to forward ad rendering events to the Google Mobile
/// Ads SDK.
id <GADMediationBannerAdEventDelegate> _adEventDelegate;
}
@end
@implementation SampleCustomEventBanner
- (void)loadBannerForAdConfiguration:
(GADMediationBannerAdConfiguration *)adConfiguration
completionHandler:(GADMediationBannerLoadCompletionHandler)
completionHandler {
__block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
__block GADMediationBannerLoadCompletionHandler originalCompletionHandler =
[completionHandler copy];
_loadCompletionHandler = ^id<GADMediationBannerAdEventDelegate>(
_Nullable id<GADMediationBannerAd> ad, NSError *_Nullable error) {
// Only allow completion handler to be called once.
if (atomic_flag_test_and_set(&completionHandlerCalled)) {
return nil;
}
id<GADMediationBannerAdEventDelegate> delegate = nil;
if (originalCompletionHandler) {
// Call original handler and hold on to its return value.
delegate = originalCompletionHandler(ad, error);
}
// Release reference to handler. Objects retained by the handler will also
// be released.
originalCompletionHandler = nil;
return delegate;
};
NSString *adUnit = adConfiguration.credentials.settings[@"parameter"];
_bannerAd = [[SampleBanner alloc]
initWithFrame:CGRectMake(0, 0, adConfiguration.adSize.size.width,
adConfiguration.adSize.size.height)];
_bannerAd.adUnit = adUnit;
_bannerAd.delegate = self;
SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
adRequest.testMode = adConfiguration.isTestRequest;
[_bannerAd fetchAd:adRequest];
}
سواء تم جلب الإعلان بنجاح أو حدث خطأ، عليك استدعاء GADMediationBannerLoadCompletionHandler
. في حال النجاح، مرِّر الفئة التي تنفّذ GADMediationBannerAd
مع قيمة nil
لمَعلمة الخطأ. وفي حال التعذّر، مرِّر الخطأ الذي
واجهته.
عادةً، يتم تنفيذ هذه الطرق داخل عمليات ردّ الاتصال من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية التي ينفّذها المحوّل. في هذا المثال، تحتوي حزمة تطوير البرامج (SDK) النموذجية على SampleBannerAdDelegate
مع عمليات رد اتصال ذات صلة:
Swift
func bannerDidLoad(_ banner: SampleBanner) {
if let handler = completionHandler {
delegate = handler(self, nil)
}
}
func banner(
_ banner: SampleBanner, didFailToLoadAdWith errorCode: SampleErrorCode
) {
let error =
SampleCustomEventUtilsSwift.SampleCustomEventErrorWithCodeAndDescription(
code: SampleCustomEventErrorCodeSwift
.SampleCustomEventErrorAdLoadFailureCallback,
description:
"Sample SDK returned an ad load failure callback with error code: \(errorCode)"
)
if let handler = completionHandler {
delegate = handler(nil, error)
}
}
Objective-C
- (void)bannerDidLoad:(SampleBanner *)banner {
_adEventDelegate = _loadCompletionHandler(self, nil);
}
- (void)banner:(SampleBanner *)banner
didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
NSError *error = SampleCustomEventErrorWithCodeAndDescription(
SampleCustomEventErrorAdLoadFailureCallback,
[NSString stringWithFormat:@"Sample SDK returned an ad load failure "
@"callback with error code: %@",
errorCode]);
_adEventDelegate = _loadCompletionHandler(nil, error);
}
يتطلّب GADMediationBannerAd
تنفيذ السمة UIView
:
Swift
var view: UIView {
return bannerAd ?? UIView()
}
Objective-C
- (nonnull UIView *)view {
return _bannerAd;
}
بعد طلب GADMediationBannerLoadCompletionHandler
باستخدام إعلان تم تحميله،
يمكن للمحوّل استخدام عنصر التفويض GADMediationBannerAdEventDelegate
الذي تم عرضه
لإعادة توجيه أحداث العرض من حزمة SDK التابعة لجهة خارجية إلى
حزمة SDK لإعلانات Google على الأجهزة الجوّالة. تنفّذ الفئة SampleCustomEventBanner
البروتوكول SampleBannerAdDelegate
لإعادة توجيه عمليات رد الاتصال من شبكة الإعلانات النموذجية إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.
من المهم أن يعيد توجيه الحدث المخصّص أكبر عدد ممكن من عمليات معاودة الاتصال هذه، لكي يتلقّى تطبيقك الأحداث المكافئة من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.
في ما يلي مثال على استخدام عمليات معاودة الاتصال:
Swift
func bannerWillLeaveApplication(_ banner: SampleBanner) {
delegate?.reportClick()
}
Objective-C
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
[_adEventDelegate reportClick];
}
بهذا تكون قد أكملت عملية تنفيذ الأحداث المخصّصة لـ "إعلانات البانر". يتوفّر المثال الكامل على GitHub.
يمكنك استخدامها مع شبكة إعلانية متوافقة أو تعديلها لعرض إعلانات بانر للأحداث المخصّصة.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-09-02 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-09-02 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eTo request a banner ad within a custom event, create a class that implements \u003ccode\u003eGADMediationAdapter\u003c/code\u003e and the \u003ccode\u003eloadBanner:adConfiguration:completionHandler:\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eA separate class implementing \u003ccode\u003eGADMediationBannerAd\u003c/code\u003e should handle loading the ad, reporting events to the Google Mobile Ads SDK, and providing a \u003ccode\u003eUIView\u003c/code\u003e property for display.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eGADMediationBannerLoadCompletionHandler\u003c/code\u003e is called upon ad load success or failure, passing the \u003ccode\u003eGADMediationBannerAd\u003c/code\u003e instance or an error, respectively.\u003c/p\u003e\n"],["\u003cp\u003eForward relevant ad events (like clicks) from the third-party ad network SDK to the Google Mobile Ads SDK using the \u003ccode\u003eGADMediationBannerAdEventDelegate\u003c/code\u003e received from the \u003ccode\u003eGADMediationBannerLoadCompletionHandler\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eRefer to the complete custom event example on GitHub for implementation details and guidance.\u003c/p\u003e\n"]]],["To request a banner ad via custom events, implement `GADMediationAdapter` and `loadBanner:adConfiguration:completionHandler:`, delegating to a class that implements `GADMediationBannerAd`. This class is responsible for loading the banner, implementing `GADMediationBannerAd`, and reporting ad event callbacks. The `loadBanner:` method within this class fetches the ad, and then invokes a completion handler (`GADMediationBannerLoadCompletionHandler`) whether loading succeeds or fails, passing the banner ad or an error, respectively. Finally, use `GADMediationBannerAdEventDelegate` to forward presentation events.\n"],null,["Prerequisites\n\nComplete the [custom events setup](/ad-manager/mobile-ads-sdk/ios/custom-events/setup).\n\nRequest a banner ad\n\nWhen the custom event line item is reached in the waterfall mediation chain,\nthe `loadBanner:adConfiguration:completionHandler:` method is called on the\nclass name you provided when [creating a custom\nevent](/ad-manager/mobile-ads-sdk/ios/custom-events/setup#create). In this case,\nthat method is in `SampleCustomEvent`, which then calls\nthe `loadBanner:adConfiguration:completionHandler:` method in\n`SampleCustomEventBanner`.\n\nTo request a banner ad, create or modify a class that implements\n`GADMediationAdapter` and `loadBanner:adConfiguration:completionHandler:`. If a\nclass that extends `GADMediationAdapter` already exists, implement\n`loadBanner:adConfiguration:completionHandler:` there. Additionally, create a\nnew class to implement `GADMediationBannerAd`.\n\nIn our custom event example,\n[`SampleCustomEvent`](//github.com/googleads/googleads-mobile-ios-mediation/blob/main/example/CustomEvent/SampleCustomEvent.m) implements\nthe `GADMediationAdapter` interface and then delegates to\n`SampleCustomEventBanner`. \n\nSwift \n\n```swift\nimport GoogleMobileAds\n\nclass SampleCustomEvent: NSObject, MediationAdapter {\n\n fileprivate var bannerAd: SampleCustomEventBanner?\n ...\n\n func loadBanner(\n for adConfiguration: MediationBannerAdConfiguration,\n completionHandler: @escaping GADMediationBannerLoadCompletionHandler\n ) {\n self.bannerAd = SampleCustomEventBanner()\n self.bannerAd?.loadBanner(\n for: adConfiguration, completionHandler: completionHandler)\n }\n}\n```\n\nObjective-C \n\n```objective-c\n#import \"SampleCustomEvent.h\"\n\n@implementation SampleCustomEvent\n...\n\nSampleCustomEventBanner *sampleBanner;\n\n- (void)loadBannerForAdConfiguration:\n (GADMediationBannerAdConfiguration *)adConfiguration\n completionHandler:(GADMediationBannerLoadCompletionHandler)\n completionHandler {\n sampleBanner = [[SampleCustomEventBanner alloc] init];\n [sampleBanner loadBannerForAdConfiguration:adConfiguration\n completionHandler:completionHandler];\n}\n```\n\n`SampleCustomEventBanner` is responsible for the following tasks:\n\n- Loading the banner ad and invoking a\n [`GADMediationBannerLoadCompletionHandler`](/ad-manager/mobile-ads-sdk/ios/api/reference/Protocols/GADMediationAdapter) method once\n loading completes.\n\n- Implementing the `GADMediationBannerAd` protocol.\n\n- Receiving and reporting ad event callbacks to Google Mobile Ads SDK.\n\nThe optional parameter defined in the Ad Manager UI is\nincluded in the ad configuration.\nThe parameter can be accessed through\n`adConfiguration.credentials.settings[@\"parameter\"]`. This parameter is\ntypically an ad unit identifier that an ad network SDK requires when\ninstantiating an ad object. \n\nSwift \n\n```swift\nclass SampleCustomEventBanner: NSObject, MediationBannerAd {\n /// The Sample Ad Network banner ad.\n var bannerAd: SampleBanner?\n\n /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.\n var delegate: MediationBannerAdEventDelegate?\n\n /// Completion handler called after ad load\n var completionHandler: GADMediationBannerLoadCompletionHandler?\n\n func loadBanner(\n for adConfiguration: MediationBannerAdConfiguration,\n completionHandler: @escaping GADMediationBannerLoadCompletionHandler\n ) {\n // Create the bannerView with the appropriate size.\n let adSize = adConfiguration.adSize\n bannerAd = SampleBanner(\n frame: CGRect(x: 0, y: 0, width: adSize.size.width, height: adSize.size.height))\n bannerAd?.delegate = self\n bannerAd?.adUnit = adConfiguration.credentials.settings[\"parameter\"] as? String\n let adRequest = SampleAdRequest()\n adRequest.testMode = adConfiguration.isTestRequest\n self.completionHandler = completionHandler\n bannerAd?.fetchAd(adRequest)\n }\n}\n```\n\nObjective-C \n\n```objective-c\n#import \"SampleCustomEventBanner.h\"\n\n@interface SampleCustomEventBanner () \u003cSampleBannerAdDelegate,\n GADMediationBannerAd\u003e {\n /// The sample banner ad.\n SampleBanner *_bannerAd;\n\n /// The completion handler to call when the ad loading succeeds or fails.\n GADMediationBannerLoadCompletionHandler _loadCompletionHandler;\n\n /// The ad event delegate to forward ad rendering events to the Google Mobile\n /// Ads SDK.\n id \u003cGADMediationBannerAdEventDelegate\u003e _adEventDelegate;\n}\n@end\n\n@implementation SampleCustomEventBanner\n\n- (void)loadBannerForAdConfiguration:\n (GADMediationBannerAdConfiguration *)adConfiguration\n completionHandler:(GADMediationBannerLoadCompletionHandler)\n completionHandler {\n __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;\n __block GADMediationBannerLoadCompletionHandler originalCompletionHandler =\n [completionHandler copy];\n\n _loadCompletionHandler = ^id\u003cGADMediationBannerAdEventDelegate\u003e(\n _Nullable id\u003cGADMediationBannerAd\u003e ad, NSError *_Nullable error) {\n // Only allow completion handler to be called once.\n if (atomic_flag_test_and_set(&completionHandlerCalled)) {\n return nil;\n }\n\n id\u003cGADMediationBannerAdEventDelegate\u003e delegate = nil;\n if (originalCompletionHandler) {\n // Call original handler and hold on to its return value.\n delegate = originalCompletionHandler(ad, error);\n }\n\n // Release reference to handler. Objects retained by the handler will also\n // be released.\n originalCompletionHandler = nil;\n\n return delegate;\n };\n\n NSString *adUnit = adConfiguration.credentials.settings[@\"parameter\"];\n _bannerAd = [[SampleBanner alloc]\n initWithFrame:CGRectMake(0, 0, adConfiguration.adSize.size.width,\n adConfiguration.adSize.size.height)];\n _bannerAd.adUnit = adUnit;\n _bannerAd.delegate = self;\n SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];\n adRequest.testMode = adConfiguration.isTestRequest;\n [_bannerAd fetchAd:adRequest];\n}\n```\n\nWhether the ad is successfully fetched or encounters an error, you\nwould call `GADMediationBannerLoadCompletionHandler`. In the event of success,\npass through the class that implements `GADMediationBannerAd` with a `nil` value\nfor the error parameter; in the event of failure, pass through the error you\nencountered.\n\nTypically, these methods are implemented inside callbacks from the\nthird-party SDK your adapter implements. For this example, the Sample SDK\nhas a `SampleBannerAdDelegate` with relevant callbacks: \n\nSwift \n\n```swift\nfunc bannerDidLoad(_ banner: SampleBanner) {\n if let handler = completionHandler {\n delegate = handler(self, nil)\n }\n}\n\nfunc banner(\n _ banner: SampleBanner, didFailToLoadAdWith errorCode: SampleErrorCode\n) {\n let error =\n SampleCustomEventUtilsSwift.SampleCustomEventErrorWithCodeAndDescription(\n code: SampleCustomEventErrorCodeSwift\n .SampleCustomEventErrorAdLoadFailureCallback,\n description:\n \"Sample SDK returned an ad load failure callback with error code: \\(errorCode)\"\n )\n if let handler = completionHandler {\n delegate = handler(nil, error)\n }\n}\n```\n\nObjective-C \n\n```objective-c\n- (void)bannerDidLoad:(SampleBanner *)banner {\n _adEventDelegate = _loadCompletionHandler(self, nil);\n}\n\n- (void)banner:(SampleBanner *)banner\n didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {\n NSError *error = SampleCustomEventErrorWithCodeAndDescription(\n SampleCustomEventErrorAdLoadFailureCallback,\n [NSString stringWithFormat:@\"Sample SDK returned an ad load failure \"\n @\"callback with error code: %@\",\n errorCode]);\n _adEventDelegate = _loadCompletionHandler(nil, error);\n}\n```\n\n`GADMediationBannerAd` requires implementing a `UIView` property: \n\nSwift \n\n```swift\nvar view: UIView {\n return bannerAd ?? UIView()\n}\n```\n\nObjective-C \n\n```objective-c\n- (nonnull UIView *)view {\n return _bannerAd;\n}\n```\n\nForward mediation events to Google Mobile Ads SDK\n\nOnce you've called `GADMediationBannerLoadCompletionHandler` with a loaded ad,\nthe returned `GADMediationBannerAdEventDelegate` delegate object can then be\nused by the adapter to forward presentation events from the third-party SDK to\nGoogle Mobile Ads SDK. The `SampleCustomEventBanner` class implements the\n`SampleBannerAdDelegate` protocol to forward callbacks from the sample ad\nnetwork to Google Mobile Ads SDK.\n\nIt's important that your custom event forwards as many of these callbacks as\npossible, so that your app receives these equivalent events from Google Mobile Ads SDK.\nHere's an example of using callbacks: \n\nSwift \n\n```swift\nfunc bannerWillLeaveApplication(_ banner: SampleBanner) {\n delegate?.reportClick()\n}\n```\n\nObjective-C \n\n```objective-c\n- (void)bannerWillLeaveApplication:(SampleBanner *)banner {\n [_adEventDelegate reportClick];\n}\n```\n\nThis completes the custom events implementation for banner ads. The full example\nis available on\n[GitHub](//github.com/googleads/googleads-mobile-ios-mediation/tree/main/example/CustomEvent).\nYou can use it with an ad network that is already supported or modify it to\ndisplay custom event banner ads."]]