-
-
Notifications
You must be signed in to change notification settings - Fork 153
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
13 changed files
with
516 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| # Hooks | ||
|
|
||
| The AdMob package provides hooks to help you to display ads in a functional component with tiny code. The supported ad formats are full-screen ads: App open, Interstitial & Rewarded. | ||
|
|
||
| ## Load an ad | ||
|
|
||
| You can create a new ad by adding a corresponding ad type's hook to your component. | ||
|
|
||
| The first argument of the hook is the "Ad Unit ID". | ||
| For testing, we can use a Test ID, however for production the ID from the | ||
| Google AdMob dashboard under "Ad units" should be used: | ||
|
|
||
| ```tsx {4-8} | ||
| import { useInterstitialAd, TestIds } from 'react-native-google-mobile-ads'; | ||
|
|
||
| export default function App() { | ||
| const interstitialAd = useInterstitialAd(TestIds.Interstitial, { | ||
| requestNonPersonalizedAdsOnly: true, | ||
| }); | ||
|
|
||
| return <View>{/* ... */}</View>; | ||
| } | ||
| ``` | ||
|
|
||
| > The `adUnitid` parameter can also be used to manage creation and destruction of an ad instance. | ||
| > If `adUnitid` is set or changed, new ad instance will be created and previous ad instance will be destroyed if exists. | ||
| > If `adUnitid` is set to `null`, no ad instance will be created and previous ad instance will be destroyed if exists. | ||
| The second argument is an additional optional request options object to be sent whilst loading an advert, such as keywords & location. | ||
| Setting additional request options helps AdMob choose better tailored ads from the network. View the [`RequestOptions`](/reference/admob/requestoptions) | ||
| documentation to view the full range of options available. | ||
|
|
||
| ## Show the ad | ||
|
|
||
| The hook returns several states and functions to control ad. | ||
|
|
||
| ```tsx | ||
| import { useInterstitialAd, TestIds } from 'react-native-google-mobile-ads'; | ||
|
|
||
| export default function App({ navigation }) { | ||
| const { isLoaded, isClosed, load, show } = useInterstitialAd(TestIds.Interstitial, { | ||
| requestNonPersonalizedAdsOnly: true, | ||
| }); | ||
|
|
||
| useEffect(() => { | ||
| // Start loading the interstitial straight away | ||
| load(); | ||
| }, [load]); | ||
|
|
||
| useEffect(() => { | ||
| if (isClosed) { | ||
| // Action after the ad is closed | ||
| navigation.navigate('NextScreen'); | ||
| } | ||
| }, [isClosed, navigation]); | ||
|
|
||
| return ( | ||
| <View> | ||
| <Button | ||
| title="Navigate to next screen" | ||
| onPress={() => { | ||
| if (isLoaded) { | ||
| show(); | ||
| } else { | ||
| // No advert ready to show yet | ||
| navigation.navigate('NextScreen'); | ||
| } | ||
| }} | ||
| /> | ||
| </View> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| The code above immediately starts to load a new advert from the network (via `load()`). | ||
| When user presses button, it checks if the ad is loaded via `isLoaded` value, | ||
| then the `show` function is called and the advert is shown over-the-top of your application. | ||
| Otherwise, if the ad is not loaded, the `navigation.navigate` method is called to navigate to the next screen without showing the ad. | ||
| After the ad is closed, the `isClosed` value is set to `true` and the `navigation.navigate` method is called to navigate to the next screen. | ||
|
|
||
| If needed, you can reuse the existing hook to load more adverts and show them when required. The states are initialized when the `load` function is called. | ||
|
|
||
| Return values of the hook are: | ||
|
|
||
| | Name | Type | Description | | ||
| | :------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------- | | ||
| | isLoaded | boolean | Whether the ad is loaded and ready to to be shown to the user. | | ||
| | isOpened | boolean | Whether the ad is opened. The value is remained `true` even after the ad is closed unless **new ad is requested**. | | ||
| | isClosed | boolean | Whether your ad is dismissed. | | ||
| | isShowing | boolean | Whether your ad is showing. The value is equal with `isOpened && !isClosed`. | | ||
| | error | Error \| undefined | `Error` object throwed during ad load. | | ||
| | reward | [RewardedAdReward](#) \| undefined | Loaded reward item of the Rewarded Ad. Available only in RewardedAd. | | ||
| | isEarnedReward | boolean | Whether the user earned the reward by Rewarded Ad. | | ||
| | load | Function | Start loading the advert with the provided RequestOptions. | | ||
| | show | Function | Show the loaded advert to the user. | | ||
|
|
||
| > Note that `isOpened` value remains `true` even after the ad is closed. | ||
| > The value changes to `false` when ad is initialized via calling `load()`. | ||
| > To determine whether the ad is currently showing, use `isShowing` value. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -141,5 +141,8 @@ | |
| }, | ||
| "publishConfig": { | ||
| "access": "public" | ||
| }, | ||
| "dependencies": { | ||
| "use-deep-compare-effect": "^1.8.1" | ||
| } | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| /* | ||
| * Copyright (c) 2016-present Invertase Limited & Contributors | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this library except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| * | ||
| */ | ||
|
|
||
| import { useState } from 'react'; | ||
| import useDeepCompareEffect from 'use-deep-compare-effect'; | ||
|
|
||
| import { AppOpenAd } from '../ads/AppOpenAd'; | ||
| import { AdHookReturns } from '../types/AdStates'; | ||
| import { RequestOptions } from '../types/RequestOptions'; | ||
|
|
||
| import { useFullScreenAd } from './useFullScreenAd'; | ||
|
|
||
| /** | ||
| * React Hook for App Open Ad. | ||
| * | ||
| * @param adUnitId The Ad Unit ID for the App Open Ad. You can find this on your Google Mobile Ads dashboard. You can destroy ad instance by setting this value to null. | ||
| * @param requestOptions Optional RequestOptions used to load the ad. | ||
| */ | ||
| export function useAppOpenAd( | ||
| adUnitId: string | null, | ||
| requestOptions: RequestOptions = {}, | ||
| ): Omit<AdHookReturns, 'adReward'> { | ||
| const [appOpenAd, setAppOpenAd] = useState<AppOpenAd | null>(null); | ||
|
|
||
| useDeepCompareEffect(() => { | ||
| setAppOpenAd(() => { | ||
| return adUnitId ? AppOpenAd.createForAdRequest(adUnitId, requestOptions) : null; | ||
| }); | ||
| }, [adUnitId, requestOptions]); | ||
|
|
||
| return useFullScreenAd(appOpenAd); | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| /* | ||
| * Copyright (c) 2016-present Invertase Limited & Contributors | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this library except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| * | ||
| */ | ||
|
|
||
| import { Reducer, useCallback, useEffect, useReducer } from 'react'; | ||
|
|
||
| import { AdEventType } from '../AdEventType'; | ||
| import { AppOpenAd } from '../ads/AppOpenAd'; | ||
| import { InterstitialAd } from '../ads/InterstitialAd'; | ||
| import { RewardedAd } from '../ads/RewardedAd'; | ||
| import { RewardedAdEventType } from '../RewardedAdEventType'; | ||
| import { AdStates, AdHookReturns } from '../types/AdStates'; | ||
| import { AdShowOptions } from '../types/AdShowOptions'; | ||
|
|
||
| const initialState: AdStates = { | ||
| isLoaded: false, | ||
| isOpened: false, | ||
| isClicked: false, | ||
| isClosed: false, | ||
| error: undefined, | ||
| reward: undefined, | ||
| isEarnedReward: false, | ||
| }; | ||
|
|
||
| export function useFullScreenAd<T extends InterstitialAd | RewardedAd | AppOpenAd | null>( | ||
| ad: T, | ||
| ): AdHookReturns { | ||
| const [state, setState] = useReducer<Reducer<AdStates, Partial<AdStates>>>( | ||
| (prevState, newState) => ({ ...prevState, ...newState }), | ||
| initialState, | ||
| ); | ||
| const isShowing = state.isOpened && !state.isClosed; | ||
|
|
||
| const load = useCallback(() => { | ||
| if (ad) { | ||
| setState(initialState); | ||
| ad.load(); | ||
| } | ||
| }, [ad]); | ||
|
|
||
| const show = useCallback( | ||
| (showOptions?: AdShowOptions) => { | ||
| if (ad) { | ||
| ad.show(showOptions); | ||
| } | ||
| }, | ||
| [ad], | ||
| ); | ||
|
|
||
| useEffect(() => { | ||
| setState(initialState); | ||
| if (!ad) { | ||
| return; | ||
| } | ||
| const unsubscribe = ad.onAdEvent((type, error, data) => { | ||
| switch (type) { | ||
| case AdEventType.LOADED: | ||
| setState({ isLoaded: true }); | ||
| break; | ||
| case AdEventType.OPENED: | ||
| setState({ isOpened: true }); | ||
| break; | ||
| case AdEventType.CLOSED: | ||
| setState({ isClosed: true }); | ||
| break; | ||
| case AdEventType.CLICKED: | ||
| setState({ isClicked: true }); | ||
| break; | ||
| case AdEventType.ERROR: | ||
| setState({ error: error }); | ||
| break; | ||
| case RewardedAdEventType.LOADED: | ||
| setState({ isLoaded: true, reward: data }); | ||
| break; | ||
| case RewardedAdEventType.EARNED_REWARD: | ||
| setState({ isEarnedReward: true, reward: data }); | ||
| break; | ||
| } | ||
| }); | ||
| return () => { | ||
| unsubscribe(); | ||
| }; | ||
| }, [ad]); | ||
|
|
||
| return { | ||
| ...state, | ||
| isShowing, | ||
| load, | ||
| show, | ||
| }; | ||
| } |
Oops, something went wrong.