feat: expose native SDK initialize methods as new initialize API (#40)

* feat: ios sdk initialization
* feat: android sdk initialization
* docs: add initialization docs
* docs: clearer wording
* refactor: improved formatting
* refactor: ios formatting
* refactor: remove array from type

android/src/main/java/io/invertase/googleads/ReactNativeGoogleAdsModule.java

@@ -17,16 +17,23 @@
  *
  */
 
+import com.facebook.react.bridge.Arguments;
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactMethod;
 import com.facebook.react.bridge.ReadableMap;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
 import com.google.android.gms.ads.AdRequest;
 import com.google.android.gms.ads.MobileAds;
 import com.google.android.gms.ads.RequestConfiguration;
+import com.google.android.gms.ads.initialization.AdapterStatus;
+import com.google.android.gms.ads.initialization.InitializationStatus;
+import com.google.android.gms.ads.initialization.OnInitializationCompleteListener;
 import io.invertase.googleads.common.ReactNativeModule;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 
 public class ReactNativeGoogleAdsModule extends ReactNativeModule {
@@ -107,6 +114,27 @@ private RequestConfiguration buildRequestConfiguration(ReadableMap requestConfig
     return builder.build();
   }
 
+  @ReactMethod
+  public void initialize(Promise promise) {
+    MobileAds.initialize(
+        getContext(),
+        new OnInitializationCompleteListener() {
+          @Override
+          public void onInitializationComplete(InitializationStatus initializationStatus) {
+            WritableArray result = Arguments.createArray();
+            for (Map.Entry<String, AdapterStatus> entry :
+                initializationStatus.getAdapterStatusMap().entrySet()) {
+              WritableMap info = Arguments.createMap();
+              info.putString("name", entry.getKey());
+              info.putInt("state", entry.getValue().getInitializationState().ordinal());
+              info.putString("description", entry.getValue().getDescription());
+              result.pushMap(info);
+            }
+            promise.resolve(result);
+          }
+        });
+  }
+
   @ReactMethod
   public void setRequestConfiguration(ReadableMap requestConfiguration, Promise promise) {
     MobileAds.setRequestConfiguration(buildRequestConfiguration(requestConfiguration));

docs/index.mdx

@@ -75,7 +75,7 @@ If the default ad settings are not correct for your app, you can provide setting
 For example, if the application targets children then you must configure the outbound requests to only
 receive content suitable for children before loading any adverts.
 
-If you need to set a custom request configuration, you must call the `setRequestConfiguration` method before requesting ads:
+If you need to set a custom request configuration, you must call the `setRequestConfiguration` method before initializing the Google Mobile Ads SDK:
 
 ```js
 import admob, { MaxAdContentRating } from '@invertase/react-native-google-ads';
@@ -102,6 +102,26 @@ admob()
 
 To learn more about the request configuration settings, view the [`RequestConfiguration`](/reference/admob/requestconfiguration) documentation.
 
+## Initialize the Google Mobile Ads SDK
+
+Before loading ads, have your app initialize the Google Mobile Ads SDK by calling `initialize` which initializes the SDK and returns a promise once initialization is complete (or after a 30-second timeout).
+This needs to be done only once, ideally at app launch.
+
+> ⚠️ **Warning:** Ads may be preloaded by the Mobile Ads SDK or mediation partner SDKs upon calling `initialize`.
+If you need to obtain consent from users in the European Economic Area (EEA), set any request-specific flags (such as tagForChildDirectedTreatment), or otherwise take action before loading ads, ensure you do so before initializing the Mobile Ads SDK.
+
+```js
+import admob from '@invertase/react-native-google-ads';
+
+admob()
+  .initialize()
+  .then((adapterStatuses) => {
+    // Initialization complete!
+  });
+```
+
+If you are using mediation, you may wish to wait until the promise is settled before loading ads, as this will ensure that all mediation adapters are initialized.
+
 ## European User Consent
 
 Out of the box, AdMob does not handle any related regulations which you may need to enforce on your application.

ios/RNGoogleAds/RNGoogleAdsModule.m

@@ -34,6 +34,24 @@ - (dispatch_queue_t)methodQueue {
 #pragma mark -
 #pragma mark Google Mobile Ads Methods
 
+RCT_EXPORT_METHOD(initialize : (RCTPromiseResolveBlock)resolve : (RCTPromiseRejectBlock)reject) {
+  [[GADMobileAds sharedInstance]
+      startWithCompletionHandler:^(GADInitializationStatus *_Nonnull status) {
+        NSDictionary *adapterStatuses = [status adapterStatusesByClassName];
+        NSMutableArray *result = [[NSMutableArray alloc] init];
+        for (NSString *adapter in adapterStatuses) {
+          GADAdapterStatus *adapterStatus = adapterStatuses[adapter];
+          NSDictionary *dict = @{
+            @"name" : adapter,
+            @"state" : @(adapterStatus.state),
+            @"description" : adapterStatus.description
+          };
+          [result addObject:dict];
+        }
+        resolve(result);
+      }];
+}
+
 RCT_EXPORT_METHOD(setRequestConfiguration
                   : (NSDictionary *)requestConfiguration
                   : (RCTPromiseResolveBlock)resolve

lib/googleMobileAds.js

@@ -26,6 +26,10 @@ class GoogleAdsModule extends Module {
     });
   }
 
+  initialize() {
+    return this.native.initialize();
+  }
+
   setRequestConfiguration(requestConfiguration) {
     let config;
     try {

lib/index.d.ts

@@ -725,6 +725,15 @@ export namespace GoogleAdsTypes {
     customData?: string;
   }
 
+  /**
+   * An immutable snapshot of a mediation adapter's initialization status.
+   */
+  export type AdapterStatus = {
+    name: string;
+    description: string;
+    status: 0 | 1;
+  };
+
   /**
    * The `RequestConfiguration` used when setting global ad settings via `setRequestConfiguration`.
    */
@@ -1123,6 +1132,11 @@ export namespace GoogleAdsTypes {
    * The Google Ads service interface.
    */
   export class Module {
+    /**
+     * Initialize the SDK.
+     */
+    initialize(): Promise<AdapterStatus[]>;
+
     /**
      * Sets request options for all future ad requests.
      *