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

اختيار النظام الأساسي: Android iOS Unity Flutter Android (قديم)

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

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

قبل المتابعة، عليك إعداد Google Mobile Ads SDK.

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

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

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

ca-app-pub-3940256099942544/1712485313

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

لمزيد من المعلومات حول طريقة عمل الإعلانات الاختبارية في Google Mobile Ads SDK، يُرجى الاطّلاع على الإعلانات الاختبارية.

التنفيذ

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

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

تحميل إعلان

يتم تحميل الإعلان باستخدام طريقة load(adUnitID:request) في فئة GADRewardedAd.

Swift

func loadRewardedAd() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "ca-app-pub-3940256099942544/1712485313", request: Request())
    rewardedAd?.fullScreenContentDelegate = self
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}
ViewController.swift

SwiftUI

import GoogleMobileAds

class RewardedViewModel: NSObject, ObservableObject, FullScreenContentDelegate {
  @Published var coins = 0
  private var rewardedAd: RewardedAd?

  func loadAd() async {
    do {
      rewardedAd = try await RewardedAd.load(
        with: "ca-app-pub-3940256099942544/1712485313", request: Request())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }
RewardedViewModel.swift

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
              request:[GADRequest request]
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
        return;
      }
      self.rewardedAd = ad;
      self.rewardedAd.fullScreenContentDelegate = self;
    }];
ViewController.m

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

[اختياري] التحقّق من صحة عمليات معاودة الاتصال في ميزة "التحقّق من جهة الخادم" (SSV)

يجب أن تستخدم التطبيقات التي تتطلّب بيانات إضافية في عمليات معاودة الاتصال من أجل التحقّق من جهة الخادم ميزة البيانات المخصّصة في "الإعلانات مقابل مكافأة". يتم تمرير أي قيمة سلسلة تم ضبطها على عنصر "إعلان مقابل مكافأة" إلى مَعلمة طلب البحث custom_data لطلب معاودة الاتصال من خلال ميزة SSV. في حال عدم ضبط قيمة بيانات مخصّصة، لن تظهر قيمة مَعلمة طلب البحث custom_data في طلب معاودة الاتصال للتحقّق من صحة الخادم.

توضّح عيّنة التعليمات البرمجية التالية كيفية ضبط بيانات مخصّصة في عنصر "إعلان مقابل مكافأة" قبل طلب إعلان:

Swift

private func validateServerSideVerification() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "ca-app-pub-3940256099942544/1712485313", request: Request())
    let options = ServerSideVerificationOptions()
    options.customRewardText = "SAMPLE_CUSTOM_DATA_STRING"
    rewardedAd?.serverSideVerificationOptions = options
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}
RewardedAdSnippets.swift

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                        request:[GADRequest request]
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  NSLog(@"Rewarded ad failed to load with error: %@", error.localizedDescription);
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];
RewardedAdSnippets.m

استبدِل SAMPLE_CUSTOM_DATA_STRING ببياناتك المخصّصة.

نقطة أساسية: يتم ترميز سلسلة المكافأة المخصّصة بالنسبة المئوية وقد يتطلّب الأمر فك ترميزها عند تحليلها من معاودة الاتصال من جهة الخادم.

التسجيل لتلقّي عمليات معاودة الاتصال

لتلقّي إشعارات بشأن أحداث العرض، عليك ضبط السمة fullScreenContentDelegate للإعلان الذي تم عرضه على GADFullScreenContentDelegate:

Swift

rewardedAd?.fullScreenContentDelegate = self
ViewController.swift

SwiftUI

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

Objective-C

self.rewardedAd.fullScreenContentDelegate = self;
ViewController.m

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

Swift

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
  // Clear the rewarded ad.
  rewardedAd = nil
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called with error: \(error.localizedDescription).")
}
ViewController.swift

SwiftUI

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded ad.
  rewardedAd = nil
}
RewardedViewModel.swift

Objective-C

- (void)adDidRecordImpression:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidRecordClick:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillPresentFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
  // Clear the rewarded ad.
  self.rewardedAd = nil;
}

- (void)ad:(id)ad didFailToPresentFullScreenContentWithError:(NSError *)error {
  NSLog(@"%s called with error: %@", __PRETTY_FUNCTION__, error.localizedDescription);
}
ViewController.m

عرض الإعلان والتعامل مع حدث مقابل مكافأة

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

عند عرض إعلانك، يجب تقديم عنصر GADUserDidEarnRewardHandler للتعامل مع مكافأة المستخدم.

يعرض الرمز التالي أفضل طريقة لعرض "إعلان مقابل مكافأة":

Swift

rewardedAd.present(from: self) {
  let reward = rewardedAd.adReward
  print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")

  // TODO: Reward the user.
}
ViewController.swift

SwiftUI

استمِع إلى أحداث واجهة المستخدم في العرض لتحديد وقت عرض الإعلان.

var body: some View {
  VStack(spacing: 20) {
      Button("Watch video for additional 10 coins") {
        viewModel.showAd()
        showWatchVideoButton = false
      }
RewardedContentView.swift

اعرض "الإعلان مقابل مكافأة" من نموذج العرض:

func showAd() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  rewardedAd.present(from: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedViewModel.swift

Objective-C

[self.rewardedAd presentFromRootViewController:self
                      userDidEarnRewardHandler:^{
                        GADAdReward *reward = self.rewardedAd.adReward;
                        NSString *rewardMessage = [NSString
                            stringWithFormat:@"Reward received with currency %@ , amount %lf",
                                             reward.type, [reward.amount doubleValue]];
                        NSLog(@"%@", rewardMessage);

                        // TODO: Reward the user.
                      }];
ViewController.m

الأسئلة الشائعة

هل يمكنني الحصول على تفاصيل المكافأة لـ "GADRewardedAd"؟

نعم، إذا كنت بحاجة إلى قيمة المكافأة قبل بدء استدعاء userDidEarnReward، يحتوي GADRewardedAd على سمة adReward يمكنك الاطّلاع عليها للتحقّق من قيمة المكافأة بعد تحميل الإعلان.

هل هناك مهلة لطلب الإعداد؟

بعد 10 ثوانٍ، يستدعي Google Mobile Ads SDK GADInitializationCompletionHandler المقدَّم إلى طريقة startWithCompletionHandler:، حتى إذا لم تكن شبكة التوسّط قد أكملت عملية الإعداد.

ماذا يحدث إذا لم تكن بعض شبكات التوسّط جاهزة عند تلقّي طلب معاودة الاتصال للإعداد؟

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

يمكنك مواصلة استطلاع حالة الإعداد لجميع المحوّلات طوال جلسة تطبيقك من خلال استدعاء GADMobileAds.initializationStatus.

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

توضّح السمة description لعنصر GADAdapterStatus سبب عدم استعداد المحوّل لعرض طلبات عرض الإعلانات.

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

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

أمثلة على GitHub

يمكنك الاطّلاع على الأمثلة الكاملة لـ "الإعلانات مقابل مكافأة" بلغتك المفضّلة:

• Swift
• SwiftUI
• Objective-C

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

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