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

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

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

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

التنفيذ

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

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

تحميل إعلان

يتم تحميل الإعلان باستخدام طريقة loadWithAdUnitID:request:completionHandler: الثابتة في الفئة GADRewardedAd. تتطلب طريقة التحميل رقم تعريف وحدتك الإعلانية وعنصر GADRequest ومعالِج الإكمال الذي يتم استدعاءه عند نجاح تحميل الإعلان أو تعذُّر تحميله. يتم توفير الكائن GADRewardedAd الذي تم تحميله كمَعلمة في معالج الإكمال. يوضّح المثال التالي كيفية تحميل GADRewardedAd في صف ViewController.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    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)")
    }
  }
}

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() {
    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.")
  }
}

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

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

  • مثال على الإعلانات التي تضم مكافأة: Swift | Objective-C

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

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