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

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

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

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

التنفيذ

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

  • تحميل إعلان
  • [اختياري] التحقّق من صحة استدعاءات SSV
  • التسجيل لمعاودة الاتصال
  • عرض الإعلان والتعامل مع حدث المكافأة

تحميل إعلان

يتم تحميل الإعلان باستخدام طريقة 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

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

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