@javascriptcommon/react-native-google-mobile-ads 16.3.3

package/src/specs/modules/NativeRewardedModule.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 { TurboModule, TurboModuleRegistry } from 'react-native';
+import { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+
+export interface Spec extends TurboModule {
+  rewardedLoad(requestId: number, adUnitId: string, requestOptions: UnsafeObject): void;
+  rewardedShow(requestId: number, adUnitId: string, showOptions?: UnsafeObject): Promise<void>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('RNGoogleMobileAdsRewardedModule');

package/src/types/AdEventListener.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 { AdEventType } from '../AdEventType';
+import { GAMAdEventType } from '../GAMAdEventType';
+import { RewardedAdEventType } from '../RewardedAdEventType';
+import { AppEvent } from './AppEvent';
+import { RewardedAdReward } from './RewardedAdReward';
+
+export type AdEventPayload<T extends AdEventType | RewardedAdEventType | GAMAdEventType = never> =
+  T extends AdEventType.ERROR
+    ? Error
+    : T extends RewardedAdEventType
+      ? RewardedAdReward
+      : T extends GAMAdEventType
+        ? AppEvent
+        : undefined;
+
+export type AdEventListener<T extends AdEventType | RewardedAdEventType | GAMAdEventType = never> =
+  (payload: AdEventPayload<T>) => void;

package/src/types/AdEventsListener.ts

@@ -0,0 +1,24 @@
+/*
+ * 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 { AdEventType } from '../AdEventType';
+import { GAMAdEventType } from '../GAMAdEventType';
+import { RewardedAdEventType } from '../RewardedAdEventType';
+import { AdEventPayload } from './AdEventListener';
+
+export type AdEventsListener<T extends AdEventType | RewardedAdEventType | GAMAdEventType = never> =
+  (eventInfo: { type: T; payload: AdEventPayload<T> }) => void;

package/src/types/AdShowOptions.ts

@@ -0,0 +1,12 @@
+/**
+ * A `AdShowOptions` interface used when showing an ad.
+ */
+export interface AdShowOptions {
+  /**
+   * - On Android, enables [immersive mode](https://developer.android.com/training/system-ui/immersive).
+   * - On iOS, this has no effect on how the ad is shown.
+   *
+   * @android
+   */
+  immersiveModeEnabled?: boolean;
+}

package/src/types/AdStates.ts

@@ -0,0 +1,92 @@
+import { AdShowOptions } from './AdShowOptions';
+import type { PaidEvent } from './PaidEventListener';
+import { RewardedAdReward } from './RewardedAdReward';
+
+export interface AdStates {
+  /**
+   * Whether the ad is loaded and ready to to be shown to the user.
+   */
+  isLoaded: boolean;
+  /**
+   * Whether the ad is opened.
+   */
+  isOpened: boolean;
+  /**
+   * Whether the user clicked the advert.
+   */
+  isClicked: boolean;
+  /**
+   * Whether the user closed the ad and has returned back to your application.
+   */
+  isClosed: boolean;
+  /**
+   * JavaScript Error containing the error code and message thrown by the Ad.
+   */
+  error?: Error;
+  /**
+   * Payload from the last impression-level ad revenue event.
+   */
+  revenue?: PaidEvent;
+  /**
+   * Loaded reward item of the Rewarded Ad.
+   */
+  reward?: RewardedAdReward;
+  /**
+   * Whether the user earned the reward by Rewarded Ad.
+   */
+  isEarnedReward?: boolean;
+}
+
+export interface AdHookReturns extends AdStates {
+  /**
+   * Whether your ad is showing.
+   * The value is equal with `isOpened && !isClosed`.
+   */
+  isShowing: boolean;
+  /**
+   * Start loading the advert with the provided RequestOptions.
+   * #### Example
+   *
+   * ```jsx
+   * export default function App() {
+   *   const interstitial = useInterstitialAd(TestIds.INTERSTITIAL, {
+   *     requestNonPersonalizedAdsOnly: true,
+   *   });
+   *   useEffect(() => {
+   *     interstitial.load();
+   *   }, [interstitial.load]);
+   * }
+   * ```
+   */
+  load: () => void;
+  /**
+   * Show the loaded advert to the user.
+   *
+   * #### Example
+   *
+   * ```jsx
+   * export default function App() {
+   *   const interstitial = useInterstitialAd(TestIds.INTERSTITIAL, {
+   *     requestNonPersonalizedAdsOnly: true,
+   *   });
+   *   return (
+   *     <View>
+   *       <Button
+   *         title="Navigate to next screen"
+   *         onPress={() => {
+   *           if (interstitial.isLoaded) {
+   *             interstitial.show();
+   *           } else {
+   *             navigation.navigate('NextScreen');
+   *           }
+   *         }}
+   *       />
+   *     </View>
+   *   )
+   * }
+   * ```
+   *
+   * @param showOptions An optional `AdShowOptions` interface.
+   */
+  show: (showOptions?: AdShowOptions) => void;
+}

package/src/types/AdapterStatus.ts

@@ -0,0 +1,20 @@
+export enum InitializationState {
+  /**
+   * The mediation adapter is less likely to fill ad requests.
+   */
+  AdapterInitializationStateNotReady = 0,
+
+  /**
+   * The mediation adapter is ready to service ad requests.
+   */
+  AdapterInitializationStateReady = 1,
+}
+
+/**
+ * An immutable snapshot of a mediation adapter's initialization status.
+ */
+export type AdapterStatus = {
+  name: string;
+  description: string;
+  state: InitializationState;
+};

package/src/types/AppEvent.ts

@@ -0,0 +1,14 @@
+/**
+ * An app event received from Google Ad Manager ads.
+ */
+export interface AppEvent {
+  /**
+   * The event name.
+   */
+  name: string;
+
+  /**
+   * The data received with the app event.
+   */
+  data?: string;
+}

package/src/types/BannerAdProps.ts

@@ -0,0 +1,184 @@
+import { BannerAdSize, GAMBannerAdSize } from '../BannerAdSize';
+import { AppEvent } from './AppEvent';
+import type { PaidEventListener } from './PaidEventListener';
+import { RequestOptions } from './RequestOptions';
+
+/**
+ * An interface for a Banner advert component.
+ *
+ * #### Example
+ *
+ * The `BannerAd` interface is exposed as a React component, allowing you to integrate ads within your existing React
+ * Native code base. The component itself is isolated, meaning any standard `View` props (e.g. `style`) are not
+ * forwarded on. It is recommended you wrap the `BannerAd` within your own `View` if you wish to apply custom props for use-cases
+ * such as positioning.
+ *
+ * ```js
+ * import { BannerAd, BannerAdSize, TestIds } from 'react-native-google-mobile-ads';
+ *
+ * function HomeScreen() {
+ *   return (
+ *     <BannerAd
+ *       unitId={TestIds.BANNER}
+ *       size={BannerAdSize.FULL_BANNER}
+ *       requestOptions={{
+ *         requestNonPersonalizedAdsOnly: true,
+ *       }}
+ *       onAdLoaded={() => {
+ *         console.log('Advert loaded');
+ *       }}
+ *       onAdFailedToLoad={(error) => {
+ *         console.error('Advert failed to load: ', error);
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export interface BannerAdProps {
+  /**
+   * The Google Mobile Ads unit ID for the banner.
+   */
+  unitId: string;
+
+  /**
+   * The size of the banner. Can be a predefined size via `BannerAdSize` or custom dimensions, e.g. `300x200`.
+   *
+   * Inventory must be available for the banner size specified, otherwise a no-fill error will be sent to `onAdFailedToLoad`.
+   */
+  size: BannerAdSize | string;
+
+  /**
+   * Limit inline adaptive banner height.
+   * By default, inline adaptive banners instantiated without a maxHeight value have a maxHeight equal to the device height.
+   */
+  maxHeight?: number;
+
+  /**
+   * Sets the width for adaptive banners (inline and anchored).
+   * If not specified, the width defaults to the full device width.
+   */
+  width?: number;
+
+  /**
+   * The request options for this banner.
+   */
+  requestOptions?: RequestOptions;
+
+  /**
+   * When an ad has finished loading.
+   */
+  onAdLoaded?: (dimensions: { width: number; height: number }) => void;
+
+  /**
+   * When an ad has failed to load. Callback contains an Error.
+   */
+  onAdFailedToLoad?: (error: Error) => void;
+
+  /**
+   * The ad is now visible to the user.
+   */
+  onAdOpened?: () => void;
+
+  /**
+   * Called when an impression is recorded for an ad.
+   */
+  onAdImpression?: () => void;
+
+  /**
+   * Called when a click is recorded for an ad
+   */
+  onAdClicked?: () => void;
+
+  /**
+   * Called when the user is about to return to the app after tapping on an ad.
+   */
+  onAdClosed?: () => void;
+
+  /**
+   * Called when ad generates revenue.
+   * See: https://developers.google.com/admob/android/impression-level-ad-revenue
+   */
+  onPaid?: PaidEventListener;
+
+  /**
+   * Called when ad size dimensions changed
+   */
+  onSizeChange?: (dimensions: { width: number; height: number }) => void;
+}
+
+/**
+ * An interface for a GAM Banner advert component.
+ *
+ * #### Example
+ *
+ * The `GAMBannerAd` interface is exposed as a React component, allowing you to integrate ads within your existing React
+ * Native code base. The component itself is isolated, meaning any standard `View` props (e.g. `style`) are not
+ * forwarded on. It is recommended you wrap the `GAMBannerAd` within your own `View` if you wish to apply custom props for use-cases
+ * such as positioning.
+ *
+ * ```js
+ * import { GAMBannerAd, BannerAdSize, TestIds } from 'react-native-google-mobile-ads';
+ *
+ * function HomeScreen() {
+ *   return (
+ *     <GAMBannerAd
+ *       unitId={TestIds.GAM_BANNER}
+ *       sizes={[BannerAdSize.FULL_BANNER]}
+ *       requestOptions={{
+ *         requestNonPersonalizedAdsOnly: true,
+ *       }}
+ *       onAdLoaded={() => {
+ *         console.log('Advert loaded');
+ *       }}
+ *       onAdFailedToLoad={(error) => {
+ *         console.error('Advert failed to load: ', error);
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export interface GAMBannerAdProps extends Omit<BannerAdProps, 'size'> {
+  /**
+   * The available sizes of the banner. Can be a array of predefined sizes via `BannerAdSize` or custom dimensions, e.g. `300x200`.
+   *
+   * Inventory must be available for the banner sizes specified, otherwise a no-fill error will be sent to `onAdFailedToLoad`.
+   */
+  sizes: (typeof GAMBannerAdSize)[keyof typeof GAMBannerAdSize][] | string[];
+
+  /**
+   * Whether to enable the manual impression counting.
+   *
+   * #### Example
+   *
+   * After setting this value to `true`, call `recordManualImpression()` from the ref object.
+   *
+   * ```js
+   * import { GAMBannerAd, BannerAdSize, TestIds } from 'react-native-google-mobile-ads';
+   *
+   * function HomeScreen() {
+   *   const ref = useRef<GAMBannerAd>(null);
+   *
+   *   const recordManualImpression = () => {
+   *     ref.current?.recordManualImpression();
+   *   }
+   *
+   *   return (
+   *     <GAMBannerAd
+   *       ref={ref}
+   *       unitId={TestIds.GAM_BANNER}
+   *       sizes={[BannerAdSize.FULL_BANNER]}
+   *       manualImpressionsEnabled={true}
+   *     />
+   *   );
+   * }
+   * ```
+   */
+  manualImpressionsEnabled?: boolean;
+
+  /**
+   * When an ad received Ad Manager specific app events.
+   */
+  onAppEvent?: (appEvent: AppEvent) => void;
+}

package/src/types/MobileAd.interface.ts

@@ -0,0 +1,113 @@
+/*
+ * 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 { AdEventListener } from './AdEventListener';
+import { AdEventsListener } from './AdEventsListener';
+import { AdShowOptions } from './AdShowOptions';
+
+/**
+ * Base class for InterstitialAd, RewardedAd, NativeAd and BannerAd.
+ */
+export interface MobileAdInterface {
+  /**
+   * The Ad Unit ID for this Gogole Mobile Ads ad.
+   */
+  adUnitId: string;
+
+  /**
+   * Whether the advert is loaded and can be shown.
+   */
+  loaded: boolean;
+
+  /**
+   * Start loading the advert with the provided RequestOptions.
+   *
+   * It is recommended you setup ad event handlers before calling this method.
+   */
+  load(): void;
+
+  /**
+   * Show the loaded advert to the user.
+   *
+   * #### Example
+   *
+   * ```js
+   * // Create InterstitialAd/RewardedAd
+   * const advert = InterstitialAd.createForAdRequest('...');
+   *
+   * advert.addAdEventListener(AdEventType.LOADED, () => {
+   *   advert.show({
+   *     immersiveModeEnabled: true,
+   *   });
+   * });
+   * ```
+   *
+   * @param showOptions An optional `AdShowOptions` interface.
+   */
+  show(showOptions?: AdShowOptions): Promise<void>;
+
+  /**
+   * Listen to ad events. See AdEventTypes for more information.
+   *
+   * Returns an unsubscriber function to stop listening to further events.
+   *
+   * #### Example
+   *
+   * ```js
+   * // Create InterstitialAd/RewardedAd
+   * const advert = InterstitialAd.createForAdRequest('...');
+   *
+   * const unsubscribe = advert.addAdEventsListener(({ type, payload }) => {
+   * });
+   *
+   * // Sometime later...
+   * unsubscribe();
+   * ```
+   *
+   * @param listener A listener callback containing a event type, error and data.
+   */
+  addAdEventsListener<T extends never>(listener: AdEventsListener<T>): () => void;
+
+  /**
+   * Listen to ad events. See AdEventTypes for more information.
+   *
+   * Returns an unsubscriber function to stop listening to further events.
+   *
+   * #### Example
+   *
+   * ```js
+   * // Create InterstitialAd/RewardedAd
+   * const advert = InterstitialAd.createForAdRequest('...');
+   *
+   * const unsubscribe = advert.addAdEventListener(AdEventType.Loaded, () => {
+   *
+   * });
+   *
+   * // Sometime later...
+   * unsubscribe();
+   * ```
+   *
+   * @param type The event type, e.g. `AdEventType.LOADED`.
+   * @param listener A listener callback containing a event type, error and data.
+   */
+  addAdEventListener<T extends never>(type: T, listener: AdEventListener<T>): void;
+
+  /**
+   * Remove all registered event listeners.
+   */
+  removeAllListeners(): void;
+}

package/src/types/MobileAdsModule.interface.ts

@@ -0,0 +1,80 @@
+import { AdapterStatus } from './AdapterStatus';
+import { RequestConfiguration } from './RequestConfiguration';
+
+/**
+ * The Google Mobile Ads service interface.
+ */
+export interface MobileAdsModuleInterface {
+  /**
+   * Initialize the SDK.
+   */
+  initialize(): Promise<AdapterStatus[]>;
+
+  /**
+   * Sets request options for all future ad requests.
+   *
+   * #### Example
+   *
+   * ```js
+   * import mobileAds, { MaxAdContentRating } from 'react-native-google-mobile-ads';
+   *
+   * await mobileAds().setRequestConfiguration({
+   *   // Update all future requests suitable for parental guidance
+   *   maxAdContentRating: MaxAdContentRating.PG,
+   * });
+   * ```
+   *
+   * @param requestConfiguration An RequestConfiguration interface used on all future Google Mobile Ads ad requests.
+   */
+  setRequestConfiguration(requestConfiguration: RequestConfiguration): Promise<void>;
+
+  /**
+   * Opens the Ad Inspector. Ad inspector is an in-app overlay that enables authorized devices to perform real-time analysis of test ad requests directly within a mobile app.
+   *
+   * The promise will resolve when the inspector is closed.
+   * Also, the promise will reject if ad inspector is closed due to an error.
+   *
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/android/ad-inspector
+   */
+  openAdInspector(): Promise<void>;
+
+  /**
+   * Opens the Ad Debug Menu.
+   *
+   * Android: `initialize` needs to be called before calling this function.
+   *
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/android/debug
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/ios/debug
+   *
+   * @param adUnit Any valid ad unit from your Ad Manager account is sufficient to open the debug options menu.
+   */
+  openDebugMenu(adUnit: string): void;
+
+  /**
+   * Sets the application's audio volume. Affects audio volumes of all ads relative to other audio output.
+   *
+   * Warning: Lowering your app's audio volume reduces video ad eligibility and may reduce your app's ad revenue.
+   * You should only utilize this API if your app provides custom volume controls to the user, and you should reflect
+   * the user's volume choice in this API.
+   *
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/android/global-settings
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/ios/global-settings
+   *
+   * @param volume the volume as a float from 0 (muted) to 1.0 (full media volume). Defaults to 1.0
+   */
+  setAppVolume(volume: number): void;
+
+  /**
+   * Indicates whether the application's audio is muted. Affects initial mute state for all ads.
+   *
+   * Warning: Muting your application reduces video ad eligibility and may reduce your app's ad revenue.
+   * You should only utilize this API if your app provides a custom mute control to the user, and you should
+   * reflect the user's mute decision in this API.
+   *
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/android/global-settings
+   * @see https://developers.google.com/ad-manager/mobile-ads-sdk/ios/global-settings
+   *
+   * @param muted true if the app is muted, false otherwise. Defaults to false.
+   */
+  setAppMuted(muted: boolean): void;
+}

package/src/types/NativeAdRequestOptions.ts

@@ -0,0 +1,55 @@
+/*
+ * 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 { RequestOptions } from './RequestOptions';
+
+export enum NativeMediaAspectRatio {
+  ANY = 1,
+  LANDSCAPE = 2,
+  PORTRAIT = 3,
+  SQUARE = 4,
+}
+
+export enum NativeAdChoicesPlacement {
+  TOP_LEFT = 0,
+  TOP_RIGHT = 1,
+  BOTTOM_RIGHT = 2,
+  BOTTOM_LEFT = 3,
+}
+
+export interface NativeAdRequestOptions extends RequestOptions {
+  /**
+   * Specifies a preference for the aspect ratio of ad creatives.
+   * Setting this option does not guarantee that all ad creatives will meet the preference specified.
+   * - When unset, the returned ad can have any media aspect ratio.
+   * - When set, you will be able to improve the user experience by specifying the preferred type of aspect ratio.
+   */
+  aspectRatio?: NativeMediaAspectRatio;
+  /**
+   * Chooses which corner to render the AdChoices icon.
+   * - If unset, the AdChoices icon position is set to the top right.
+   * - If set, AdChoices is placed at the custom position as requested.
+   */
+  adChoicesPlacement?: NativeAdChoicesPlacement;
+  /**
+   * Disables or enables a video's starting audio.
+   * - The start muted behavior is enabled by default.
+   * - When disabled, your app requests the video should begin with audio.
+   * - When enabled, your app requests that the video should begin with audio muted.
+   */
+  startVideoMuted?: boolean;
+}

package/src/types/PaidEventListener.ts

@@ -0,0 +1,9 @@
+import { RevenuePrecisions } from '../common/constants';
+
+export type PaidEvent = {
+  currency: string;
+  precision: RevenuePrecisions;
+  value: number;
+};
+
+export type PaidEventListener = (event: PaidEvent) => void;