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

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

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

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

التنفيذ

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

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

تحميل إعلان

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

[اختياري] التحقّق من صحة عمليات رد الاتصال الخاصة بعملية التحقّق من جهة الخادم

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

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

Swift

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

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

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

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

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

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

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

تصف السمة description الخاصة بالكائن GADAdapterStatus سبب عدم استعداد إحدى وحدات الربط لتلبية طلبات الإعلانات.

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

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

أمثلة على GitHub

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

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

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