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

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

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

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

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

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

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

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

يمكنك مواصلة استطلاع حالة ضبط جميع المحوّلات على مستوى جلسة التطبيق عن طريق الاتصال بـ GADMobileAds.initializationStatus.

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

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

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

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

أمثلة على GitHub

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

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