پیاده سازی یک آداپتور تبلیغاتی با پاداش

مهم: استفاده شما از Google Mobile Ads SDK در ارتباط با سرویس‌های میانجی‌گری تحت شرایط خدمات میانجیگری است.

یک آداپتور میانجی پیام‌ها و درخواست‌ها را از Google Mobile Ads SDK دریافت می‌کند و با یک SDK شبکه شخص ثالث ارتباط برقرار می‌کند تا این درخواست‌ها را برآورده کند.

این راهنما برای شبکه‌های تبلیغاتی در نظر گرفته شده است که به دنبال ایجاد یک آداپتور میانجی آگهی با پاداش برای میانجیگری تبلیغات موبایلی Google هستند. یک نمونه SDK در قطعه کد زیر برای اهداف نمایشی استفاده می شود. می‌توانید اجرای کامل یک آداپتور ساخته شده برای این نمونه SDK را در پروژه iOSMediation ما بیابید. این راهنما نحوه ساخت آداپتور را توضیح می دهد.

نام کلاس آداپتور و پارامترهای سرور را تعریف کنید

شبکه‌های تبلیغاتی که از طریق پلتفرم میانجی‌گری AdMob انجام می‌شوند معمولاً برای شناسایی ناشر به یک یا چند شناسه نیاز دارند. این شناسه‌ها به‌عنوان پارامترهای سرور نشان داده می‌شوند و هنگام پیکربندی یک شبکه تبلیغاتی شخص ثالث برای میانجی‌گری در رابط کاربری AdMob تعریف می‌شوند.

قبل از ایجاد یک آداپتور میانجی، باید نام کلاس آداپتور خود و سایر پارامترهای مورد نیاز را برای دسترسی به شبکه تبلیغاتی خود در اختیار Google قرار دهید.

مطابق با پروتکل GADMediationAdapter

اولین قدم این است که کلاس آداپتور خود را وادار کنید پروتکل GADMediationAdapter را پیاده سازی کند:

#import <Foundation/Foundation.h>
#import <GoogleMobileAds/GoogleMobileAds.h>
#import <SampleAdSDK/SampleAdSDK.h>

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

این تغییر تضمین می کند که کلاس شما چندین متد را که در زیر مورد بحث قرار گرفته است را پیاده سازی می کند.

گزارش کلاس اضافی

اگر شبکه شخص ثالث بخواهد به ناشران اجازه دهد تا پارامترهای اختیاری اضافی را برای یک درخواست آگهی ارسال کنند، کلاس extras باید از روش networkExtrasClass برگردانده شود. اگر شخص ثالث از موارد اضافی ارائه شده توسط ناشر پشتیبانی نمی کند، Nil برگردانید.

#import <GoogleMobileAds/GoogleMobileAds.h>

@interface SampleExtras : NSObject<GADAdNetworkExtras>

/// Use this to indicate if debug mode is on for logging.
@property(nonatomic) BOOL debugLogging;

/// Use this to indicate whether to mute audio for video ads.
@property(nonatomic) BOOL muteAudio;

@end

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleExtras class];
}
...
@end

گزارش شماره نسخه

آداپتور باید هم نسخه خود آداپتور و هم نسخه SDK شخص ثالث را به Google Mobile Ads SDK گزارش دهد. نسخه ها با استفاده از GADVersionNumberگزارش شده اند.

آداپتورهای منبع باز و نسخه شده Google از طرح نسخه آداپتور 4 رقمی استفاده می کنند، اما GADVersionNumberفقط 3 رقم را مجاز می کند. برای حل این مشکل، توصیه می شود که دو رقم آخر را در نسخه پچ ترکیب کنید، همانطور که در زیر نشان داده شده است:

l10n

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = SampleSDKVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 3) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    version.patchVersion = [versionComponents[2] integerValue];
  }
  return version;
}

+ (GADVersionNumber)version {
  NSString *versionString = SampleAdapterVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 4) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    // Adapter versions have 2 patch versions. Multiply the first patch by 100.
    version.patchVersion =
        [versionComponents[2] integerValue] * 100 + [versionComponents[3] integerValue];
  }
  return version;
}
...
@end

آداپتور را راه اندازی کنید

هنگامی که یک برنامه SDK تبلیغات تلفن همراه Google را راه‌اندازی می‌کند، setUpWithConfiguration:completionHandler: روی همه آداپتورهای پیکربندی‌شده برای برنامه در رابط کاربری AdMob فراخوانی می‌شود.

آرگومان GADMediationServerConfiguration اطلاعاتی را در مورد همه مکان‌های پیکربندی شده برای برنامه در رابط کاربری AdMob ارائه می‌کند. از این اطلاعات برای راه اندازی SDK شبکه تبلیغاتی خود استفاده کنید. هنگامی که SDK شبکه تبلیغاتی شما راه اندازی شد، آرگومان GADMediationAdapterSetUpCompletionBlock را فراخوانی کنید. این بلوک به شما امکان می‌دهد با فراخوانی کنترل‌کننده تکمیل با nil یا یک شی NSError ، یک اولیه‌سازی موفق یا ناموفق را به Google Mobile Ads SDK گزارش دهید.

#import "SampleAdapter.h"

@implementation SampleAdapter
...
+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  // Since the Sample SDK doesn't need to be initialized, the completion
  //handler is called directly here.
  completionHandler(nil);
}
...
@end

درخواست آگهی با پاداش

هنگامی که یک برنامه یک تبلیغ پاداش را با Google Mobile Ads SDK بارگیری می‌کند، اگر شبکه تبلیغاتی شما در آبشار میانجی دسترسی داشته باشد loadRewardedAdForAdConfiguration:completionHandler: روی آداپتور فراخوانی می‌شود.

GADRewardedLoadCompletionHandler به شما امکان می‌دهد با ارائه ارجاع به یک شی منطبق با پروتکل GADMediationRewardedAd یا یک بار آگهی ناموفق با ارائه مرجع nil و یک شی NSError ، بار آگهی موفق را به Google Mobile Ads SDK گزارش دهید. فراخوانی کنترل‌کننده تکمیل بار، یک GADMediationRewardedAdEventDelegate را برمی‌گرداند که آداپتور شما باید آن را برای چرخه عمر تبلیغ نگه دارد تا هر رویداد بعدی را به Google Mobile Ads SDK اطلاع دهد.

#import "SampleAdapter.h"

@interface SampleAdapter () <GADMediationRewardedAd> {
  /// Rewarded ads from Sample SDK.
  SampleRewardedAd *_rewardedAd;

  /// Handles any callback when the sample rewarded ad finishes loading.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// Delegate for receiving rewarded ad notifications.
  __weak id<GADMediationRewardedAdEventDelegate> _rewardedAdDelegate;
}
@end

@implementation SampleAdapter
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  _loadCompletionHandler = completionHandler;

  NSString *adUnit = adConfiguration.credentials.settings[SampleSDKAdUnitIDKey];
  SampleExtras *extras = adConfiguration.extras;

  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.enableDebugLogging = extras.enableDebugLogging;

  /// Check the extras to see if the request should be customized.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.mute = extras.muteAudio;

  /// Set the delegate on the rewarded ad to listen for callbacks from the Sample SDK.
  _rewardedAd.delegate = self;
  [_rewardedAd fetchAd:request];
}
...
@end

رویدادهای بارگذاری آگهی را پخش کنید

این مسئولیت آداپتور است که به تماس‌های SDK شخص ثالث گوش دهد و آنها را به پاسخ تماس SDK تبلیغات موبایل Google مربوطه نشان دهد.

با فراخوانی loadCompletionHandler با یک آگهی یا یک خطا، موفقیت یا شکست رویدادهای بارگذاری آگهی شخص ثالث را گزارش دهید. اگر کنترل کننده تکمیل با یک تبلیغ و بدون خطا فراخوانی شود، یک شی نمایندگی رویداد آگهی برگردانده می شود. به این نماینده اشاره کنید تا آداپتور شما بتواند بعداً رویدادهای ارائه را انتقال دهد.

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:GADErrorNoFill
                                              userInfo:nil]);
}

آگهی را نمایش دهید

وقتی برنامه از Google Mobile Ads SDK می‌خواهد تبلیغ پاداش را ارائه کند، SDK روش presentFromViewController: را در نمونه GADMediationRewardedAd ارائه شده در تماس با کنترل‌کننده تکمیل بار فراخوانی می‌کند. در اینجا باید تبلیغ پاداش را ارائه دهید:

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if (!_rewardedAd.isReady) {
    NSError *error =
        [NSError errorWithDomain:kAdapterErrorDomain
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [_rewardedAdDelegate didFailToPresentWithError:error];
    return;
  }
  [_rewardedAd presentFromRootViewController:viewController];
}

رویدادهای تبلیغاتی را به SDK تبلیغات موبایل گزارش دهید

پس از نمایش آگهی، آداپتور باید رویدادهای چرخه عمر ارائه آگهی را با استفاده از همان نماینده رویداد تبلیغاتی که در زمان بارگذاری موفقیت آمیز آگهی بازگردانده شده است، گزارش کند.

- (void)rewardedAdDidPresent:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willPresentFullScreenView];
  [_rewardedAdDelegate didStartVideo];
  [_rewardedAdDelegate reportImpression];
}

- (void)rewardedAdDidDismiss:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willDismissFullScreenView];
  [_rewardedAdDelegate didEndVideo];
  [_rewardedAdDelegate didDismissFullScreenView];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@"GADMediationAdapterSampleAdNetwork"
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [_rewardedAdDelegate didRewardUserWithReward:aReward];
}

رویدادهای تبلیغاتی که باید به Google Mobile Ads SDK گزارش شوند به تفصیل در زیر آمده است:

رویداد تبلیغاتی	شرح
willPresentFullScreenView	به Google Mobile Ads SDK اطلاع می دهد که تبلیغ نمایش داده می شود.
didStartVideo	به Google Mobile Ads SDK اطلاع می دهد که یک تبلیغ پاداش شروع به پخش کرد.
ReportImpression	به Google Mobile Ads SDK اطلاع می‌دهد که نمایشی در آگهی رخ داده است.
didEndVideo	به Google Mobile Ads SDK اطلاع می دهد که پخش آگهی پاداش داده شده به پایان رسیده است.
didRewardUserWithReward	به Google Mobile Ads SDK اطلاع می دهد که کاربر پاداشی را به دست آورده است.
گزارش کلیک کنید	به Google Mobile Ads SDK اطلاع می دهد که روی تبلیغ کلیک شده است.
willDismissFullScreenView	به Google Mobile Ads SDK اطلاع می دهد که آگهی رد می شود.
didDismissFullScreenView	به Google Mobile Ads SDK اطلاع می دهد که تبلیغ رد شده است.