الإعلانات بمكافأة

الإعلانات التي تضم مكافأة هي إعلانات يتوفّر للمستخدمين خيار التفاعل معها في مقابل للحصول على مكافآت داخل التطبيق هذا الدليل كيفية دمج الإعلانات التي تضم مكافأة من AdMob في تطبيق iOS. الاطّلاع على بعض قصص نجاح العملاء: دراسة الحالة 1، دراسة الحالة 2.

المتطلبات الأساسية

  • الإصدار 8.0.0 أو إصدار أحدث من حزمة "SDK لإعلانات Google على الأجهزة الجوّالة".
  • أكمِل دليل البدء.

الاختبار دائمًا باستخدام الإعلانات الاختبارية

عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات تجريبية بدلاً من إعلانات بث مباشر وقد يؤدي عدم الالتزام بذلك إلى تعليق حسابك.

أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام رقم التعريف المخصّص للوحدة الإعلانية الاختبارية لنظام التشغيل iOS. الإعلانات التي تضم مكافأة:

ca-app-pub-3940256099942544/1712485313

لقد تم إعدادها خصيصًا لعرض إعلانات اختبارية لكل طلب، يمكن استخدامها مجانًا في تطبيقاتك الخاصة أثناء الترميز والاختبار وتصحيح الأخطاء. ما عليك سوى إجراء واحرص على استبداله بمعرّف وحدتك الإعلانية قبل نشر تطبيقك.

لمزيد من المعلومات عن آلية عمل الإعلانات الاختبارية لحزمة تطوير البرامج (SDK) لعرض الإعلانات للأجهزة الجوّالة، راجع اختبار الإعلانات:

التنفيذ

في ما يلي الخطوات الأساسية لدمج الإعلانات التي تضم مكافأة:

  • تحميل إعلان
  • [اختياري] التحقُّق من عمليات معاودة الاتصال باستخدام ميزة "التحقُّق بخطوتين"
  • التسجيل لتلقّي مكالمات من فريق الدعم
  • عرض الإعلان والتعامل مع حدث المكافأة

تحميل إعلان

يتم الانتهاء من تحميل الإعلان باستخدام load(adUnitID:request) في الفئة GADRewardedAd.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

SwiftUI

import GoogleMobileAds

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

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

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GADRequest *request = [GADRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
      }];
}

[اختياري] التحقق من صحة عمليات استدعاء التحقّق من جهة الخادم (SSV)

التطبيقات التي تتطلب بيانات إضافية في خادم التحقق، يجب أن تستخدم استدعاءات الخاصة بالإعلانات التي تضم مكافأة. أي قيمة سلسلة تمّ تحديدها على إعلان يضم مكافأة يتم تمرير الكائن إلى معلَمة طلب البحث custom_data لمعاودة اتصال SSV. إذا كانت الإجابة "لا" البيانات المخصّصة، ولن يتم تغيير قيمة معلَمة طلب البحث custom_data الموجودة في معاودة اتصال SSV.

يوضح نموذج الرمز البرمجي التالي كيفية ضبط البيانات المخصّصة في إعلان يضم مكافأة. قبل طلب إعلان.

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedAd
     loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
              request:[GADRequest request];
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

التسجيل لتلقّي طلبات معاودة الاتصال

لتلقي إشعارات لأحداث العرض التقديمي، يجب تنفيذ بروتوكول GADFullScreenContentDelegate وتعيينه إلى السمة fullScreenContentDelegate للإعلان الذي تم عرضه. تشير رسالة الأشكال البيانية يتعامل بروتوكول GADFullScreenContentDelegate مع عمليات معاودة الاتصال عند ظهور الإعلان نجاحه أو عدم نجاحه وعندما يتم رفضه. ما يلي: طريقة تنفيذ البروتوكول وتعيينه للإعلان:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }

  /// Tells the delegate that the ad failed to present full screen content.
  func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
    print("Ad did fail to present full screen content.")
  }

  /// Tells the delegate that the ad will present full screen content.
  func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad will present full screen content.")
  }

  /// Tells the delegate that the ad dismissed full screen content.
  func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad did dismiss full screen content.")
  }
}

SwiftUI

تحديد السمة fullScreenContentDelegate للإعلان المعروض:

rewardedAd?.fullScreenContentDelegate = self

تنفيذ البروتوكول:

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

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

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

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

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

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

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GADRequest *request = [GADRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
        self.rewardedAd.fullScreenContentDelegate = self;
      }];
}

/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
    didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
    NSLog(@"Ad did fail to present full screen content.");
}

/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad will present full screen content.");
}

/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad did dismiss full screen content.");
}

GADRewardedAd هو عنصر يُستخدم لمرة واحدة. وهذا يعني أنه بعد عرض الإعلان الذي يضم مكافأة كما هو موضح، لا يمكن عرضه مرة أخرى. ومن أفضل الممارسات تحميل إعلان آخر يضم مكافأة. في طريقة adDidDismissFullScreenContent: على GADFullScreenContentDelegate لكي يبدأ تحميل الإعلان التالي الذي يضم مكافأة بمجرد تحميل الإعلان السابق رفضت.

عرض الإعلان والتعامل مع حدث المكافأة

قبل عرض إعلان يضم مكافأة للمستخدمين، يجب منح المستخدم خيارًا واضحًا لعرض محتوى الإعلان الذي يضم مكافأة مقابل مكافأة. مكافأة أن تتضمّن الإعلانات دائمًا تجربة تتطلّب موافقة المستخدمين.

عند عرض إعلانك، يجب تقديم كائن GADUserDidEarnRewardHandler. لمعالجة المكافأة للمستخدم.

يوضّح الرمز التالي أفضل طريقة لعرض الإعلان الذي يضم مكافأة.

Swift

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

  // The UIViewController parameter is an optional.
  ad.present(fromRootViewController: nil) {
    let reward = ad.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(fromRootViewController: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}

Objective-C

- (void)show {
  if (self.rewardedAd) {
    // The UIViewController parameter is nullable.
    [self.rewardedAd presentFromRootViewController:nil
                                  userDidEarnRewardHandler:^{
                                  GADAdReward *reward =
                                      self.rewardedAd.adReward;
                                  // TODO: Reward the user!
                                }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

الأسئلة الشائعة

هل يمكنني الحصول على تفاصيل المكافأة الخاصة بـ "GADRewardedAd
نعم، إذا كنت بحاجة إلى مبلغ المكافأة قبل معاودة الاتصال على userDidEarnReward تم تنشيطها، يمتلك GADRewardedAd adReward الموقع الذي يمكنك التحقّق منه للتحقّق من قيمة المكافأة بعد تحميل الإعلان.
هل هناك مهلة لطلب الإعداد؟
بعد 10 ثوانٍ، تستدعي "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" تمّ توفير GADInitializationCompletionHandler إلى startWithCompletionHandler:، حتى إذا لم يتم إجراء ذلك من خلال شبكة توسّط حتى الآن اكتملت عملية الإعداد.
ماذا لو لم تكن بعض شبكات التوسّط جاهزة عند تلقّي طلب إعادة الاتصال لبدء عملية الإعداد؟

نقترح تحميل إعلان داخل GADInitializationCompletionHandler وحتى إذا لم تكن شبكة التوسّط جاهزة إلا أن حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" لا تزال تطلب من تلك الشبكة عرض إعلان. لذلك إذا كانت تنتهي عملية إعداد شبكة التوسط بعد انتهاء المهلة، فيمكن أن يبقى بإمكانها لطلبات الإعلان المستقبلية في تلك الجلسة.

يمكنك مواصلة التحقق من حالة الإعداد لجميع المحوّلات. جلسة التطبيق من خلال الاتصال بالرقم GADMobileAds.initializationStatus.

كيف يمكنني معرفة سبب عدم جهوزية شبكة توسّط معيَّنة؟

توضِّح سمة description لعنصر GADAdapterStatus سبب عدم جاهزية المحوِّل لعرض طلبات الإعلانات.

هل يتم دائمًا استدعاء معالج إكمال userDidEarnRewardHandler قبل طريقة التفويض adDidDismissFullScreenContent:؟

بالنسبة إلى "إعلانات Google"، تتم جميع المكالمات البالغ عددها userDidEarnRewardHandler. قبل adDidDismissFullScreenContent:. بالنسبة إلى الإعلانات التي يتم عرضها من خلال التوسّط، وشبكة المواقع الإعلانية التابعة لجهة خارجية يتم تحديد طلب معاودة الاتصال من خلال تنفيذ حزمة تطوير البرامج (SDK). بالنسبة إلى حِزم SDK لشبكات الإعلانات التي توفّر طريقة واحدة مفوَّضة تتضمّن معلومات المكافأة، يشغِّل محوِّل التوسّط userDidEarnRewardHandler قبل adDidDismissFullScreenContent:.

أمثلة على GitHub

يمكنك عرض الأمثلة الكاملة للإعلانات التي تضم مكافأة بلغتك المفضّلة:

الخطوات التالية

مزيد من المعلومات حول خصوصية المستخدم