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

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

آگهی‌های پاداش‌دار آگهی‌هایی هستند که کاربران این گزینه را دارند که با آن‌ها در ازای پاداش‌های درون‌برنامه تعامل کنند. این راهنما به شما نشان می‌دهد که چگونه آگهی‌های پاداش‌دار را از Ad Manager در برنامه iOS ادغام کنید.

پیش‌نیازها

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

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

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

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

/21775744923/example/rewarded

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

برای اطلاعات بیشتر درباره نحوه عملکرد آگهی‌های آزمایشی 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: "/21775744923/example/rewarded", request: AdManagerRequest())
    rewardedAd?.fullScreenContentDelegate = self
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}

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)")
    }
  }

آبجکتیو-سی

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"/21775744923/example/rewarded"
              request:[GAMRequest 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;
    }];

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

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

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

Swift

private func validateAdManagerServerSideVerification() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "/21775744923/example/rewarded", request: AdManagerRequest())
    let options = ServerSideVerificationOptions()
    options.customRewardText = "SAMPLE_CUSTOM_DATA_STRING"
    rewardedAd?.serverSideVerificationOptions = options
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}

آبجکتیو-سی

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"/21775744923/example/rewarded"
                        request:[GAMRequest 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;
              }];

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

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

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

Swift

rewardedAd?.fullScreenContentDelegate = self

SwiftUI

rewardedAd?.fullScreenContentDelegate = self

آبجکتیو-سی

self.rewardedAd.fullScreenContentDelegate = self;

پروتکل 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).")
}

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
}

آبجکتیو-سی

- (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);
}

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

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

هنگام ارائه آگهی‌تان، باید یک شیء 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.
}

SwiftUI

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

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

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

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)
  }
}

آبجکتیو-سی

[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.
                      }];

پرسشگان

آیا می‌توانم جزئیات پاداش 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

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

مراحل بعدی

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