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

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

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

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

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

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

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

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

/21775744923/example/rewarded

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

لمزيد من المعلومات حول طريقة عمل الإعلانات الاختبارية 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: "/21775744923/example/rewarded", request: AdManagerRequest())
    rewardedAd?.fullScreenContentDelegate = self
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}

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)")
    }
  }

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"/21775744923/example/rewarded"
              request:[GAMRequest 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;
    }];

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

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

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

Swift

private func validateAdManagerServerSideVerification() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "/21775744923/example/rewarded", request: AdManagerRequest())
    let options = ServerSideVerificationOptions()
    options.customRewardText = "SAMPLE_CUSTOM_DATA_STRING"
    rewardedAd?.serverSideVerificationOptions = options
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"/21775744923/example/rewarded"
                        request:[GAMRequest 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;
              }];

يُرجى استبدال SAMPLE_CUSTOM_DATA_STRING ببياناتك المخصّصة.

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

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

Swift

rewardedAd?.fullScreenContentDelegate = self

SwiftUI

rewardedAd?.fullScreenContentDelegate = self

Objective-C

self.rewardedAd.fullScreenContentDelegate = self;

يتعامل بروتوكول 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).")
}

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
}

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);
}

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

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

عند عرض إعلانك، عليك تقديم عنصر 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.
}

SwiftUI

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

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

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

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)
  }
}

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.
                      }];

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

هل يمكنني الحصول على تفاصيل المكافأة لـ 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

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

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

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