الأحداث المخصّصة للإعلانات التي تضم مكافأة
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المتطلبات الأساسية
أكمِل إعداد الأحداث المخصّصة.
طلب عرض إعلان مقابل مكافأة
عند الوصول إلى عنصر الحدث المخصّص في سلسلة التوسّط المتسلسلة، يتم استدعاء الطريقة loadRewarded:adConfiguration:completionHandler: على اسم الفئة الذي قدّمته عند إنشاء حدث مخصّص. في هذه الحالة، تكون الطريقة في SampleCustomEvent
، والتي تستدعي بعد ذلك الطريقة loadRewarded:adConfiguration:completionHandler:
في SampleCustomEventRewarded
.
لطلب إعلان مقابل مكافأة، أنشئ أو عدِّل فئة تنفّذ
GADMediationAdapter
وloadRewarded:adConfiguration:completionHandler:
. إذا كان هناك صف يوسّع GADMediationAdapter
، عليك تنفيذ loadRewarded:adConfiguration:completionHandler:
فيه. بالإضافة إلى ذلك،
أنشئ فئة جديدة لتنفيذ GADMediationRewardedAd
.
في مثال الحدث المخصّص،
تنفّذ SampleCustomEvent
الواجهة GADMediationAdapter
ثم تفوّض إلى
SampleCustomEventRewarded
.
Swift
import GoogleMobileAds
class SampleCustomEvent: NSObject, MediationAdapter {
fileprivate var rewardedAd: SampleCustomEventRewarded?
...
func loadRewarded(
for adConfiguration: MediationRewardedAdConfiguration,
completionHandler: @escaping GADMediationRewardedLoadCompletionHandler
) {
self.rewardedAd = SampleCustomEventRewarded()
self.rewardedAd?.loadRewarded(
for: adConfiguration, completionHandler: completionHandler)
}
}
Objective-C
#import "SampleCustomEvent.h"
@implementation SampleCustomEvent
...
SampleCustomEventRewarded *sampleRewarded;
- (void)loadRewardedForAdConfiguration:
(GADMediationRewardedAdConfiguration *)adConfiguration
completionHandler:
(GADMediationRewardedLoadCompletionHandler)
completionHandler {
sampleRewarded = [[SampleCustomEventRewarded alloc] init];
[sampleRewarded loadRewardedForAdConfiguration:adConfiguration
completionHandler:completionHandler];
}
يتحمّل "SampleCustomEventRewarded
" مسؤولية المهام التالية:
تحميل "الإعلان مقابل مكافأة"
تنفيذ بروتوكول GADMediationRewardedAd
تلقّي عمليات ردّ الاتصال الخاصة بأحداث الإعلانات وإعداد تقارير عنها في حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"
يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم AdMob ضمن إعدادات الإعلان.
يمكن الوصول إلى المَعلمة من خلال
adConfiguration.credentials.settings[@"parameter"]
. تكون هذه المَعلمة عادةً معرّف وحدة إعلانية تتطلّبه حزمة تطوير البرامج (SDK) التابعة لشبكة إعلانية عند إنشاء مثيل لكائن إعلان.
Swift
class SampleCustomEventRewarded: NSObject, MediationRewardedAd {
/// The Sample Ad Network rewarded ad.
var nativeAd: SampleRewarded?
/// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
var delegate: MediationRewardedAdEventDelegate?
/// Completion handler called after ad load.
var completionHandler: GADMediationRewardedLoadCompletionHandler?
func loadRewarded(
for adConfiguration: MediationRewardedAdConfiguration,
completionHandler: @escaping GADMediationRewardedLoadCompletionHandler
) {
rewarded = SampleRewarded.init(
adUnitID: adConfiguration.credentials.settings["parameter"] as? String)
rewarded?.delegate = self
let adRequest = SampleAdRequest()
adRequest.testMode = adConfiguration.isTestRequest
self.completionHandler = completionHandler
rewarded?.fetchAd(adRequest)
}
}
Objective-C
#import "SampleCustomEventRewarded.h"
@interface SampleCustomEventRewarded () <SampleRewardedAdDelegate,
GADMediationRewardedAd> {
/// The sample rewarded ad.
SampleRewarded *_rewardedAd;
/// The completion handler to call when the ad loading succeeds or fails.
GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;
/// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
id <GADMediationRewardedAdEventDelegate> _adEventDelegate;
}
@end
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
completionHandler:
(GADMediationRewardedLoadCompletionHandler)completionHandler {
__block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
__block GADMediationRewardedLoadCompletionHandler originalCompletionHandler =
[completionHandler copy];
_loadCompletionHandler = ^id<GADMediationRewardedAdEventDelegate>(
_Nullable id<GADMediationRewardedAd> ad, NSError *_Nullable error) {
// Only allow completion handler to be called once.
if (atomic_flag_test_and_set(&completionHandlerCalled)) {
return nil;
}
id<GADMediationRewardedAdEventDelegate> 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"];
_rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
_rewardedAd.delegate = self;
SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
adRequest.testMode = adConfiguration.isTestRequest;
[_rewardedAd fetchAd:adRequest];
}
سواء تم جلب الإعلان بنجاح أو حدث خطأ، عليك استدعاء GADMediationRewardedLoadCompletionHandler
. في حال النجاح، مرِّر الفئة التي تنفّذ GADMediationRewardedAd
مع قيمة nil
لمَعلمة الخطأ. وفي حال حدوث خطأ، مرِّر الخطأ الذي واجهته.
عادةً، يتم تنفيذ هذه الطرق داخل عمليات ردّ الاتصال من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية التي ينفّذها المحوّل. في هذا المثال، تحتوي حزمة تطوير البرامج (SDK) النموذجية على SampleRewardedAdDelegate
مع عمليات رد اتصال ذات صلة:
Swift
func rewardedDidLoad(_ interstitial: SampleRewarded) {
if let handler = completionHandler {
delegate = handler(self, nil)
}
}
func rewarded(
rewarded: SampleRewarded, didFailToLoadAdWith errorCode: SampleErrorCode
) {
let error =
SampleCustomEventUtils.SampleCustomEventErrorWithCodeAndDescription(
code: SampleCustomEventErrorCode
.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)rewardedDidLoad:(SampleRewarded *)rewarded {
_adEventDelegate = _loadCompletionHandler(self, nil);
}
- (void)rewarded:(SampleInterstitial *)rewarded
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);
}
يتطلّب GADMediationrewardedAd
تنفيذ طريقة present(viewController:)
لعرض الإعلان:
Swift
func present(from viewController: UIViewController) {
if let rewarded = rewarded, rewarded.isRewardedLoaded {
rewarded.show()
}
}
Objective-C
- (void)presentFromViewController:(UIViewController *)viewController {
if ([_rewardedAd isRewardedLoaded]) {
[_rewardedAd show];
} else {
NSError *error = SampleCustomEventErrorWithCodeAndDescription(
SampleCustomEventErrorAdNotLoaded,
[NSString stringWithFormat:
@"The rewarded ad failed to present because the ad was not loaded."]);
[_adEventDelegate didFailToPresentWithError:error]
}
}
إعادة توجيه أحداث الوساطة إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"
بعد طلب GADMediationRewardedLoadCompletionHandler
باستخدام إعلان تم تحميله، يمكن للمحوّل استخدام عنصر التفويض GADMediationRewardedAdEventDelegate
الذي تم عرضه لإعادة توجيه أحداث العرض من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة". تنفّذ الفئة SampleCustomEventRewarded
البروتوكول SampleRewardedAdDelegate
لإعادة توجيه عمليات رد الاتصال من شبكة الإعلانات النموذجية إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.
من المهم أن يعيد توجيه الحدث المخصّص أكبر عدد ممكن من عمليات معاودة الاتصال هذه، لكي يتلقّى تطبيقك الأحداث المكافئة من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.
في ما يلي مثال على استخدام عمليات معاودة الاتصال:
Swift
func rewardedAdDidPresent(_ rewarded: SampleRewardedAd) {
delegate?.willPresentFullScreenVideo()
delegate?.didStartVideo()
}
func rewardedAdUserDidEarnReward(_ rewarded: SampleRewardedAd) {
AdReward aReward = AdReward("", rewarded)
delegate.didRewardUser()
}
Objective-C
- (void)rewardedAdDidPresent:(SampleRewardedAd *)rewardedAd {
[_adEventDelegate willPresentFullScreenView];
[_adEventDelegate didStartVideo];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd
userDidEarnReward:(NSUInteger)reward {
GADAdReward *aReward = [[GADAdReward alloc]
initWithRewardType:@""
rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
[_adEventDelegate didRewardUserWithReward];
}
بهذا تكتمل عملية تنفيذ الأحداث المخصّصة للإعلانات مقابل مكافأة. يتوفّر المثال الكامل على 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 rewarded ad through a custom event, implement the \u003ccode\u003eGADMediationAdapter\u003c/code\u003e and \u003ccode\u003eloadRewarded:adConfiguration:completionHandler:\u003c/code\u003e methods.\u003c/p\u003e\n"],["\u003cp\u003eCreate a separate class that implements \u003ccode\u003eGADMediationRewardedAd\u003c/code\u003e to handle ad loading, the \u003ccode\u003eGADMediationRewardedAd\u003c/code\u003e protocol, and ad event callbacks to the Google Mobile Ads SDK.\u003c/p\u003e\n"],["\u003cp\u003eUse the \u003ccode\u003eGADMediationRewardedLoadCompletionHandler\u003c/code\u003e to notify the Google Mobile Ads SDK about ad load success or failure.\u003c/p\u003e\n"],["\u003cp\u003eForward ad events from the third-party ad network SDK to the Google Mobile Ads SDK using the \u003ccode\u003eGADMediationRewardedAdEventDelegate\u003c/code\u003e object.\u003c/p\u003e\n"],["\u003cp\u003eThe provided code snippets and the full example on GitHub can be used to create or modify custom events for rewarded ads.\u003c/p\u003e\n"]]],["To implement rewarded ads, create a class extending `GADMediationAdapter` and `GADMediationRewardedAd`, exemplified by `SampleCustomEvent` and `SampleCustomEventRewarded`. `SampleCustomEvent` calls `loadRewarded:` in `SampleCustomEventRewarded`, which loads the ad, implements `GADMediationRewardedAd`, and manages event callbacks. Ad configuration parameters, like ad unit IDs, can be accessed. After loading, `GADMediationRewardedLoadCompletionHandler` reports success or failure. `present(viewController:)` displays the ad. Forward relevant presentation events from the ad network SDK to the Google Mobile Ads SDK.\n"],null,["Prerequisites\n\nComplete the [custom events setup](/admob/ios/custom-events/setup).\n\nRequest a rewarded ad\n\nWhen the custom event line item is reached in the waterfall mediation chain,\nthe loadRewarded:adConfiguration:completionHandler: method is called on the\nclass name you provided when [creating a custom\nevent](/admob/ios/custom-events/setup#create). In this case,\nthat method is in `SampleCustomEvent`, which then calls\nthe `loadRewarded:adConfiguration:completionHandler:` method in\n`SampleCustomEventRewarded`.\n\nTo request a rewarded ad, create or modify a class that implements\n`GADMediationAdapter` and `loadRewarded:adConfiguration:completionHandler:`. If\na class that extends `GADMediationAdapter` already exists, implement\n`loadRewarded:adConfiguration:completionHandler:` there. Additionally,\ncreate a new class to implement `GADMediationRewardedAd`.\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`SampleCustomEventRewarded`. \n\nSwift \n\n```swift\nimport GoogleMobileAds\n\nclass SampleCustomEvent: NSObject, MediationAdapter {\n\n fileprivate var rewardedAd: SampleCustomEventRewarded?\n ...\n\n func loadRewarded(\n for adConfiguration: MediationRewardedAdConfiguration,\n completionHandler: @escaping GADMediationRewardedLoadCompletionHandler\n ) {\n self.rewardedAd = SampleCustomEventRewarded()\n self.rewardedAd?.loadRewarded(\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\nSampleCustomEventRewarded *sampleRewarded;\n\n- (void)loadRewardedForAdConfiguration:\n (GADMediationRewardedAdConfiguration *)adConfiguration\n completionHandler:\n (GADMediationRewardedLoadCompletionHandler)\n completionHandler {\n sampleRewarded = [[SampleCustomEventRewarded alloc] init];\n [sampleRewarded loadRewardedForAdConfiguration:adConfiguration\n completionHandler:completionHandler];\n}\n```\n\n`SampleCustomEventRewarded` is responsible for the following tasks:\n\n- Loading the rewarded ad.\n\n- Implementing the `GADMediationRewardedAd` protocol.\n\n- Receiving and reporting ad event callbacks to Google Mobile Ads SDK.\n\nThe optional parameter defined in the AdMob 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 SampleCustomEventRewarded: NSObject, MediationRewardedAd {\n /// The Sample Ad Network rewarded ad.\n var nativeAd: SampleRewarded?\n\n /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.\n var delegate: MediationRewardedAdEventDelegate?\n\n /// Completion handler called after ad load.\n var completionHandler: GADMediationRewardedLoadCompletionHandler?\n\n func loadRewarded(\n for adConfiguration: MediationRewardedAdConfiguration,\n completionHandler: @escaping GADMediationRewardedLoadCompletionHandler\n ) {\n rewarded = SampleRewarded.init(\n adUnitID: adConfiguration.credentials.settings[\"parameter\"] as? String)\n rewarded?.delegate = self\n let adRequest = SampleAdRequest()\n adRequest.testMode = adConfiguration.isTestRequest\n self.completionHandler = completionHandler\n rewarded?.fetchAd(adRequest)\n }\n}\n```\n\nObjective-C \n\n```objective-c\n#import \"SampleCustomEventRewarded.h\"\n\n@interface SampleCustomEventRewarded () \u003cSampleRewardedAdDelegate,\n GADMediationRewardedAd\u003e {\n /// The sample rewarded ad.\n SampleRewarded *_rewardedAd;\n\n /// The completion handler to call when the ad loading succeeds or fails.\n GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;\n\n /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.\n id \u003cGADMediationRewardedAdEventDelegate\u003e _adEventDelegate;\n}\n@end\n\n- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration\n completionHandler:\n (GADMediationRewardedLoadCompletionHandler)completionHandler {\n __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;\n __block GADMediationRewardedLoadCompletionHandler originalCompletionHandler =\n [completionHandler copy];\n\n _loadCompletionHandler = ^id\u003cGADMediationRewardedAdEventDelegate\u003e(\n _Nullable id\u003cGADMediationRewardedAd\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\u003cGADMediationRewardedAdEventDelegate\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 be released.\n originalCompletionHandler = nil;\n\n return delegate;\n };\n\n NSString *adUnit = adConfiguration.credentials.settings[@\"parameter\"];\n _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];\n _rewardedAd.delegate = self;\n SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];\n adRequest.testMode = adConfiguration.isTestRequest;\n [_rewardedAd fetchAd:adRequest];\n}\n```\n\nWhether the ad is successfully fetched or encounters an error, you\nwould call `GADMediationRewardedLoadCompletionHandler`. In the event of\nsuccess, pass through the class that implements `GADMediationRewardedAd`\nwith a `nil` value for the error parameter; in the event of failure, pass\nthrough the error you encountered.\n\nTypically, these methods are implemented inside callbacks from the\nthird-party SDK your adapter implements. For this example, the Sample SDK\nhas a `SampleRewardedAdDelegate` with relevant callbacks: \n\nSwift \n\n```swift\nfunc rewardedDidLoad(_ interstitial: SampleRewarded) {\n if let handler = completionHandler {\n delegate = handler(self, nil)\n }\n}\n\nfunc rewarded(\n rewarded: SampleRewarded, didFailToLoadAdWith errorCode: SampleErrorCode\n) {\n let error =\n SampleCustomEventUtils.SampleCustomEventErrorWithCodeAndDescription(\n code: SampleCustomEventErrorCode\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)rewardedDidLoad:(SampleRewarded *)rewarded {\n _adEventDelegate = _loadCompletionHandler(self, nil);\n}\n\n- (void)rewarded:(SampleInterstitial *)rewarded\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`GADMediationrewardedAd` requires implementing a `present(viewController:)`\nmethod to display the ad: \n\nSwift \n\n```swift\nfunc present(from viewController: UIViewController) {\n if let rewarded = rewarded, rewarded.isRewardedLoaded {\n rewarded.show()\n }\n}\n```\n\nObjective-C \n\n```objective-c\n- (void)presentFromViewController:(UIViewController *)viewController {\n if ([_rewardedAd isRewardedLoaded]) {\n [_rewardedAd show];\n } else {\n NSError *error = SampleCustomEventErrorWithCodeAndDescription(\n SampleCustomEventErrorAdNotLoaded,\n [NSString stringWithFormat:\n @\"The rewarded ad failed to present because the ad was not loaded.\"]);\n [_adEventDelegate didFailToPresentWithError:error]\n }\n}\n```\n\nForward mediation events to Google Mobile Ads SDK\n\nOnce you've called `GADMediationRewardedLoadCompletionHandler` with a loaded\nad, the returned `GADMediationRewardedAdEventDelegate` delegate object can\nthen be used by the adapter to forward presentation events from the third-party\nSDK to Google Mobile Ads SDK. The `SampleCustomEventRewarded` class\nimplements the `SampleRewardedAdDelegate` protocol to forward callbacks from\nthe sample ad network 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 rewardedAdDidPresent(_ rewarded: SampleRewardedAd) {\n delegate?.willPresentFullScreenVideo()\n delegate?.didStartVideo()\n}\n\nfunc rewardedAdUserDidEarnReward(_ rewarded: SampleRewardedAd) {\n AdReward aReward = AdReward(\"\", rewarded)\n delegate.didRewardUser()\n}\n```\n\nObjective-C \n\n```objective-c\n- (void)rewardedAdDidPresent:(SampleRewardedAd *)rewardedAd {\n [_adEventDelegate willPresentFullScreenView];\n [_adEventDelegate didStartVideo];\n}\n\n- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd\n userDidEarnReward:(NSUInteger)reward {\n GADAdReward *aReward = [[GADAdReward alloc]\n initWithRewardType:@\"\"\n rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];\n [_adEventDelegate didRewardUserWithReward];\n}\n```\n\nThis completes the custom events implementation for rewarded ads. The full\nexample is available on\n[GitHub](//github.com/googleads/googleads-mobile-ios-mediation/tree/master/example/CustomEvent).\nYou can use it with an ad network that is already supported or modify it to\ndisplay custom event rewarded ads."]]