react-native-google-mobile-ads 5.0.0 → 5.1.1

package/lib/typescript/AdsConsentPurposes.d.ts

@@ -0,0 +1,148 @@
+export declare enum AdsConsentPurposes {
+    /**
+     * Cookies, device identifiers, or other information can be stored or
+     * accessed on your device for the purposes presented to you.
+     *
+     * Vendors can:
+     *   - Store and access information on the device such as cookies
+     *     and device identifiers presented to a user.
+     */
+    STORE_AND_ACCESS_INFORMATION_ON_DEVICE = 1,
+    /**
+     * Ads can be shown to you based on the content you’re viewing,
+     * the app you’re using, your approximate location, or your device type.
+     *
+     * To do basic ad selection vendors can:
+     *  - Use real-time information about the context in which the ad will be shown,
+     *    to show the ad, including information about the content and the device, such as:
+     *    device type and capabilities, user agent, URL, IP address
+     *  - Use a user’s non-precise geolocation data
+     *  - Control the frequency of ads shown to a user.
+     *  - Sequence the order in which ads are shown to a user.
+     *  - Prevent an ad from serving in an unsuitable editorial (brand-unsafe) context
+     *
+     * Vendors cannot:
+     *  - Create a personalised ads profile using this information for the selection of
+     *    future ads without a separate legal basis to create a personalised ads profile.
+     *  - N.B. Non-precise means only an approximate location involving at least a radius
+     *    of 500 meters is permitted.
+     */
+    SELECT_BASIC_ADS = 2,
+    /**
+     * A profile can be built about you and your interests to show you personalised ads
+     * that are relevant to you.
+     *
+     * To create a personalised ads profile vendors can:
+     *   - Collect information about a user, including a user's activity, interests,
+     *     demographic information, or location, to create or edit a user profile for use
+     *     in personalised advertising.
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps, to create or edit a user profile
+     *     for use in personalised advertising.
+     */
+    CREATE_A_PERSONALISED_ADS_PROFILE = 3,
+    /**
+     * Personalised ads can be shown to you based on a profile about you.
+     *
+     * To select personalised ads vendors can:
+     *   - Select personalised ads based on a user profile or other historical user data,
+     *     including a user’s prior activity, interests, visits to sites or apps, location,
+     *     or demographic information.
+     */
+    SELECT_PERSONALISED_ADS = 4,
+    /**
+     * A profile can be built about you and your interests to show you personalised content
+     * that is relevant to you.
+     *
+     * To create a personalised content profile vendors can:
+     *   - Collect information about a user, including a user's activity, interests, visits to
+     *     sites or apps, demographic information, or location, to create or edit a user profile
+     *     for personalising content.
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps, to create or edit a user profile for use
+     *     in personalising content.
+     */
+    CREATE_A_PERSONALISED_CONTENT_PROFILE = 5,
+    /**
+     * Personalised content can be shown to you based on a profile about you.
+     *
+     * To select personalised content vendors can:
+     *   - Select personalised content based on a user profile or other historical user data,
+     *     including a user’s prior activity, interests, visits to sites or apps, location,
+     *     or demographic information.
+     */
+    SELECT_PERSONALISED_CONTENT = 6,
+    /**
+     * The performance and effectiveness of ads that you see or interact with can be measured.
+     *
+     * To measure ad performance vendors can:
+     *   - Measure whether and how ads were delivered to and interacted with by a user
+     *   - Provide reporting about ads including their effectiveness and performance
+     *   - Provide reporting about users who interacted with ads using data observed during
+     *     the course of the user's interaction with that ad
+     *   - Provide reporting to publishers about the ads displayed on their property
+     *   - Measure whether an ad is serving in a suitable editorial environment (brand-safe) context
+     *   - Determine the percentage of the ad that had the opportunity to be seen and
+     *     the duration of that opportunity
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps
+     *
+     * Vendors cannot:
+     *   - Apply panel- or similarly-derived audience insights data to ad measurement data
+     *     without a Legal Basis to apply market research to generate audience insights (Purpose 9)
+     */
+    MEASURE_AD_PERFORMANCE = 7,
+    /**
+     * The performance and effectiveness of content that you see or interact with can be measured.
+     *
+     * To measure content performance vendors can:
+     *   - Measure and report on how content was delivered to and interacted with by users.
+     *   - Provide reporting, using directly measurable or known information, about users who
+     *     interacted with the content
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps.
+     *
+     * Vendors cannot:
+     *   - Measure whether and how ads (including native ads) were delivered to and
+     *     interacted with by a user.
+     *   - Apply panel- or similarly derived audience insights data to ad measurement
+     *     data without a Legal Basis to apply market research to generate audience insights (Purpose 9)
+     */
+    MEASURE_CONTENT_PERFORMANCE = 8,
+    /**
+     * Market research can be used to learn more about the audiences who visit sites/apps and view ads.
+     *
+     * To apply market research to generate audience insights vendors can:
+     *   - Provide aggregate reporting to advertisers or their representatives about
+     *     the audiences reached by their ads, through panel-based and similarly derived insights.
+     *   - Provide aggregate reporting to publishers about the audiences that were served or
+     *     interacted with content and/or ads on their property by applying
+     *     panel-based and similarly derived insights.
+     *   - Associate offline data with an online user for the purposes of
+     *     market research to generate audience insights if vendors have declared to match and
+     *     combine offline data sources (Feature 1)
+     *   - Combine this information with other information previously collected including from
+     *     across websites and apps.
+     *
+     * Vendors cannot:
+     *   - Measure the performance and effectiveness of ads that a specific user was served or
+     *     interacted with, without a Legal Basis to measure ad performance.
+     *   - Measure which content a specific user was served and how they interacted with it,
+     *     without a Legal Basis to measure content performance.
+     */
+    APPLY_MARKET_RESEARCH_TO_GENERATE_AUDIENCE_INSIGHTS = 9,
+    /**
+     * Your data can be used to improve existing systems and software,
+     * and to develop new products
+     *
+     * To develop new products and improve products vendors can:
+     *   - Use information to improve their existing products with new features and
+     *     to develop new products
+     *   - Create new models and algorithms through machine learning
+     *
+     * Vendors cannot:
+     *   - Conduct any other data processing operation allowed under
+     *     a different purpose under this purpose
+     */
+    DEVELOP_AND_IMPROVE_PRODUCTS = 10
+}

package/lib/typescript/AdsConsentSpecialFeatures.d.ts

@@ -0,0 +1,22 @@
+export declare enum AdsConsentSpecialFeatures {
+    /**
+     * Your precise geolocation data can be used in support of one or more purposes.
+     * This means your location can be accurate to within several meters.
+     *
+     * Vendors can:
+     *   - Collect and process precise geolocation data in support of one or more purposes.
+     *   - Precise geolocation means that there are no restrictions on the precision of
+     *     a user's location; this can be accurate to within several meters.
+     */
+    USE_PRECISE_GEOLOCATION_DATA = 1,
+    /**
+     * Your device can be identified based on a scan of your device's
+     * unique combination of characteristics.
+     *
+     * Vendors can:
+     *   - Create an identifier using data collected via actively scanning a device for
+     *     specific characteristics, e.g. installed fonts or screen resolution.
+     *   - Use such an identifier to re-identify a device.
+     */
+    ACTIVELY_SCAN_DEVICE_CHARACTERISTICS_FOR_IDENTIFICATION = 2
+}

package/lib/typescript/hooks/useAppOpenAd.d.ts

@@ -0,0 +1,9 @@
+import { AdHookReturns } from '../types/AdStates';
+import { RequestOptions } from '../types/RequestOptions';
+/**
+ * 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 declare function useAppOpenAd(adUnitId: string | null, requestOptions?: RequestOptions): Omit<AdHookReturns, 'adReward'>;

package/lib/typescript/hooks/useFullScreenAd.d.ts

@@ -0,0 +1,5 @@
+import { AppOpenAd } from '../ads/AppOpenAd';
+import { InterstitialAd } from '../ads/InterstitialAd';
+import { RewardedAd } from '../ads/RewardedAd';
+import { AdHookReturns } from '../types/AdStates';
+export declare function useFullScreenAd<T extends InterstitialAd | RewardedAd | AppOpenAd | null>(ad: T): AdHookReturns;

package/lib/typescript/hooks/useInterstitialAd.d.ts

@@ -0,0 +1,9 @@
+import { AdHookReturns } from '../types/AdStates';
+import { RequestOptions } from '../types/RequestOptions';
+/**
+ * React Hook for Interstitial Ad.
+ *
+ * @param adUnitId The Ad Unit ID for the Interstitial 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 declare function useInterstitialAd(adUnitId: string | null, requestOptions?: RequestOptions): Omit<AdHookReturns, 'adReward'>;

package/lib/typescript/hooks/useRewardedAd.d.ts

@@ -0,0 +1,9 @@
+import { AdHookReturns } from '../types/AdStates';
+import { RequestOptions } from '../types/RequestOptions';
+/**
+ * React Hook for Rewarded Ad.
+ *
+ * @param adUnitId The Ad Unit ID for the Rewarded 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 declare function useRewardedAd(adUnitId: string | null, requestOptions?: RequestOptions): Omit<AdHookReturns, 'adReward'>;

package/lib/typescript/index.d.ts

@@ -1,6 +1,8 @@
-export declare const SDK_VERSION = "5.0.0";
+export declare const SDK_VERSION = "5.1.1";
 export { default, MobileAds } from './MobileAds';
 export { AdsConsentDebugGeography } from './AdsConsentDebugGeography';
+export { AdsConsentPurposes } from './AdsConsentPurposes';
+export { AdsConsentSpecialFeatures } from './AdsConsentSpecialFeatures';
 export { AdsConsentStatus } from './AdsConsentStatus';
 export { MaxAdContentRating } from './MaxAdContentRating';
 export { TestIds } from './TestIds';
@@ -12,3 +14,6 @@ export { AppOpenAd } from './ads/AppOpenAd';
 export { InterstitialAd } from './ads/InterstitialAd';
 export { RewardedAd } from './ads/RewardedAd';
 export { BannerAd } from './ads/BannerAd';
+export { useAppOpenAd } from './hooks/useAppOpenAd';
+export { useInterstitialAd } from './hooks/useInterstitialAd';
+export { useRewardedAd } from './hooks/useRewardedAd';

package/lib/typescript/types/AdStates.d.ts

@@ -0,0 +1,85 @@
+import { AdShowOptions } from './AdShowOptions';
+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;
+    /**
+     * 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/lib/typescript/types/AdsConsent.interface.d.ts

@@ -1,3 +1,4 @@
+import { TCModel } from '@iabtcf/core';
 import { AdsConsentDebugGeography } from '../AdsConsentDebugGeography';
 import { AdsConsentStatus } from '../AdsConsentStatus';
 /**
@@ -55,6 +56,47 @@ export interface AdsConsentInterface {
      * ```
      */
     showForm(): Promise<AdsConsentFormResult>;
+    /**
+     * Returns the value stored under the `IABTCF_TCString` key
+     * in NSUserDefaults (iOS) / SharedPreferences (Android) as
+     * defined by the IAB Europe Transparency & Consent Framework.
+     *
+     * More information available here:
+     * https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#in-app-details
+     *
+     * #### Example
+     *
+     * ```js
+     * import { AdsConsent } from '@invertase/react-native-google-ads';
+     *
+     * const tcString = await AdsConsent.getTCString();
+     * ```
+     */
+    getTCString(): Promise<string>;
+    /**
+     * Returns the TC Model of the saved IAB TCF 2.0 String.
+     *
+     * #### Example
+     *
+     * ```js
+     * import { AdsConsent } from '@invertase/react-native-google-ads';
+     *
+     * const tcModel = await AdsConsent.getTCModel();
+     * ```
+     */
+    getTCModel(): Promise<TCModel>;
+    /**
+     * Provides information about a user's consent choices.
+     *
+     * #### Example
+     *
+     * ```js
+     * import { AdsConsent } from '@invertase/react-native-google-ads';
+     *
+     * const { storeAndAccessInformationOnDevice } = await AdsConsent.getUserChoices();
+     * ```
+     */
+    getUserChoices(): Promise<AdsConsentUserChoices>;
     /**
      * Resets the UMP SDK state.
      *
@@ -117,3 +159,177 @@ export interface AdsConsentInfo {
      */
     isConsentFormAvailable: boolean;
 }
+/**
+ * The options used when requesting consent information.
+ *
+ * https://vendor-list.consensu.org/v2/vendor-list.json
+ * https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework
+ */
+export interface AdsConsentUserChoices {
+    /**
+     * Your device can be identified based on a scan of your device's
+     * unique combination of characteristics.
+     *
+     * Vendors can:
+     *   - Create an identifier using data collected via actively scanning a device for
+     *   - specific characteristics, e.g. installed fonts or screen resolution.
+     *   - Use such an identifier to re-identify a device.
+     */
+    activelyScanDeviceCharacteristicsForIdentification: boolean;
+    /**
+     * Market research can be used to learn more about the audiences who visit sites/apps and view ads.
+     *
+     * To apply market research to generate audience insights vendors can:
+     *   - Provide aggregate reporting to advertisers or their representatives about
+     *     the audiences reached by their ads, through panel-based and similarly derived insights.
+     *   - Provide aggregate reporting to publishers about the audiences that were served or
+     *     interacted with content and/or ads on their property by applying
+     *     panel-based and similarly derived insights.
+     *   - Associate offline data with an online user for the purposes of
+     *     market research to generate audience insights if vendors have declared to match and
+     *     combine offline data sources (Feature 1)
+     *   - Combine this information with other information previously collected including from
+     *     across websites and apps.
+     *
+     * Vendors cannot:
+     *   - Measure the performance and effectiveness of ads that a specific user was served or
+     *     interacted with, without a Legal Basis to measure ad performance.
+     *   - Measure which content a specific user was served and how they interacted with it,
+     *     without a Legal Basis to measure content performance.
+     */
+    applyMarketResearchToGenerateAudienceInsights: boolean;
+    /**
+     * A profile can be built about you and your interests to show you personalised ads
+     * that are relevant to you.
+     *
+     * To create a personalised ads profile vendors can:
+     *   - Collect information about a user, including a user's activity, interests,
+     *     demographic information, or location, to create or edit a user profile for use
+     *     in personalised advertising.
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps, to create or edit a user profile
+     *     for use in personalised advertising.
+     */
+    createAPersonalisedAdsProfile: boolean;
+    /**
+     * A profile can be built about you and your interests to show you personalised content
+     * that is relevant to you.
+     *
+     * To create a personalised content profile vendors can:
+     *   - Collect information about a user, including a user's activity, interests, visits to
+     *     sites or apps, demographic information, or location, to create or edit a user profile
+     *     for personalising content.
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps, to create or edit a user profile for use
+     *     in personalising content.
+     */
+    createAPersonalisedContentProfile: boolean;
+    /**
+     * Your data can be used to improve existing systems and software,
+     * and to develop new products
+     *
+     * To develop new products and improve products vendors can:
+     *   - Use information to improve their existing products with new features and
+     *     to develop new products
+     *   - Create new models and algorithms through machine learning
+     *
+     * Vendors cannot:
+     *   - Conduct any other data processing operation allowed under
+     *     a different purpose under this purpose
+     */
+    developAndImproveProducts: boolean;
+    /**
+     * The performance and effectiveness of ads that you see or interact with can be measured.
+     *
+     * To measure ad performance vendors can:
+     *   - Measure whether and how ads were delivered to and interacted with by a user
+     *   - Provide reporting about ads including their effectiveness and performance
+     *   - Provide reporting about users who interacted with ads using data observed during
+     *     the course of the user's interaction with that ad
+     *   - Provide reporting to publishers about the ads displayed on their property
+     *   - Measure whether an ad is serving in a suitable editorial environment (brand-safe) context
+     *   - Determine the percentage of the ad that had the opportunity to be seen and
+     *     the duration of that opportunity
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps
+     *
+     * Vendors cannot:
+     *   - Apply panel- or similarly-derived audience insights data to ad measurement data
+     *     without a Legal Basis to apply market research to generate audience insights (Purpose 9)
+     */
+    measureAdPerformance: boolean;
+    /**
+     * The performance and effectiveness of content that you see or interact with can be measured.
+     *
+     * To measure content performance vendors can:
+     *   - Measure and report on how content was delivered to and interacted with by users.
+     *   - Provide reporting, using directly measurable or known information, about users who
+     *     interacted with the content
+     *   - Combine this information with other information previously collected,
+     *     including from across websites and apps.
+     *
+     * Vendors cannot:
+     *   - Measure whether and how ads (including native ads) were delivered to and
+     *     interacted with by a user.
+     *   - Apply panel- or similarly derived audience insights data to ad measurement
+     *     data without a Legal Basis to apply market research to generate audience insights (Purpose 9)
+     */
+    measureContentPerformance: boolean;
+    /**
+     * Ads can be shown to you based on the content you’re viewing,
+     * the app you’re using, your approximate location, or your device type.
+     *
+     * To do basic ad selection vendors can:
+     *  - Use real-time information about the context in which the ad will be shown,
+     *    to show the ad, including information about the content and the device, such as:
+     *    device type and capabilities, user agent, URL, IP address
+     *  - Use a user’s non-precise geolocation data
+     *  - Control the frequency of ads shown to a user.
+     *  - Sequence the order in which ads are shown to a user.
+     *  - Prevent an ad from serving in an unsuitable editorial (brand-unsafe) context
+     *
+     * Vendors cannot:
+     *  - Create a personalised ads profile using this information for the selection of
+     *    future ads without a separate legal basis to create a personalised ads profile.
+     *  - N.B. Non-precise means only an approximate location involving at least a radius
+     *    of 500 meters is permitted.
+     */
+    selectBasicAds: boolean;
+    /**
+     * Personalised ads can be shown to you based on a profile about you.
+     *
+     * To select personalised ads vendors can:
+     *   - Select personalised ads based on a user profile or other historical user data,
+     *     including a user’s prior activity, interests, visits to sites or apps, location,
+     *     or demographic information.
+     */
+    selectPersonalisedAds: boolean;
+    /**
+     * Personalised content can be shown to you based on a profile about you.
+     *
+     * To select personalised content vendors can:
+     *   - Select personalised content based on a user profile or other historical user data,
+     *     including a user’s prior activity, interests, visits to sites or apps, location,
+     *     or demographic information.
+     */
+    selectPersonalisedContent: boolean;
+    /**
+     * Cookies, device identifiers, or other information can be stored or
+     * accessed on your device for the purposes presented to you.
+     *
+     * Vendors can:
+     *   - Store and access information on the device such as cookies and
+     *     device identifiers presented to a user.
+     */
+    storeAndAccessInformationOnDevice: boolean;
+    /**
+     * Your precise geolocation data can be used in support of one or more purposes.
+     * This means your location can be accurate to within several meters.
+     *
+     * Vendors can:
+     *   - Collect and process precise geolocation data in support of one or more purposes.
+     *   - Precise geolocation means that there are no restrictions on the precision of
+     *     a user's location; this can be accurate to within several meters.
+     */
+    usePreciseGeolocationData: boolean;
+}

package/lib/typescript/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.0.0";
+export declare const version = "5.1.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-google-mobile-ads",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "author": "Invertase <oss@invertase.io> (http://invertase.io)",
   "description": "React Native Google Mobile Ads is an easy way to monetize mobile apps with targeted, in-app advertising.",
   "main": "lib/commonjs/index.js",
@@ -72,7 +72,7 @@
     "lint:ios:check": "clang-format --glob=\"ios/**/*.{h,cpp,m,mm}\" --style=Google -n -Werror",
     "lint:ios:fix": "clang-format -i --glob=\"ios/**/*.{h,cpp,m,mm}\" --style=Google",
     "lint:markdown:check": "prettier --check \"docs/**/*.md[x]\"",
-    "lint:markdown:fix": "prettier --write \"docs/**/*.md\"",
+    "lint:markdown:fix": "prettier --write \"docs/**/*.md[x]\"",
     "lint:report": "eslint --output-file=eslint-report.json --format=json . --ext .js,.jsx,.ts,.tsx",
     "lint:spellcheck": "spellchecker --quiet --files=\"docs/**/*.md\" --dictionaries=\"./.spellcheck.dict.txt\" --reports=\"spelling.json\" --plugins spell indefinite-article repeated-words syntax-mentions syntax-urls frontmatter",
     "tsc:compile": "tsc --project . --noEmit",
@@ -98,6 +98,10 @@
     "tests:ios:test-cover-reuse": "cd example && node_modules/.bin/nyc yarn detox test --configuration ios.sim.debug --reuse --loglevel warn",
     "tests:ios:pod:install": "cd example && cd ios && rm -rf example.xcworkspace && rm -f Podfile.lock && pod install --repo-update && cd .."
   },
+  "dependencies": {
+    "@iabtcf/core": "^1.4.0",
+    "use-deep-compare-effect": "^1.8.1"
+  },
   "devDependencies": {
     "@babel/core": "^7.16.0",
     "@babel/preset-env": "^7.16.4",