الإعلان البيني بمكافأة (إصدار تجريبي)

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

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

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

التنفيذ

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

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

تحميل إعلان

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

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedInterstitialAd: GADRewardedInterstitialAd?

  override func viewDidLoad() {
    super.viewDidLoad()

    Task {
      do {
        rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
          withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
      } catch {
        print("Failed to load rewarded interstitial ad with error: \(error.localizedDescription)")
      }
    }
  }
}

SwiftUI

import GoogleMobileAds

class RewardedInterstitialViewModel: NSObject, ObservableObject,
  GADFullScreenContentDelegate
{
  @Published var coins = 0
  private var rewardedInterstitialAd: GADRewardedInterstitialAd?

  func loadAd() async {
    do {
      rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
      rewardedInterstitialAd?.fullScreenContentDelegate = self
    } catch {
      print(
        "Failed to load rewarded interstitial ad with error: \(error.localizedDescription)")
    }
  }
RewardedInterstitialViewModel.swift

Objective-C

#import "ViewController.h"

@interface ViewController ()
@property(nonatomic, strong) GADRewardedInterstitialAd* rewardedInterstitialAd;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  [GADRewardedInterstitialAd
      loadWithAdUnitID:@"<var label='the ad unit ID'>ca-app-pub-3940256099942544/6978759866</var>"
                request:[GADRequest request]
      completionHandler:^(
          GADRewardedInterstitialAd* _Nullable rewardedInterstitialAd,
          NSError* _Nullable error) {
        if (!error) {
          self.rewardedInterstitialAd = rewardedInterstitialAd;
        }
      }
  ];
}

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

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

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

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

Swift

do {
  rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
    withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedInterstitialAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedInterstitialAd
    loadWithAdUnitID:@"ca-app-pub-3940256099942544/6978759866"
              request:GADRequest
    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;
    }];

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

التسجيل لتلقّي مكالمات من فريق الدعم

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

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedInterstitialAd: GADRewardedInterstitialAd?

  override func viewDidLoad() {
    super.viewDidLoad()

    Task {
      do {
        rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
          withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
        self.rewardedInterstitialAd?.fullScreenContentDelegate = self
      } catch {
        print("Failed to load rewarded interstitial ad 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.")
  }
}

SwiftUI

خصِّص السمة fullScreenContentDelegate للإعلان الذي تم عرضه:

rewardedInterstitialAd?.fullScreenContentDelegate = self
RewardedInterstitialViewModel.swift

تنفيذ البروتوكول:

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

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

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

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

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

func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded interstitial ad.
  rewardedInterstitialAd = nil
}
RewardedInterstitialViewModel.swift

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>
@property(nonatomic, strong) GADRewardedInterstitialAd *rewardedInterstitialAd;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  // Do any additional setup after loading the view.

  [GADRewardedInterstitialAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/6978759866"
                request:[GADRequest request]
      completionHandler:^(
          GADRewardedInterstitialAd *_Nullable rewardedInterstitialAd,
          NSError *_Nullable error) {
        if (!error) {
          self.rewardedInterstitialAd = rewardedInterstitialAd;
          self.rewardedInterstitialAd.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.");
}

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

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

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

يوضّح الرمز التالي أفضل طريقة لعرض الإعلان البيني الذي يضم مكافأة.

Swift

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

  // The UIViewController parameter is an optional.
  rewardedInterstitialAd.present(fromRootViewController: nil) {
    let reward = rewardedInterstitialAd.adReward
    print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

SwiftUI

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

var rewardedInterstitialBody: some View {
  // ...
  }
  .onChange(
    of: showAd,
    perform: { newValue in
      if newValue {
        viewModel.showAd()
      }
    }
  )
RewardedInterstitialContentView.swift

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

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

  rewardedInterstitialAd.present(fromRootViewController: nil) {
    let reward = rewardedInterstitialAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedInterstitialViewModel.swift

Objective-C

- (void)show {
  // The UIViewController parameter is nullable.
  [_rewardedInterstitialAd presentFromRootViewController:nil
                                userDidEarnRewardHandler:^{

                                  GADAdReward *reward =
                                      self.rewardedInterstitialAd.adReward;
                                  // TODO: Reward the user.
                                }];
}

أمثلة على GitHub

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

• Swift
• SwiftUI
• Objective-C

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

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