آگهی‌های پاداش‌دار

پلاتفرم را انتخاب کنید: Android iOS Unity Flutter Android (Legacy)

آگهی‌های پاداش‌دار آگهی‌هایی هستند که کاربران می‌توانند در ازای دریافت پاداش‌های درون‌برنامه با آن‌ها تعامل داشته باشند. این راهنما به شما نشان می‌دهد که چگونه آگهی‌های پاداش‌دار را از AdMob در برنامه iOS ادغام کنید. چند داستان موفقیت مشتری را بخوانید: مطالعه موردی ۱، مطالعه موردی ۲.

پیش‌نیازها

پیش‌از ادامه دادن، Google Mobile Ads SDK را راه‌اندازی کنید.

همیشه با آگهی‌های آزمایشی آزمایش کنید

هنگام ساختن و آزمایش کردن برنامه‌هایتان، حتماً از آگهی‌های آزمایشی استفاده کنید نه آگهی‌های زنده و تولیدی. انجام ندادن این کار می‌تواند منجر به تعلیق حسابتان شود.

ساده‌ترین راه برای بار کردن آگهی‌های آزمایشی استفاده از شناسه واحد آگهی آزمایشی اختصاصی ما برای آگهی‌های پاداش‌دار iOS است:

ca-app-pub-3940256099942544/1712485313

این شناسه به‌طور ویژه پیکربندی شده است تا برای هر درخواست، آگهی‌های آزمایشی برگرداند و شما می‌توانید آزادانه از آن در برنامه‌های خودتان هنگام کدنویسی، آزمایش، و اشکال‌زدایی استفاده کنید. فقط مطمئن شوید که قبل‌از انتشار برنامه‌تان، آن را با شناسه واحد آگهی خودتان جایگزین کنید.

برای اطلاعات بیشتر درباره نحوه عملکرد آگهی‌های آزمایشی Google Mobile Ads SDK، به آگهی‌های آزمایشی مراجعه کنید.

پیاده‌سازی

مراحل اصلی برای ادغام آگهی‌های پاداش‌دار به شرح زیر است:

• بار کردن آگهی
• [اختیاری] اعتبارسنجی تماس‌های برگشتی SSV
• ثبت‌نام برای پاسخ تماس
• نمایش آگهی و مدیریت رویداد پاداش

بار کردن آگهی

بار کردن آگهی بااستفاده از روش load(adUnitID:request) در کلاس GADRewardedAd انجام می‌شود.

Swift

func loadRewardedAd() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "ca-app-pub-3940256099942544/1712485313", request: Request())
    rewardedAd?.fullScreenContentDelegate = self
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}
ViewController.swift

SwiftUI

import GoogleMobileAds

class RewardedViewModel: NSObject, ObservableObject, FullScreenContentDelegate {
  @Published var coins = 0
  private var rewardedAd: RewardedAd?

  func loadAd() async {
    do {
      rewardedAd = try await RewardedAd.load(
        with: "ca-app-pub-3940256099942544/1712485313", request: Request())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }
RewardedViewModel.swift

آبجکتیو-سی

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
              request:[GADRequest request]
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
        return;
      }
      self.rewardedAd = ad;
      self.rewardedAd.fullScreenContentDelegate = self;
    }];
ViewController.m

نکته: می‌توانید از فراخوانی‌های بار کردن آگهی برای ایجاد حافظه نهان آگهی‌های پیش‌بارشده قبل‌از نمایش آن‌ها استفاده کنید تا آگهی‌ها درصورت نیاز با تأخیر صفر نشان داده شوند. چون آگهی‌ها پس‌از یک ساعت منقضی می‌شوند، باید این حافظه نهان را پاک کنید و هر ساعت آگهی‌های جدید را بارگیری مجدد کنید.

[اختیاری] اعتبارسنجی تماس‌های برگشتی درستی‌سنجی سمت سرور (SSV)

برنامه‌هایی که به داده‌های اضافی در بازخوانی‌های تأیید سمت سرور نیاز دارند باید از ویژگی داده‌های سفارشی آگهی‌های پاداشی استفاده کنند. هر مقدار رشته‌ای که در شیء آگهی پاداش‌دار تنظیم شده باشد به پارامتر پُرسمان custom_data در فراخوان SSV ارسال می‌شود. اگر هیچ مقدار داده سفارشی‌ای تنظیم نشده باشد، مقدار پارامتر پُرسمان custom_data در فراخوانی SSV وجود نخواهد داشت.

نمونه کد زیر نشان می‌دهد که چگونه داده‌های سفارشی را روی یک شیء آگهی پاداش‌دار تنظیم کنید قبل‌از درخواست آگهی:

Swift

private func validateServerSideVerification() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "ca-app-pub-3940256099942544/1712485313", request: Request())
    let options = ServerSideVerificationOptions()
    options.customRewardText = "SAMPLE_CUSTOM_DATA_STRING"
    rewardedAd?.serverSideVerificationOptions = options
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}
RewardedAdSnippets.swift

آبجکتیو-سی

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                        request:[GADRequest request]
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  NSLog(@"Rewarded ad failed to load with error: %@", error.localizedDescription);
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];
RewardedAdSnippets.m

SAMPLE_CUSTOM_DATA_STRING را با داده‌های سفارشی‌تان جایگزین کنید.

نکته کلیدی: رشته پاداش سفارشی گریز درصد است و ممکن است هنگام تجزیه از فراخوانی SSV نیاز به رمزگشایی داشته باشد.

ثبت‌نام برای پاسخ تماس

برای دریافت اعلان‌های رویدادهای ارائه، باید GADFullScreenContentDelegate را به ویژگی fullScreenContentDelegate آگهی برگردانده‌شده اختصاص دهید:

Swift

rewardedAd?.fullScreenContentDelegate = self
ViewController.swift

SwiftUI

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

آبجکتیو-سی

self.rewardedAd.fullScreenContentDelegate = self;
ViewController.m

پروتکل GADFullScreenContentDelegate تماس‌های برگشتی را برای زمانی که آگهی با موفقیت یا بدون موفقیت ارائه می‌شود و زمانی که رد می‌شود، مدیریت می‌کند. کد زیر نحوه پیاده‌سازی پروتکل را نشان می‌دهد:

Swift

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
  // Clear the rewarded ad.
  rewardedAd = nil
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called with error: \(error.localizedDescription).")
}
ViewController.swift

SwiftUI

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded ad.
  rewardedAd = nil
}
RewardedViewModel.swift

آبجکتیو-سی

- (void)adDidRecordImpression:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidRecordClick:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillPresentFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
  // Clear the rewarded ad.
  self.rewardedAd = nil;
}

- (void)ad:(id)ad didFailToPresentFullScreenContentWithError:(NSError *)error {
  NSLog(@"%s called with error: %@", __PRETTY_FUNCTION__, error.localizedDescription);
}
ViewController.m

نمایش آگهی و مدیریت رویداد پاداش

قبل‌از نمایش آگهی پاداش‌دار به کاربران، باید به کاربر انتخاب صریحی برای مشاهده محتوای آگهی پاداش‌دار درازای پاداش ارائه دهید. آگهی‌های پاداش‌دار همیشه باید تجربه‌ای با موافقت کاربر باشد.

هنگام ارائه آگهی، باید شیء GADUserDidEarnRewardHandler را ارائه دهید تا پاداش کاربر را مدیریت کند.

کد زیر بهترین روش را برای نمایش آگهی پاداش‌دار ارائه می‌دهد:

Swift

rewardedAd.present(from: self) {
  let reward = rewardedAd.adReward
  print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")

  // TODO: Reward the user.
}
ViewController.swift

SwiftUI

به رویدادهای واسط کاربر در نما گوش دهید تا تعیین کنید چه زمانی آگهی نشان داده شود.

var body: some View {
  VStack(spacing: 20) {
      Button("Watch video for additional 10 coins") {
        viewModel.showAd()
        showWatchVideoButton = false
      }
RewardedContentView.swift

آگهی پاداش‌دار را از مدل نمایشی ارائه دهید:

func showAd() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  rewardedAd.present(from: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedViewModel.swift

آبجکتیو-سی

[self.rewardedAd presentFromRootViewController:self
                      userDidEarnRewardHandler:^{
                        GADAdReward *reward = self.rewardedAd.adReward;
                        NSString *rewardMessage = [NSString
                            stringWithFormat:@"Reward received with currency %@ , amount %lf",
                                             reward.type, [reward.amount doubleValue]];
                        NSLog(@"%@", rewardMessage);

                        // TODO: Reward the user.
                      }];
ViewController.m

پرسشگان

می‌توانم جزئیات پاداش GADRewardedAd را دریافت کنم؟

بله، اگر قبل‌از فعال شدن فراخوانی برگشتی userDidEarnReward به مقدار پاداش نیاز دارید، GADRewardedAd دارای ویژگی adReward است که می‌توانید آن را بررسی کنید تا مقدار پاداش را پس‌از بار شدن آگهی درستی‌سنجی کنید.

آیا برای تماس مقداردهی اولیه زمان‌بندی وجود دارد؟

پس‌از ۱۰ ثانیه، Google Mobile Ads SDK GADInitializationCompletionHandler ارائه‌شده به startWithCompletionHandler: را فراخوانی می‌کند، حتی اگر شبکه میانجی هنوز مقداردهی اولیه را تکمیل نکرده باشد.

اگر برخی‌از شبکه‌های میانجی هنگام دریافت فراخوانی برگشتی مقداردهی اولیه آماده نباشند چه می‌شود؟

توصیه می‌کنیم آگهی را در GADInitializationCompletionHandler بار کنید. حتی اگر شبکه میانجی آماده نباشد، Google Mobile Ads SDK همچنان از آن شبکه آگهی درخواست می‌کند. بنابراین اگر یک شبکه میانجی پس‌از اتمام مهلت زمانی مقداردهی اولیه را تمام کند، همچنان می‌تواند به درخواست‌های آگهی آینده در آن جلسه خدمات ارائه دهد.

می‌توانید با فراخوانی GADMobileAds.initializationStatus، وضعیت مقداردهی اولیه همه آداپتورها را درطول جلسه برنامه‌تان به‌طور مداوم بررسی کنید.

چگونه می‌توانم بفهمم چرا یک شبکه میانجی‌گری خاص آماده نیست؟

ویژگی description شیء GADAdapterStatus توضیح می‌دهد که چرا یک آداپتور برای ارائه درخواست‌های آگهی آماده نیست.

آیا گرداننده تکمیل userDidEarnRewardHandler همیشه قبل‌از روش نماینده adDidDismissFullScreenContent: فراخوانده می‌شود؟

برای آگهی‌های Google، همه تماس‌های userDidEarnRewardHandler قبل‌از adDidDismissFullScreenContent: انجام می‌شود. برای آگهی‌هایی که ازطریق میانجی‌گری ارائه می‌شوند، پیاده‌سازی کیت توسعه نرم‌افزار شبکه آگهی شخص ثالث ترتیب فراخوانی را تعیین می‌کند. برای کیت‌های توسعه نرم‌افزار شبکه آگهی که یک روش نماینده واحد با اطلاعات پاداش ارائه می‌دهند، آداپتور واسطه‌گری userDidEarnRewardHandler را قبل‌از adDidDismissFullScreenContent: فراخوانی می‌کند.

نمونه‌ها در GitHub

نمونه‌های کامل آگهی‌های پاداش‌دار را به زبان ترجیحی‌تان مشاهده کنید:

• Swift
• SwiftUI
• آبجکتیو-سی

مراحل بعدی

درباره حریم خصوصی کاربر بیشتر بدانید.