آگهی‌های در صفحه باز شدن برنامه

انتخاب پلاتفرم: Android iOS Unity Flutter Android (قدیمی)

آگهی‌های باز کردن برنامه قالب آگهی ویژه‌ای است که برای ناشرانی درنظر گرفته شده است که می‌خواهند از صفحه‌های بار کردن برنامه خود درآمدزایی کنند. آگهی‌های باز کردن برنامه را می‌توان در هر زمانی بست و این آگهی‌ها به‌گونه‌ای طراحی شده‌اند که وقتی کاربران برنامه شما را به پیش‌زمینه می‌آورند نمایش داده شوند.

آگهی‌های باز کردن برنامه به‌طور خودکار یک ناحیه نمانام کوچک نشان می‌دهند تا کاربران بدانند در برنامه شما هستند. در اینجا نمونه‌ای از ظاهر آگهی باز کردن برنامه آورده شده است:

پیش‌نیازها

قبل‌از ادامه دادن، موارد زیر را انجام دهید:

• افزایه Flutter نسخه ۰.۱۳.۶ یا بالاتر را نصب کنید.
• ‫Google Mobile Ads Flutter Plugin را راه‌اندازی کنید. برنامه Flutter شما باید Google Mobile Ads Flutter Plugin را وارد کرده باشد.

همیشه با آگهی‌های آزمایشی آزمایش کنید

هنگام ساختن و آزمایش کردن برنامه‌هایتان، مطمئن شوید که از آگهی‌های آزمایشی به‌جای آگهی‌های زنده و تولید استفاده می‌کنید. انجام ندادن این کار می‌تواند منجر به تعلیق حساب شما شود.

آسان‌ترین راه برای بار کردن آگهی‌های آزمایشی استفاده از شناسه‌های واحد آگهی آزمایشی اختصاصی ما برای آگهی‌های پاداش‌دار Android و iOS است:

Android

ca-app-pub-3940256099942544/9257395921

iOS

ca-app-pub-3940256099942544/5575463023

این واحدها به‌طور ویژه پیکربندی شده‌اند تا برای هر درخواست، آگهی‌های آزمایشی برگردانند و شما می‌توانید درحین کدنویسی، آزمایش، و اشکال‌زدایی، آزادانه از آن‌ها در برنامه‌های خودتان استفاده کنید. فقط مطمئن شوید که قبل‌از انتشار برنامه، آن‌ها را با شناسه واحد آگهی خودتان جایگزین کنید.

پیاده‌سازی

مراحل اصلی برای ادغام آگهی‌های باز کردن برنامه عبارت‌اند از:

1. کلاس کمکی‌ای ایجاد کنید که آگهی را قبل‌از اینکه بخواهید آن را نمایش دهید بار می‌کند.
2. آگهی‌ای را بار کنید.
3. برای تماس‌های برگشتی ثبت‌نام کنید و آگهی را نشان دهید.
4. برای نمایش آگهی درطول رویدادهای پیش‌زمینه‌ای، در AppStateEventNotifier.appStateStream مشترک شوید.

ایجاد کلاس ابزار

برای بار کردن آگهی، کلاس جدیدی به‌نام AppOpenAdManager ایجاد کنید. این کلاس متغیر نمونه‌ای را مدیریت می‌کند تا آگهی بارشده و شناسه واحد آگهی را برای هر پلاتفرم پیگیری کند.

import 'package:google_mobile_ads/google_mobile_ads.dart';
import 'dart:io' show Platform;

class AppOpenAdManager {
  
  String adUnitId = Platform.isAndroid
    ? 'ca-app-pub-3940256099942544/9257395921'
    : 'ca-app-pub-3940256099942544/5575463023';
  
  AppOpenAd? _appOpenAd;
  bool _isShowingAd = false;

  /// Load an AppOpenAd.
  void loadAd() {
    // We will implement this below.
  }

  /// Whether an ad is available to be shown.
  bool get isAdAvailable {
    return _appOpenAd != null;
  }
}

بار کردن آگهی

آگهی باز برنامه شما باید قبل‌از ورود کاربران به برنامه آماده باشد. کلاس کمکی را پیاده‌سازی کنید تا درخواست‌های آگهی را قبل‌از زمانی که باید آگهی را نشان دهید انجام دهد.

بار کردن آگهی بااستفاده از روش load در کلاس AppOpenAd انجام می‌شود. روش بار کردن به شناسه واحد آگهی، حالت جهت، شیء AdRequest، و مدیریت تکمیل نیاز دارد که وقتی بار کردن آگهی موفق یا ناموفق باشد فراخوانده می‌شود. شیء بارگیری‌شده AppOpenAd به‌عنوان پارامتر در مدیریت تکمیل ارائه می‌شود. مثال زیر نحوه بار کردن AppOpenAd را نشان می‌دهد.

public class AppOpenAdManager {
  ...

  /// Load an AppOpenAd.
  void loadAd() {
    AppOpenAd.load(
      adUnitId: adUnitId,
      adRequest: AdRequest(),
      adLoadCallback: AppOpenAdLoadCallback(
        onAdLoaded: (ad) {
          _appOpenAd = ad;
        },
        onAdFailedToLoad: (error) {
          print('AppOpenAd failed to load: $error');
          // Handle the error.
        },
      ),
    );
  }
}

نمایش آگهی و مدیریت تمام‌صفحه برگشتی‌های تماس

قبل‌از نمایش آگهی، FullScreenContentCallback را برای هر رویداد آگهی که می‌خواهید به آن گوش دهید ثبت کنید.

public class AppOpenAdManager {
  ...

  public void showAdIfAvailable() {
    if (!isAdAvailable) {
      print('Tried to show ad before available.');
      loadAd();
      return;
    }
    if (_isShowingAd) {
      print('Tried to show ad while already showing an ad.');
      return;
    }
    // Set the fullScreenContentCallback and show the ad.
    _appOpenAd!.fullScreenContentCallback = FullScreenContentCallback(
      onAdShowedFullScreenContent: (ad) {
        _isShowingAd = true;
        print('$ad onAdShowedFullScreenContent');
      },
      onAdFailedToShowFullScreenContent: (ad, error) {
        print('$ad onAdFailedToShowFullScreenContent: $error');
        _isShowingAd = false;
        ad.dispose();
        _appOpenAd = null;
      },
      onAdDismissedFullScreenContent: (ad) {
        print('$ad onAdDismissedFullScreenContent');
        _isShowingAd = false;
        ad.dispose();
        _appOpenAd = null;
        loadAd();
      },
    );
  }
}

اگر کاربری پس‌از ترک کردن برنامه‌تان با کلیک کردن روی آگهی باز کردن برنامه به آن برمی‌گردد، مطمئن شوید که آگهی باز کردن برنامه دیگری به او نشان داده نشود.

گوش دادن به رویدادهای پیش‌زمینه‌ای برنامه

برای اینکه از رویدادهای پیش‌زمینه‌ای برنامه مطلع شوید، باید در AppStateEventNotifier.appStateStream مشترک شوید و به رویدادهای foreground گوش دهید.

import 'package:app_open_example/app_open_ad_manager.dart';
import 'package:google_mobile_ads/google_mobile_ads.dart';

/// Listens for app foreground events and shows app open ads.
class AppLifecycleReactor {
  final AppOpenAdManager appOpenAdManager;

  AppLifecycleReactor({required this.appOpenAdManager});

  void listenToAppStateChanges() {
    AppStateEventNotifier.startListening();
    AppStateEventNotifier.appStateStream
        .forEach((state) => _onAppStateChanged(state));
  }

  void _onAppStateChanged(AppState appState) {
    // Try to show an app open ad if the app is being resumed and
    // we're not already showing an app open ad.
    if (appState == AppState.foreground) {
      appOpenAdManager.showAdIfAvailable();
    }
  }
}

اکنون می‌توانید AppLifecycleReactor خود را مقداردهی اولیه کنید و شروع به گوش دادن به تغییرات چرخه حیات برنامه کنید. برای مثال، از صفحه اصلی:

import 'package:app_open_example/app_open_ad_manager.dart';
import 'package:flutter/material.dart';
import 'package:google_mobile_ads/google_mobile_ads.dart';

import 'app_lifecycle_reactor.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  MobileAds.instance.initialize();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'App Open Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'App Open Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

/// Example home page for an app open ad.
class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;
  late AppLifecycleReactor _appLifecycleReactor;

  @override
  void initState() {
    super.initState();
    
    AppOpenAdManager appOpenAdManager = AppOpenAdManager()..loadAd();
    _appLifecycleReactor = AppLifecycleReactor(
      appOpenAdManager: appOpenAdManager);
  }

انقضای آگهی را درنظر بگیرید

نکته کلیدی: ارجاعات آگهی در نسخه بتای باز برنامه پس‌از چهار ساعت منقضی می‌شود. آگهی‌هایی که بیش‌از چهار ساعت پس‌از زمان درخواست ارائه شوند دیگر معتبر نخواهند بود و ممکن است درآمدی کسب نکنند. این حد زمانی با دقت درنظر گرفته شده است و ممکن است در نسخه‌های بتای آینده قالب باز برنامه تغییر کند.

برای اینکه مطمئن شوید آگهی منقضی‌شده‌ای را نشان نمی‌دهید، مُهر زمان به AppOpenAdManager اضافه کنید تا بتوانید بررسی کنید که از زمان بار شدن آگهی‌تان چقدر گذشته است. سپس از آن مُهر زمان برای بررسی اینکه آیا آگهی هنوز معتبر است یا نه استفاده کنید.

/// Utility class that manages loading and showing app open ads.
class AppOpenAdManager {
  ...
  
  /// Maximum duration allowed between loading and showing the ad.
  final Duration maxCacheDuration = Duration(hours: 4);

  /// Keep track of load time so we don't show an expired ad.
  DateTime? _appOpenLoadTime;
  
  ...

  /// Load an AppOpenAd.
  void loadAd() {
    AppOpenAd.load(
      adUnitId: adUnitId,
      orientation: AppOpenAd.orientationPortrait,
      adRequest: AdRequest(),
      adLoadCallback: AppOpenAdLoadCallback(
        onAdLoaded: (ad) {
          print('$ad loaded');
          _appOpenLoadTime = DateTime.now();
          _appOpenAd = ad;
        },
        onAdFailedToLoad: (error) {
          print('AppOpenAd failed to load: $error');
        },
      ),
    );
  }

  /// Shows the ad, if one exists and is not already being shown.
  ///
  /// If the previously cached ad has expired, this just loads and caches a
  /// new ad.
  void showAdIfAvailable() {
    if (!isAdAvailable) {
      print('Tried to show ad before available.');
      loadAd();
      return;
    }
    if (_isShowingAd) {
      print('Tried to show ad while already showing an ad.');
      return;
    }
    if (DateTime.now().subtract(maxCacheDuration).isAfter(_appOpenLoadTime!)) {
      print('Maximum cache duration exceeded. Loading another ad.');
      _appOpenAd!.dispose();
      _appOpenAd = null;
      loadAd();
      return;
    }
    // Set the fullScreenContentCallback and show the ad.
    _appOpenAd!.fullScreenContentCallback = FullScreenContentCallback(...);
    _appOpenAd!.show();
  }
}

شروع سرد و صفحه‌های بار کردن

تاکنون در اسناد فرض شده است که شما فقط زمانی آگهی‌های باز کردن برنامه را نمایش می‌دهید که کاربران برنامه شما را وقتی در حافظه تعلیق شده است به پیش‌زمینه می‌آورند. «شروع‌های سرد» زمانی رخ می‌دهد که برنامه شما راه‌اندازی می‌شود اما قبلاً در حافظه تعلیق نشده است.

مثالی از راه‌اندازی سرد زمانی است که کاربر برای اولین‌بار برنامه شما را باز می‌کند. با شروع‌های سرد، آگهی باز برنامه ازقبل بارگیری‌شده‌ای نخواهید داشت که آماده نمایش فوری باشد. تأخیر بین زمانی که آگهی درخواست می‌کنید و زمانی که آگهی را دریافت می‌کنید می‌تواند وضعیتی ایجاد کند که کاربران بتوانند قبل‌از اینکه با آگهی خارج از زمینه‌ای غافلگیر شوند، به‌طور خلاصه از برنامه شما استفاده کنند. باید از این کار اجتناب شود زیرا تجربه کاربری بدی است.

روش ترجیحی برای استفاده از آگهی‌های باز کردن برنامه در شروع‌های سرد این است که از صفحه بارگیری برای بار کردن دارایی‌های بازی یا برنامه استفاده کنید و آگهی را فقط از صفحه بارگیری نشان دهید. اگر برنامه شما بارگیری را تکمیل کرده است و کاربر را به محتوای اصلی برنامه شما هدایت کرده است، آگهی را نشان ندهید.

نکته کلیدی: برای اینکه بار کردن دارایی‌های برنامه درحین نمایش آگهی باز برنامه ادامه یابد، همیشه دارایی‌ها را در رشته پس‌زمینه بار کنید.

روال‌های مطلوب

آگهی‌های باز کردن برنامه به شما کمک می‌کند از صفحه بار کردن برنامه‌تان، زمانی که برنامه برای اولین‌بار راه‌اندازی می‌شود، و درطول تعویض برنامه درآمدزایی کنید، اما مهم است که شیوه‌های مطلوب را درنظر داشته باشید تا کاربران از استفاده از برنامه‌تان لذت ببرند. بهتر است:

• آگهی باز شدن برنامه اول را پس‌از اینکه کاربران چند بار از برنامه شما استفاده کردند نشان دهید.
• آگهی‌های باز کردن برنامه را در زمان‌هایی نمایش دهید که کاربران شما درغیراین‌صورت منتظر بار شدن برنامه‌تان هستند.
• اگر در زیر آگهی باز برنامه صفحه بارگیری دارید و صفحه بارگیری شما قبل‌از بسته شدن آگهی بارگیری را تکمیل می‌کند، ممکن است بخواهید صفحه بارگیری خود را در مدیر رویداد onAdDismissedFullScreenContent ببندید.

مثال کامل در GitHub

برای مشاهده مثال کامل، به نمونه نمایشی میانای برنامه‌سازی کاربردی مراجعه کنید.