From a6aa286a791e04be3e0b015438d162dbe798eaf5 Mon Sep 17 00:00:00 2001 From: Jay Date: Sat, 27 Nov 2021 02:50:52 +0900 Subject: [PATCH] docs: update app open ad docs --- docs/docs/api/hooks/useAppOpenAd.mdx | 10 ++++--- docs/docs/api/hooks/useFullScreenAd.mdx | 6 ++-- docs/docs/usage/appopen.mdx | 38 ++++++++++++++++++++++--- 3 files changed, 43 insertions(+), 11 deletions(-) diff --git a/docs/docs/api/hooks/useAppOpenAd.mdx b/docs/docs/api/hooks/useAppOpenAd.mdx index a022152..a358d4c 100644 --- a/docs/docs/api/hooks/useAppOpenAd.mdx +++ b/docs/docs/api/hooks/useAppOpenAd.mdx @@ -11,16 +11,18 @@ Properties: | Name | Type | Description | | :------------- | :------- | :-------------------------------------------------------------------------------------------- | | adLoaded | boolean | Whether your ad is loaded and ready to present. | -| adPresented | boolean | Whether your ad is presented to user. Value is remained `true` until new ad is **loaded**. | -| adDismissed | boolean | Whether your ad is dismissed. Value is remained `true` until new ad is **presented**. | +| adPresented | boolean | Whether your ad is presented to user. The value remains `true` until **new ad is requested**. | +| adDismissed | boolean | Whether your ad is dismissed. The value remains `true` until new ad is requested. | | adShowing | boolean | Whether your ad is showing. The value is equal with `adPresented && !adDismissed`. | | adLoadError | Error | Error during ad load. | | adPresentError | Error | Error during ad present. | -| load | Function | Loads new ad. Can not call this function if the ad is loaded but not presented and dismissed. | +| load | Function | Loads new ad. | | show | Function | Shows loaded ad. Ad must be loaded prior to this call. | :::tip -Note that `adPresented` value remains `true` after the ad is dismissed. The value changes to `false` when ad is initialized via `load()`. Also, `adDismissed` value remains `true` until new ad is presented even if after a new ad is loaded. To determine whether the ad is showing, use `adShowing` value. +Note that `adPresented` value remains `true` after the ad is dismissed. +The value changes to `false` when ad is initialized via `load()`. +To determine whether the ad is showing, use `adShowing` value. ::: diff --git a/docs/docs/api/hooks/useFullScreenAd.mdx b/docs/docs/api/hooks/useFullScreenAd.mdx index ea7f752..d3b1198 100644 --- a/docs/docs/api/hooks/useFullScreenAd.mdx +++ b/docs/docs/api/hooks/useFullScreenAd.mdx @@ -39,13 +39,13 @@ Properties: | Name | Type | Description | | :------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------- | | adLoaded | boolean | Whether your ad is loaded and ready to present. | -| adPresented | boolean | Whether your ad is presented to user. Value is remained `true` until **new ad is requested**. | -| adDismissed | boolean | Whether your ad is dismissed. Value is remained `true` until new ad is requested. | +| adPresented | boolean | Whether your ad is presented to user. The value remains `true` until **new ad is requested**. | +| adDismissed | boolean | Whether your ad is dismissed. The value remains `true` until new ad is requested. | | adShowing | boolean | Whether your ad is showing. The value is equal with `adPresented && !adDismissed`. | | adLoadError | Error \| undefined | `Error` object throwed during ad load. | | adPresentError | Error \| undefined | `Error` object throwed during ad present. | | reward | [Reward](#) \| undefined | Reward earned by user. The value is `undefined` until user earns reward. Available only in RewardedAd or RewardedInterstitialAd. | -| load | Function | Loads new ad. Can not call this function if the ad is loaded but not presented and dismissed. | +| load | Function | Loads new ad. | | show | Function | Shows loaded ad. Ad must be loaded prior to this call. | :::tip diff --git a/docs/docs/usage/appopen.mdx b/docs/docs/usage/appopen.mdx index c2289b0..aa9da50 100644 --- a/docs/docs/usage/appopen.mdx +++ b/docs/docs/usage/appopen.mdx @@ -4,13 +4,43 @@ sidebar_position: 5 --- App Open Ad is slightly different from other Full Screen Ads. + +## Creating App Open Ad + +### Hook API + +Simplest way to add App Open Ad to your app is wrapping your app components with `AppOpenAdProvider` and using `useAppOpenAd` hook. + +When you wrap your app components with `AppOpenAdProvider` it automatically creates `AppOpenAd` instance and start to provide App Open Ad to your app. + +### Class API + +If you are not going to use `useAppOpenAd` hook, you don't need to wrap your app with `AppOpenAdProvider`. But, you need to create ad instance using `AppOpenAd.create` method. While other Full Screen Ads can be created multiple times and each ads have their own instance, only one AppOpenAd instance can be exist in a app. +If you create App Open Ad using `AppOpenAd.createAd()` static method more than once, +previous ad instance will be destroyed and newly created ad instance will replace it. + +You don't need to keep reference to `AppOpenAd` instance because it is managed to be singleton and you can access the ad via static methods. + +## Loading App Open Ad + +Library automatically loads ad when it is created or dismissed. + +Also, ad is automatically loaded when app comes to foreground from background, but has no ad loaded. + +## Showing App Open Ad + +Ad is automatically shown when app comes to foreground and has loaded ad previously. + +### Cold starts and loading screens + +"Cold starts" occur when your app is launched but was not previously suspended in memory. + +An example of a cold start is when a user opens your app for the first time. With cold starts, you won't have a previously loaded app open ad that's ready to be shown right away. The delay between when you request an ad and receive an ad back can create a situation where users are able to briefly use your app before being surprised by an out of context ad. This should be avoided because it is a bad user experience. -So, `AppOpenAd` class have static `sharedInstance` internally and when you create App Open Ad using `AppOpenAd.createAd()` method, -it will replace existing `sharedInstance` and app will always have signle `AppOpenAd` instance. +The preferred way to use app open ads on cold starts is to use a loading screen to load your game or app assets, and to only show the ad from the loading screen. If your app has completed loading and has sent the user to the main content of your app, do not show the ad. -Also, you have to wrap your app components with [AppOpenAdProvider](/docs/api/components/AppOpenAdProvider) to use `useAppOpenAd` hook. -`AppOpenAdProvider` is needed beacuse it provides sigleton `AppOpenAd` instance to hooks. +## Usage Example Example below uses external library [react-native-bootsplash](https://github.com/zoontek/react-native-bootsplash) to implement splash screen. This is not necessary, but we recommend you to use this library with App Open Ad because App Open Ad must be showed before the app content showed.