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

الإعلانات التي تضم مكافأة هي إعلانات يتوفّر للمستخدمين خيار التفاعل معها في مقابل للحصول على مكافآت داخل التطبيق هذا الدليل كيفية دمج الإعلانات التي تضم مكافأة من "مدير إعلانات Google" في تطبيق iOS.

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

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

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

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

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

/6499/example/rewarded

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

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

التنفيذ

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

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

تحميل إعلان

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

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
    } 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 {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/6499/example/rewarded"
                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: "/6499/example/rewarded", request: GAMRequest())
  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:@"/6499/example/rewarded"
              request:[GAMRequest 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: "/6499/example/rewarded", request: GAMRequest())
      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 {
  GAMRequest *request = [GAMRequest 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

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

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