react-native-google-mobile-ads 4.1.0

package/src/types/BannerAdProps.ts

@@ -0,0 +1,73 @@
+import { BannerAdSize } from '../BannerAdSize';
+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 type 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;
+
+  /**
+   * The request options for this banner.
+   */
+  requestOptions?: RequestOptions;
+
+  /**
+   * When an ad has finished loading.
+   */
+  onAdLoaded?: () => 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 the user is about to return to the app after tapping on an ad.
+   */
+  onAdClosed?: () => void;
+};

package/src/types/GoogleMobileAdsNativeModule.ts

@@ -0,0 +1,15 @@
+import { AdapterStatus } from './AdapterStatus';
+import { RequestConfiguration } from './RequestConfiguration';
+import { RequestOptions } from './RequestOptions';
+import { AdShowOptions } from './AdShowOptions';
+
+export interface GoogleMobileAdsNativeModule {
+  initialize(): Promise<AdapterStatus[]>;
+  setRequestConfiguration(requestConfiguration?: RequestConfiguration): Promise<void>;
+  appOpenLoad(requestId: number, adUnitId: string, requestOptions: RequestOptions): void;
+  appOpenShow(requestId: number, showOptions?: AdShowOptions): Promise<void>;
+  interstitialLoad(requestId: number, adUnitId: string, requestOptions: RequestOptions): void;
+  interstitialShow(requestId: number, showOptions?: AdShowOptions): Promise<void>;
+  rewardedLoad(requestId: number, adUnitId: string, requestOptions: RequestOptions): void;
+  rewardedShow(requestId: number, adUnitId: string, showOptions?: AdShowOptions): Promise<void>;
+}

package/src/types/MobileAd.interface.ts

@@ -0,0 +1,69 @@
+import { AdEventListener } from './AdEventListener';
+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;
+
+  /**
+   * 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.onAdEvent((type) => {
+   *
+   * });
+   *
+   * // Sometime later...
+   * unsubscribe();
+   * ```
+   *
+   * @param listener A listener callback containing a event type, error and data.
+   */
+  onAdEvent(listener: AdEventListener): () => void;
+
+  /**
+   * Show the loaded advert to the user.
+   *
+   * #### Example
+   *
+   * ```js
+   * // Create InterstitialAd/RewardedAd
+   * const advert = InterstitialAd.createForAdRequest('...');
+   *
+   * advert.onAdEvent((type) => {
+   *   if (type === AdEventType.LOADED) {
+   *     advert.show({
+   *       immersiveModeEnabled: true,
+   *     });
+   *   }
+   * });
+   * ```
+   *
+   * @param showOptions An optional `AdShowOptions` interface.
+   */
+  show(showOptions?: AdShowOptions): Promise<void>;
+}

package/src/types/MobileAdsModule.interface.ts

@@ -0,0 +1,43 @@
+import { EventEmitter } from 'react-native';
+
+import { AdapterStatus } from './AdapterStatus';
+import { GoogleMobileAdsNativeModule } from './GoogleMobileAdsNativeModule';
+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>;
+
+  /**
+   * The native module instance for the Google Mobile Ads service.
+   */
+  native: GoogleMobileAdsNativeModule;
+
+  /**
+   * Returns the shared event emitter instance used for all JS event routing.
+   */
+  emitter: EventEmitter;
+}

package/src/types/Module.interface.ts

@@ -0,0 +1,16 @@
+export interface App {
+  name: string;
+}
+
+export interface Config {
+  version: string;
+  namespace: string;
+  nativeModuleName: string[];
+  nativeEvents: string[];
+}
+
+export interface ModuleInterface {
+  app: App;
+  _config: Config;
+  _customUrlOrRegion?: string;
+}

package/src/types/RequestConfiguration.ts

@@ -0,0 +1,40 @@
+import { MaxAdContentRating } from '../MaxAdContentRating';
+
+/**
+ * The `RequestConfiguration` used when setting global ad settings via `setRequestConfiguration`.
+ */
+export interface RequestConfiguration {
+  /**
+   * The maximum ad content rating for all ads.  Google Mobile Ads returns ads at or below the specified level.
+   *
+   * Ratings are based on the [digital content label classifications](https://support.google.com/admob/answer/7562142).
+   */
+  maxAdContentRating?: MaxAdContentRating;
+
+  /**
+   * If `true`, indicates that you want your content treated as child-directed for purposes of COPPA.
+   *
+   * For purposes of the [Children's Online Privacy Protection Act (COPPA)](http://business.ftc.gov/privacy-and-security/children%27s-privacy),
+   * there is a setting called "tag for child-directed treatment". By setting this tag, you certify that this notification
+   * is accurate and you are authorized to act on behalf of the owner of the app. You understand that abuse of this
+   * setting may result in termination of your Google account.
+   */
+  tagForChildDirectedTreatment?: boolean;
+
+  /**
+   * If `true`, indicates that you want the ad request to be handled in a manner suitable for users under the age of consent.
+   *
+   * You can mark your ad requests to receive treatment for users in the European Economic Area (EEA) under the age of consent.
+   * This feature is designed to help facilitate compliance with the [General Data Protection Regulation (GDPR)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32016R0679).
+   *
+   * See the [Google Mobile SDK docs](https://developers.google.com/admob/android/targeting#ad_content_filtering) for more information.
+   */
+  tagForUnderAgeOfConsent?: boolean;
+
+  /**
+   * An array of test device IDs to add to the allowlist.
+   *
+   * If using an emulator, set the device ID to `EMULATOR`.
+   */
+  testDeviceIdentifiers?: string[];
+}

package/src/types/RequestOptions.ts

@@ -0,0 +1,113 @@
+export interface ServerSideVerificationOptions {
+  /**
+   * User identifier.
+   * If no user identifier is provided by the app, this query parameter will not be present in the SSV callback.
+   */
+  userId?: string;
+
+  /**
+   * Custom data string.
+   * If no custom data string is provided by the app, this query parameter value will not be present in the SSV callback.
+   */
+  customData?: string;
+}
+
+/**
+ * The `RequestOptions` interface. Used when passing additional request options before an advert is loaded.
+ */
+export interface RequestOptions {
+  /**
+   * If `true` only non-personalized ads will be loaded.
+   *
+   * Google serves personalized ads by default. This option must be `true` if users who are within the EEA have only
+   * given consent to non-personalized ads.
+   */
+  requestNonPersonalizedAdsOnly?: boolean;
+
+  /**
+   * Attaches additional properties to an ad request for direct campaign delivery.
+   *
+   * Takes an array of string key/value pairs.
+   *
+   * #### Example
+   *
+   * Attaches `?campaign=abc&user=123` to the ad request:
+   *
+   * ```js
+   * await Interstitial.createForAdRequest('ca-app-pub-3940256099942544/1033173712', {
+   *   networkExtras: {
+   *     campaign: 'abc',
+   *     user: '123',
+   *   },
+   * });
+   */
+  networkExtras?: { [key: string]: string };
+
+  /**
+   * An array of keywords to be sent when loading the ad.
+   *
+   * Setting keywords helps deliver more specific ads to a user based on the keywords.
+   *
+   * #### Example
+   *
+   * ```js
+   * await Interstitial.createForAdRequest('ca-app-pub-3940256099942544/1033173712', {
+   *   keywords: ['fashion', 'clothing'],
+   * });
+   * ```
+   */
+  keywords?: string[];
+
+  /**
+   * Sets a content URL for targeting purposes.
+   *
+   * Max length of 512.
+   */
+  contentUrl?: string;
+
+  /**
+   * The latitude and longitude location of the user.
+   *
+   * Ensure your app requests location permissions from the user.
+   *
+   * #### Example
+   *
+   * ```js
+   * await Interstitial.createForAdRequest('ca-app-pub-3940256099942544/1033173712', {
+   *   location: [53.481073, -2.237074],
+   * });
+   * ```
+   */
+  location?: [number, number];
+
+  /**
+   * Sets the location accuracy if the location is set, in meters.
+   *
+   * This option is only applied to iOS devices. On Android, this option has no effect.
+   *
+   * @ios
+   */
+  locationAccuracy?: number;
+
+  /**
+   * Sets the request agent string to identify the ad request's origin. Third party libraries that reference the Mobile
+   * Ads SDK should call this method to denote the platform from which the ad request originated. For example, if a
+   * third party ad network called "CoolAds network" mediates requests to the Mobile Ads SDK, it should call this
+   * method with "CoolAds".
+   *
+   * #### Example
+   *
+   * ```js
+   * await Interstitial.createForAdRequest('ca-app-pub-3940256099942544/1033173712', {
+   *   requestAgent: 'CoolAds',
+   * });
+   * ```
+   */
+  requestAgent?: string;
+
+  /**
+   * Server Side Verification(SSV) Options
+   * See [Google Mobile SDK Docs](https://developers.google.com/admob/android/ssv) for more information.
+   */
+  serverSideVerificationOptions?: ServerSideVerificationOptions;
+}

package/src/types/RewardedAdReward.ts

@@ -0,0 +1,14 @@
+/**
+ * A `RewardedAdReward` returned from rewarded ads.
+ */
+export interface RewardedAdReward {
+  /**
+   * The reward name, e.g. 'coins', 'diamonds'.
+   */
+  type: string;
+
+  /**
+   * The number value of the reward, e.g. 10
+   */
+  amount: number;
+}

package/src/validateAdRequestConfiguration.ts

@@ -0,0 +1,71 @@
+/*
+ * 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 { hasOwnProperty, isArray, isBoolean, isObject } from './common';
+import { MaxAdContentRating } from './MaxAdContentRating';
+import { RequestConfiguration } from './types/RequestConfiguration';
+
+export function validateAdRequestConfiguration(requestConfiguration: RequestConfiguration) {
+  const out: RequestConfiguration = {};
+
+  if (!isObject(requestConfiguration)) {
+    throw new Error("'requestConfiguration' expected an object value");
+  }
+
+  if (requestConfiguration.maxAdContentRating) {
+    if (
+      requestConfiguration.maxAdContentRating !== MaxAdContentRating.G &&
+      requestConfiguration.maxAdContentRating !== MaxAdContentRating.PG &&
+      requestConfiguration.maxAdContentRating !== MaxAdContentRating.T &&
+      requestConfiguration.maxAdContentRating !== MaxAdContentRating.MA
+    ) {
+      throw new Error(
+        "'requestConfiguration.maxAdContentRating' expected on of MaxAdContentRating.G, MaxAdContentRating.PG, MaxAdContentRating.T or MaxAdContentRating.MA",
+      );
+    }
+
+    out.maxAdContentRating = requestConfiguration.maxAdContentRating;
+  }
+
+  if (hasOwnProperty(requestConfiguration, 'tagForChildDirectedTreatment')) {
+    if (!isBoolean(requestConfiguration.tagForChildDirectedTreatment)) {
+      throw new Error(
+        "'requestConfiguration.tagForChildDirectedTreatment' expected a boolean value",
+      );
+    }
+
+    out.tagForChildDirectedTreatment = requestConfiguration.tagForChildDirectedTreatment;
+  }
+
+  if (hasOwnProperty(requestConfiguration, 'tagForUnderAgeOfConsent')) {
+    if (!isBoolean(requestConfiguration.tagForUnderAgeOfConsent)) {
+      throw new Error("'requestConfiguration.tagForUnderAgeOfConsent' expected a boolean value");
+    }
+
+    out.tagForUnderAgeOfConsent = requestConfiguration.tagForUnderAgeOfConsent;
+  }
+
+  if (hasOwnProperty(requestConfiguration, 'testDeviceIdentifiers')) {
+    if (!isArray(requestConfiguration.testDeviceIdentifiers)) {
+      throw new Error("'requestConfiguration.testDeviceIdentifiers' expected an array value");
+    }
+
+    out.testDeviceIdentifiers = requestConfiguration.testDeviceIdentifiers;
+  }
+
+  return out;
+}

package/src/validateAdRequestOptions.ts

@@ -0,0 +1,168 @@
+/*
+ * 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 {
+  hasOwnProperty,
+  isArray,
+  isBoolean,
+  isNumber,
+  isObject,
+  isString,
+  isUndefined,
+  isValidUrl,
+} from './common';
+import { RequestOptions } from './types/RequestOptions';
+
+export function validateAdRequestOptions(options?: RequestOptions) {
+  const out: RequestOptions = {};
+
+  if (isUndefined(options)) {
+    return out;
+  }
+
+  if (!isObject(options)) {
+    throw new Error("'options' expected an object value");
+  }
+
+  if (hasOwnProperty(options, 'requestNonPersonalizedAdsOnly')) {
+    if (!isBoolean(options.requestNonPersonalizedAdsOnly)) {
+      throw new Error("'options.requestNonPersonalizedAdsOnly' expected a boolean value");
+    }
+
+    out.requestNonPersonalizedAdsOnly = options.requestNonPersonalizedAdsOnly;
+  }
+
+  if (options.networkExtras) {
+    if (!isObject(options.networkExtras)) {
+      throw new Error("'options.networkExtras' expected an object of key/value pairs");
+    }
+
+    Object.entries(options.networkExtras).forEach(([key, value]) => {
+      if (!isString(value)) {
+        throw new Error(`'options.networkExtras' expected a string value for object key "${key}"`);
+      }
+    });
+
+    out.networkExtras = options.networkExtras;
+  }
+
+  if (options.keywords) {
+    if (!isArray(options.keywords)) {
+      throw new Error("'options.keywords' expected an array containing string values");
+    }
+
+    for (let i = 0; i < options.keywords.length; i++) {
+      const keyword = options.keywords[i];
+
+      if (!isString(keyword)) {
+        throw new Error("'options.keywords' expected an array containing string values");
+      }
+    }
+
+    out.keywords = options.keywords;
+  }
+
+  if (options.contentUrl) {
+    if (!isString(options.contentUrl)) {
+      throw new Error("'options.contentUrl' expected a string value");
+    }
+
+    if (!isValidUrl(options.contentUrl)) {
+      throw new Error("'options.contentUrl' expected a valid HTTP or HTTPS url.");
+    }
+
+    if (options.contentUrl.length > 512) {
+      throw new Error("'options.contentUrl' maximum length of a content URL is 512 characters.");
+    }
+
+    out.contentUrl = options.contentUrl;
+  }
+
+  if (options.location) {
+    const error = new Error(
+      "'options.location' expected an array value containing a latitude & longitude number value.",
+    );
+
+    if (!isArray(options.location)) {
+      throw error;
+    }
+
+    const [latitude, longitude] = options.location;
+
+    if (!isNumber(latitude) || !isNumber(longitude)) {
+      throw error;
+    }
+
+    if (latitude < -90 || latitude > 90) {
+      throw new Error(
+        `'options.location' latitude value must be a number between -90 and 90, but was: ${latitude}`,
+      );
+    }
+
+    if (longitude < -180 || longitude > 180) {
+      throw new Error(
+        `'options.location' longitude value must be a number between -180 and 180, but was: ${latitude}`,
+      );
+    }
+
+    out.location = [latitude, longitude];
+  }
+
+  if (hasOwnProperty(options, 'locationAccuracy')) {
+    if (!isNumber(options.locationAccuracy)) {
+      throw new Error("'options.locationAccuracy' expected a number value.");
+    }
+
+    if (isNumber(options.locationAccuracy) && options.locationAccuracy < 0) {
+      throw new Error("'options.locationAccuracy' expected a number greater than 0.");
+    }
+
+    out.locationAccuracy = options.locationAccuracy;
+  } else {
+    out.locationAccuracy = 5;
+  }
+
+  if (options.requestAgent) {
+    if (!isString(options.requestAgent)) {
+      throw new Error("'options.requestAgent' expected a string value");
+    }
+
+    out.requestAgent = options.requestAgent;
+  }
+
+  if (options.serverSideVerificationOptions) {
+    if (!isObject(options.serverSideVerificationOptions)) {
+      throw new Error(
+        "'options.serverSideVerificationOptions' expected an object of key/value pairs",
+      );
+    }
+
+    const ssvOptions = options.serverSideVerificationOptions;
+
+    if (ssvOptions.userId && !isString(ssvOptions.userId)) {
+      throw new Error("'options.serverSideVerificationOptions.userId' expected a string value");
+    }
+
+    if (ssvOptions.customData && !isString(ssvOptions.customData)) {
+      throw new Error("'options.serverSideVerificationOptions.customData' expected a string value");
+    }
+
+    out.serverSideVerificationOptions = options.serverSideVerificationOptions;
+  }
+
+  return out;
+}

package/src/validateAdShowOptions.ts

@@ -0,0 +1,41 @@
+/*
+ * 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 { hasOwnProperty, isBoolean, isObject, isUndefined } from './common';
+import { AdShowOptions } from './types/AdShowOptions';
+
+export function validateAdShowOptions(options?: AdShowOptions) {
+  const out: AdShowOptions = {};
+
+  if (isUndefined(options)) {
+    return out;
+  }
+
+  if (!isObject(options)) {
+    throw new Error("'options' expected an object value");
+  }
+
+  if (hasOwnProperty(options, 'immersiveModeEnabled')) {
+    if (!isBoolean(options.immersiveModeEnabled)) {
+      throw new Error("'options.immersiveModeEnabled' expected a boolean value");
+    }
+
+    out.immersiveModeEnabled = options.immersiveModeEnabled;
+  }
+
+  return out;
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+// generated by genversion
+export const version = '4.1.0';