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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الإعلانات بمكافأة هي إعلانات يمكن للمستخدمين التفاعل معها مقابل الحصول على مكافآت داخل التطبيق. يوضّح لك هذا الدليل كيفية دمج الإعلانات بمكافأة من 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() {
    let request = GADRequest()
    GADRewardedAd.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error = error {
        print("Failed to load rewarded ad with error: \(error.localizedDescription)")
        return
      }
      rewardedAd = ad
      print("Rewarded ad loaded.")
    }
    )
  }
}

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

GADRewardedInterstitialAd.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedInterstitialAd = ad
      let options = GADServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedInterstitialAd.serverSideVerificationOptions = options
    }

Objective-C

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

التسجيل من أجل معاودة الاتصال

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

Swift

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    let request = GADRequest()
    GADRewarded.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                     request: request,
                     completionHandler: { [self] ad, error in
      if let error = error {
        print("Failed to load rewarded ad with error: \(error.localizedDescription)")
        return
      }
      rewardedAd = ad
      print("Rewarded ad loaded.")
      rewardedAd?.fullScreenContentDelegate = self
    }
    )
  }

  /// 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() {
  if let ad = rewardedAd {
    ad.present(fromRootViewController: self) {
      let reward = ad.adReward
      print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
      // TODO: Reward the user.
    }
  } else {
    print("Ad wasn't ready")
  }
}

Objective-C

- (void)show {
  ...
  if (self.rewardedAd) {
    [self.rewardedAd presentFromRootViewController:self
                                  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 سبب عدم جهوزية المحوّل لتلبية طلبات الإعلان.

أمثلة على GitHub

  • مثال على الإعلانات بمكافأة: Swift | Purpose-C