react-native-google-mobile-ads 4.1.0

package/src/internal/constants.ts

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ *
+ */
+
+export const APP_NATIVE_MODULE = 'RNFBAppModule';
+
+export const DEFAULT_APP_NAME = '[DEFAULT]';
+
+export const KNOWN_NAMESPACES = [
+  'appCheck',
+  'appDistribution',
+  'auth',
+  'analytics',
+  'remoteConfig',
+  'crashlytics',
+  'database',
+  'inAppMessaging',
+  'installations',
+  'firestore',
+  'functions',
+  'indexing',
+  'storage',
+  'dynamicLinks',
+  'messaging',
+  'naturalLanguage',
+  'ml',
+  'notifications',
+  'perf',
+  'utils',
+];

package/src/internal/index.ts

@@ -0,0 +1,21 @@
+/*
+ * 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.
+ *
+ */
+
+export { AppModule as Module } from './Module';
+export { NativeError } from './NativeError';
+export * from './registry/nativeModule';
+export { SharedEventEmitter } from './SharedEventEmitter';

package/src/internal/registry/nativeModule.ts

@@ -0,0 +1,226 @@
+/*
+ * 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 { NativeModules, Platform } from 'react-native';
+import { APP_NATIVE_MODULE } from '../constants';
+import { NativeError } from '../NativeError';
+import { GoogleMobileAdsNativeEventEmitter } from '../GoogleMobileAdsNativeEventEmitter';
+import { SharedEventEmitter } from '../SharedEventEmitter';
+import { isFunction } from '../../common';
+import { ModuleInterface } from '../../types/Module.interface';
+
+const NATIVE_MODULE_REGISTRY: Record<string, unknown> = {};
+const NATIVE_MODULE_EVENT_SUBSCRIPTIONS: Record<string, unknown> = {};
+
+function nativeModuleKey(module: ModuleInterface) {
+  return `${module._customUrlOrRegion || ''}:${module.app.name}:${module._config.namespace}`;
+}
+
+/**
+ * Wraps a native module method to provide
+ * auto prepended args and custom Error classes.
+ *
+ * @param namespace
+ * @param method
+ * @param argToPrepend
+ * @returns {Function}
+ */
+function nativeModuleMethodWrapped(
+  namespace: string,
+  method: (...args: unknown[]) => Promise<unknown> | void,
+  argToPrepend: [],
+) {
+  return (...args: []) => {
+    const possiblePromise = method(...[...argToPrepend, ...args]);
+
+    if (possiblePromise && possiblePromise.then) {
+      const jsStack = new Error().stack || '';
+      return possiblePromise.catch(nativeError =>
+        Promise.reject(new NativeError(nativeError, jsStack, namespace)),
+      );
+    }
+
+    return possiblePromise;
+  };
+}
+
+/**
+ * Prepends all arguments in prependArgs to all native method calls
+ *
+ * @param namespace
+ * @param NativeModule
+ * @param argToPrepend
+ */
+function nativeModuleWrapped(
+  namespace: string,
+  NativeModule: Record<string, (...args: unknown[]) => Promise<unknown> | void>,
+  argToPrepend: [],
+) {
+  const native: Record<string, unknown> = {};
+  if (!NativeModule) {
+    return NativeModule;
+  }
+
+  const properties = Object.keys(NativeModule);
+
+  for (let i = 0, len = properties.length; i < len; i++) {
+    const property = properties[i];
+    if (isFunction(NativeModule[property])) {
+      native[property] = nativeModuleMethodWrapped(namespace, NativeModule[property], argToPrepend);
+    } else {
+      native[property] = NativeModule[property];
+    }
+  }
+
+  return native;
+}
+
+/**
+ * Initialises and wraps all the native module methods.
+ *
+ * @param module
+ * @returns {*}
+ */
+function initialiseNativeModule(module: ModuleInterface) {
+  const config = module._config;
+  const key = nativeModuleKey(module);
+  const { namespace, nativeEvents, nativeModuleName } = config;
+  const multiModuleRoot: Record<string, unknown> = {};
+  const multiModule = Array.isArray(nativeModuleName);
+  const nativeModuleNames = multiModule ? nativeModuleName : [nativeModuleName];
+
+  for (let i = 0; i < nativeModuleNames.length; i++) {
+    const nativeModule = NativeModules[nativeModuleNames[i]];
+
+    // only error if there's a single native module
+    // as multi modules can mean some are optional
+    if (!multiModule && !nativeModule) {
+      throw new Error(getMissingModuleHelpText(namespace));
+    }
+
+    if (multiModule) {
+      multiModuleRoot[nativeModuleNames[i]] = !!nativeModule;
+    }
+
+    Object.assign(multiModuleRoot, nativeModuleWrapped(namespace, nativeModule, []));
+  }
+
+  if (nativeEvents && nativeEvents.length) {
+    for (let i = 0, len = nativeEvents.length; i < len; i++) {
+      subscribeToNativeModuleEvent(nativeEvents[i]);
+    }
+  }
+
+  Object.freeze(multiModuleRoot);
+
+  NATIVE_MODULE_REGISTRY[key] = multiModuleRoot;
+
+  return NATIVE_MODULE_REGISTRY[key];
+}
+
+/**
+ * Subscribe to a native event for js side distribution by appName
+ *    React Native events are hard set at compile - cant do dynamic event names
+ *    so we use a single event send it to js and js then internally can prefix it
+ *    and distribute dynamically.
+ *
+ * @param eventName
+ * @private
+ */
+function subscribeToNativeModuleEvent(eventName: string) {
+  if (!NATIVE_MODULE_EVENT_SUBSCRIPTIONS[eventName]) {
+    GoogleMobileAdsNativeEventEmitter.addListener(eventName, event => {
+      if (event.appName) {
+        // native event has an appName property - auto prefix and internally emit
+        SharedEventEmitter.emit(`${event.appName}-${eventName}`, event);
+      } else {
+        // standard event - no need to prefix
+        SharedEventEmitter.emit(eventName, event);
+      }
+    });
+
+    NATIVE_MODULE_EVENT_SUBSCRIPTIONS[eventName] = true;
+  }
+}
+
+/**
+ * Help text for integrating the native counter parts for each module.
+ *
+ * @param namespace
+ * @returns {string}
+ */
+function getMissingModuleHelpText(namespace: string) {
+  const snippet = `${namespace}()`;
+  const nativeModule = namespace.charAt(0).toUpperCase() + namespace.slice(1);
+
+  if (Platform.OS === 'ios') {
+    return (
+      `You attempted to use a module that's not installed natively on your iOS project by calling ${snippet}.` +
+      '\r\n\r\nEnsure you have either linked the module or added it to your projects Podfile.' +
+      '\r\n\r\nSee http://invertase.link/ios for full setup instructions.'
+    );
+  }
+
+  const rnPackage = `'io.invertase.${namespace}.ReactNative${nativeModule}Package'`;
+  const newInstance = `'new ReactNative${nativeModule}Package()'`;
+
+  return (
+    `You attempted to use a module that's not installed on your Android project by calling ${snippet}.` +
+    `\r\n\r\nEnsure you have:\r\n\r\n1) imported the ${rnPackage} module in your 'MainApplication.java' file.\r\n\r\n2) Added the ` +
+    `${newInstance} line inside of the RN 'getPackages()' method list.` +
+    '\r\n\r\nSee http://invertase.link/android for full setup instructions.'
+  );
+}
+
+/**
+ * Gets a wrapped native module instance for the provided module.
+ * Will attempt to create a new instance if non previously created.
+ *
+ * @param module
+ * @returns {*}
+ */
+export function getNativeModule(module: ModuleInterface) {
+  const key = nativeModuleKey(module);
+
+  if (NATIVE_MODULE_REGISTRY[key]) {
+    return NATIVE_MODULE_REGISTRY[key];
+  }
+
+  return initialiseNativeModule(module);
+}
+
+/**
+ * Custom wrapped app module as it does not have it's own FirebaseModule based class.
+ *
+ * @returns {*}
+ */
+export function getAppModule() {
+  if (NATIVE_MODULE_REGISTRY[APP_NATIVE_MODULE]) {
+    return NATIVE_MODULE_REGISTRY[APP_NATIVE_MODULE];
+  }
+
+  const namespace = 'app';
+  const nativeModule = NativeModules[APP_NATIVE_MODULE];
+
+  if (!nativeModule) {
+    throw new Error(getMissingModuleHelpText(namespace));
+  }
+
+  NATIVE_MODULE_REGISTRY[APP_NATIVE_MODULE] = nativeModuleWrapped(namespace, nativeModule, []);
+
+  return NATIVE_MODULE_REGISTRY[APP_NATIVE_MODULE];
+}

package/src/types/AdEventListener.ts

@@ -0,0 +1,16 @@
+import { AdEventType } from '../AdEventType';
+import { RewardedAdReward } from './RewardedAdReward';
+import { RewardedAdEventType } from '../RewardedAdEventType';
+
+/**
+ * A callback interface for all ad events.
+ *
+ * @param type The event type, e.g. `AdEventType.LOADED`.
+ * @param error An optional JavaScript Error containing the error code and message.
+ * @param data Optional data for the event, e.g. reward type and amount
+ */
+export type AdEventListener = (
+  type: AdEventType | RewardedAdEventType,
+  error?: Error,
+  data?: RewardedAdReward,
+) => 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/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;
+  status: InitializationState;
+};

package/src/types/AdsConsent.interface.ts

@@ -0,0 +1,306 @@
+import { AdsConsentDebugGeography } from '../AdsConsentDebugGeography';
+import { AdsConsentStatus } from '../AdsConsentStatus';
+
+/**
+ * Under the Google [EU User Consent Policy](https://www.google.com/about/company/consentstaging.html), you must make certain disclosures to your users in the European Economic Area (EEA)
+ * and obtain their consent to use cookies or other local storage, where legally required, and to use personal data
+ * (such as AdID) to serve ads. This policy reflects the requirements of the EU ePrivacy Directive and the
+ * General Data Protection Regulation (GDPR).
+ *
+ * It is recommended that you determine the status of a user's consent at every app launch. The user consent status is held
+ * on the device until a condition changes which requires the user to consent again, such as a change in publishers.
+ *
+ * For more information, see [here](https://developers.google.com/admob/android/eu-consent#delay_app_measurement_optional).
+ */
+
+/**
+ * A AdProvider interface returned from `AdsConsent.getProviders`.
+ */
+export interface AdProvider {
+  /**
+   * A provider company ID.
+   */
+  companyId: string;
+
+  /**
+   * A provider company name.
+   */
+  companyName: string;
+
+  /**
+   * A fully formed URL for the privacy policy of the provider.
+   */
+  privacyPolicyUrl: string;
+}
+
+export interface AdsConsentInterface {
+  /**
+   * Requests user consent for a given list of publisher IDs.
+   *
+   * The list of publisher IDs can be obtained from the settings panel on the Google Mobile Ads console. If the list of
+   * publisher IDs has changed since the last time a user provided consent, their consent status will be reset to
+   * 'UNKNOWN' and they must provide consent again.
+   *
+   * If the request fails with the error "Could not parse Event FE preflight response", this means the state of your
+   * Google Mobile Ads account is not complete. Ensure you have validated your account and have setup valid payment
+   * information. This error is also thrown when a Publisher ID is invalid.
+   *
+   * The response from this method provides request location and consent status properties.
+   *
+   * If request location is within the EEA or unknown, and the consent status is also unknown, you
+   * must request consent via the `showForm()` method or your own means.
+   *
+   * If the consent status is not unknown, the user has already previously provided consent for the current publisher
+   * scope.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent } from 'react-native-google-mobile-ads';
+   *
+   * const consent = await AdsConsent.requestInfoUpdate(['pub-6189033257628554']);
+   * console.log('User location within EEA or Unknown:', consent.isRequestLocationInEeaOrUnknown);
+   * console.log('User consent status:', consent.status);
+   * ```
+   *
+   * @param publisherIds A list of publisher IDs found on your Google Mobile Ads dashboard.
+   */
+  requestInfoUpdate(publisherIds: string[]): Promise<AdsConsentInfo>;
+
+  /**
+   * Shows a Google-rendered user consent form.
+   *
+   * The Google-rendered consent form is a full-screen configurable form that displays over your app content. The form
+   * allows the following configuration options:
+   *
+   *
+   * 1. Consent to view personalized ads (via `withPersonalizedAds`).
+   * 2. Consent to view non-personalized ads (via `withNonPersonalizedAds`).
+   * 3. Use a paid version of the app instead of viewing ads (via `withAdFree`).
+   *
+   * Every consent form requires a privacy policy URL which outlines the usage of your application.
+   *
+   * You should review the consent text carefully: what appears by default is a message that might be appropriate if
+   * you use Google to monetize your app.
+   *
+   * If providing an ad-free version of your app, ensure you handle this once the form has been handled by the user
+   * via the `userPrefersAdFree` property. The users preference on consent is automatically forwarded onto the Google
+   * Mobile SDKs and saved.
+   *
+   * If the user is outside of the EEA, the request form will error.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';
+   *
+   * async function requestConsent() {
+   *   const consent = await AdsConsent.requestInfoUpdate(['pub-6189033257628554']);
+   *
+   *   // Check if user requires consent
+   *   if (consent.isRequestLocationInEeaOrUnknown && consent.status === AdsConsentStatus.UNKNOWN) {
+   *     // Show a Google-rendered form
+   *     const result = await AdsConsent.showForm({
+   *       privacyPolicy: 'https://invertase.io/privacy-policy',
+   *       withPersonalizedAds: true,
+   *       withNonPersonalizedAds: true,
+   *       withAdFree: true,
+   *     });
+   *
+   *     console.log('User accepted personalized: ', result.status === AdsConsentStatus.PERSONALIZED);
+   *     console.log('User accepted non-personalized: ', result.status === AdsConsentStatus.NON_PERSONALIZED);
+   *     console.log('User prefers Ad Free version of app: ', result.userPrefersAdFree);
+   *   }
+   * }
+   *
+   * ```
+   *
+   * @param options An AdsConsentFormOptions interface to control the Google-rendered form.
+   */
+  showForm(options: AdsConsentFormOptions): Promise<AdsConsentFormResult>;
+
+  /**
+   * Returns a list of ad providers currently in use for the given Google Mobile Ads App ID.
+   *
+   * If requesting consent from the user via your own method, this list of ad providers must be shown to the user
+   * for them to accept consent.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent } from 'react-native-google-mobile-ads';
+   *
+   * const providers = await AdsConsent.getAdProviders();
+   * ```
+   */
+  getAdProviders(): Promise<AdProvider[]>;
+
+  /**
+   * Sets the debug geography to locally test consent.
+   *
+   * If debugging on an emulator (where location cannot be determined) or outside of the EEA,
+   * it is possible set your own location to test how your app handles different scenarios.
+   *
+   * If using a real device, ensure you have set it as a test device via `addTestDevice()` otherwise this method will have
+   * no effect.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent, AdsConsentDebugGeography } from 'react-native-google-mobile-ads';
+   *
+   * // Set disabled
+   * await AdsConsentDebugGeography.setDebugGeography(AdsConsentDebugGeography.DISABLED);
+   *
+   * // Set within EEA
+   * await AdsConsentDebugGeography.setDebugGeography(AdsConsentDebugGeography.EEA);
+   *
+   * // Set outside EEA
+   * await AdsConsentDebugGeography.setDebugGeography(AdsConsentDebugGeography.NOT_EEA);
+   * ```
+   *
+   * @param geography The debug geography location.
+   */
+  setDebugGeography(geography: AdsConsentDebugGeography): Promise<void>;
+
+  /**
+   * Manually update the consent status of the user.
+   *
+   * This method is used when providing your own means of user consent. If using the Google-rendered form via `showForm()`,
+   * the consent status is automatically set and calling this method is not required.
+   *
+   * This method can also be used to reset the consent status, by setting it to `AdsConsentStatus.UNKNOWN`, which may be useful in certain circumstances.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';
+   *
+   * // User accepted personalized ads
+   * await AdsConsent.setStatus(AdsConsentStatus.PERSONALIZED);
+   * ```
+   *
+   * @param status The user consent status.
+   */
+  setStatus(status: AdsConsentStatus): Promise<void>;
+
+  /**
+   * Returns the current consent status of the user.
+   *
+   * > The user consent status may change at any time, therefore don't reuse old values locally and always request the current value at any time consent is required.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent } from 'react-native-google-mobile-ads';
+   *
+   * const status = await AdsConsent.getStatus();
+   * ```
+   */
+  getStatus(): Promise<AdsConsentStatus>;
+
+  /**
+   * If a publisher is aware that the user is under the age of consent, all ad requests must set TFUA (Tag For Users
+   * Under the Age of consent in Europe). This setting takes effect for all future ad requests.
+   *
+   * Once the TFUA setting is enabled, the Google-rendered consent form will fail to load. All ad requests that include
+   * TFUA will be made ineligible for personalized advertising and remarketing. TFUA disables requests to third-party
+   * ad technology providers, such as ad measurement pixels and third-party ad servers.
+   *
+   * To remove TFUA from ad requests, set the value to `false`.
+   *
+   * #### Example
+   *
+   * ```js
+   * import { AdsConsent } from 'react-native-google-mobile-ads';
+   *
+   * // User is under age of consent
+   * await AdsConsent.setTagForUnderAgeOfConsent(true);
+   * ```
+   *
+   * @param tag The boolean value to tag for under age consent.
+   */
+  setTagForUnderAgeOfConsent(tag: boolean): Promise<void>;
+
+  /**
+   * If using a real device to test, ensure the device ID is provided to the Google Mobile Ads SDK so any mock debug locations
+   * can take effect.
+   *
+   * Emulators are automatically on the allowlist and should require no action.
+   *
+   * If you are seeing real ad activity from a test device, examine logcat / console
+   * during execution in association with google mobile ads test device documentation to
+   * configure your device correctly.
+   *
+   * @param deviceIds An array of testing device ID.
+   */
+  addTestDevices(deviceIds: string[]): Promise<void>;
+}
+
+/**
+ * The options used to show on the Google-rendered consent form. At least one of `withAdFree`, `withPersonalizedAds` and `WithNonPersonalizedAds` needs to be set to `true`.
+ */
+export interface AdsConsentFormOptions {
+  /**
+   * A fully formed HTTP or HTTPS privacy policy URL for your application.
+   *
+   * Users will have the option to visit this web page before consenting to ads.
+   */
+  privacyPolicy: string;
+
+  /**
+   * Set to `true` to provide the option for the user to accept being shown personalized ads, defaults to `false`.
+   */
+  withPersonalizedAds?: boolean;
+
+  /**
+   * Set to `true` to provide the option for the user to accept being shown non-personalized ads, defaults to `false`.
+   */
+  withNonPersonalizedAds?: boolean;
+
+  /**
+   * Set to `true` to provide the option for the user to choose an ad-free version of your app, defaults to `false`.
+   *
+   * If the user chooses this option, you must handle it as required (e.g. navigating to a paid version of the app,
+   * or a subscribe view).
+   */
+  withAdFree?: boolean;
+}
+
+/**
+ * The result of a Google-rendered consent form.
+ */
+export interface AdsConsentFormResult {
+  /**
+   * The consent status of the user after closing the consent form.
+   *
+   * - UNKNOWN: The form was unable to determine the users consent status.
+   * - NON_PERSONALIZED: The user has accepted non-personalized ads.
+   * - PERSONALIZED: The user has accepted personalized ads.
+   */
+  status: AdsConsentStatus;
+
+  /**
+   * If `true`, the user requested an ad-free version of your application.
+   */
+  userPrefersAdFree: boolean;
+}
+
+/**
+ * The result of requesting info about a users consent status.
+ */
+export interface AdsConsentInfo {
+  /**
+   * The consent status of the user.
+   *
+   * - UNKNOWN: The consent status is unknown and the user must provide consent to show ads if they are within the EEA or location is also unknown.
+   * - NON_PERSONALIZED: The user has accepted non-personalized ads.
+   * - PERSONALIZED: The user has accepted personalized ads.
+   */
+  status: AdsConsentStatus;
+
+  /**
+   * If `true` the user is within the EEA or their location could not be determined.
+   */
+  isRequestLocationInEeaOrUnknown: boolean;
+}