feat(analytics): add getAppInstanceId for use with ga4 measurement protocol

README.md

@@ -117,6 +117,7 @@ To help ensure this plugin is kept updated, new features are added and bugfixes
     - [setScreenName](#setscreenname)
     - [setUserId](#setuserid)
     - [setUserProperty](#setuserproperty)
+    - [getAppInstanceId](#getappinstanceid)
     - [initiateOnDeviceConversionMeasurement](#initiateondeviceconversionmeasurement)
   - [Crashlytics](#crashlytics)
     - [setCrashlyticsCollectionEnabled](#setcrashlyticscollectionenabled)
@@ -2580,6 +2581,25 @@ Set a user property for use in Analytics:
 FirebasePlugin.setUserProperty("name", "value");
 ```
 
+### getAppInstanceId
+
+Get the app instance ID for use with the [Google Analytics Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4). The app instance ID is used to join Measurement Protocol events with online interactions using the `app_instance_id` parameter, but Measurement Protocol events will only attribute if the `app_instance_id` has already been observed by the Firebase SDK in that app session.
+
+**Parameters**:
+
+-   {function} success - callback function which will be invoked on success.
+    Will be passed a {string} containing the app instance ID (or `null` if Analytics storage consent is denied or Analytics collection is disabled, per [Firebase Analytics consent behavior](https://firebase.google.com/docs/analytics/consent)).
+-   {function} error - (optional) callback function which will be passed a {string} error message as an argument
+
+```javascript
+FirebasePlugin.getAppInstanceId(function(appInstanceId) {
+    console.log("App Instance ID: " + appInstanceId);
+    // Use appInstanceId with Google Analytics Measurement Protocol
+}, function(error) {
+    console.error("Error getting app instance ID: " + error);
+});
+```
+
 
 ### initiateOnDeviceConversionMeasurement
 

src/android/FirebasePlugin.java

@@ -361,6 +361,9 @@ public boolean execute(String action, JSONArray args, CallbackContext callbackCo
                 case "setUserProperty":
                     this.setUserProperty(callbackContext, args.getString(0), args.getString(1));
                     break;
+                case "getAppInstanceId":
+                    this.getAppInstanceId(callbackContext);
+                    break;
                 case "activateFetched":
                     this.activateFetched(callbackContext);
                     break;
@@ -1163,6 +1166,19 @@ public void run() {
         });
     }
 
+    private void getAppInstanceId(final CallbackContext callbackContext) {
+        cordova.getThreadPool().execute(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    handleTaskOutcomeWithStringResult(mFirebaseAnalytics.getAppInstanceId(), callbackContext);
+                } catch (Exception e) {
+                    handleExceptionWithContext(e, callbackContext);
+                }
+            }
+        });
+    }
+
     private void fetch(CallbackContext callbackContext) {
         fetch(callbackContext, FirebaseRemoteConfig.getInstance().fetch());
     }

src/ios/FirebasePlugin.h

@@ -77,6 +77,7 @@
 - (void)setUserId:(CDVInvokedUrlCommand*)command;
 - (void)setUserProperty:(CDVInvokedUrlCommand*)command;
 - (void)initiateOnDeviceConversionMeasurement:(CDVInvokedUrlCommand*)command;
+- (void)getAppInstanceId:(CDVInvokedUrlCommand*)command;
 
 // Crashlytics
 - (void)setCrashlyticsCollectionEnabled:(CDVInvokedUrlCommand*)command;

src/ios/FirebasePlugin.m

@@ -1750,6 +1750,33 @@ - (void) initiateOnDeviceConversionMeasurement:(CDVInvokedUrlCommand*)command {
     }];
 }
 
+- (void)getAppInstanceId:(CDVInvokedUrlCommand*)command {
+    [self.commandDelegate runInBackground:^{
+        @try {
+            NSString *appInstanceID = [FIRAnalytics appInstanceID];
+
+            CDVPluginResult *pluginResult = nil;
+
+            if (appInstanceID != nil && appInstanceID.length > 0) {
+                pluginResult = [CDVPluginResult
+                                resultWithStatus:CDVCommandStatus_OK
+                                messageAsString:appInstanceID];
+            } else {
+                NSString *errorMessage = @"Failed to get app instance ID: value is nil or empty. Ensure Firebase Analytics is initialized and collection is enabled.";
+                pluginResult = [CDVPluginResult
+                                resultWithStatus:CDVCommandStatus_ERROR
+                                messageAsString:errorMessage];
+            }
+
+            [self.commandDelegate sendPluginResult:pluginResult
+                                        callbackId:command.callbackId];
+        }
+        @catch (NSException *exception) {
+            [self handlePluginExceptionWithContext:exception :command];
+        }
+    }];
+}
+
 /*
  * Crashlytics
  */

types/index.d.ts

@@ -148,6 +148,10 @@ export interface FirebasePlugin {
         userName: string,
         userValue: string
     ): void
+    getAppInstanceId(
+        success?: (appInstanceId: string | null) => void,
+        error?: (err: string) => void
+    ): void
     initiateOnDeviceConversionMeasurement(
         userIdentifier: { emailAddress?:string, phoneNumber?: string },
         success?: () => void,

www/firebase.js

@@ -200,6 +200,10 @@ exports.initiateOnDeviceConversionMeasurement = function(userIdentifier, success
     exec(success, error, "FirebasePlugin", "initiateOnDeviceConversionMeasurement", [userIdentifier]);
 }
 
+exports.getAppInstanceId = function(success, error) {
+    exec(success, error, "FirebasePlugin", "getAppInstanceId", []);
+};
+
 exports.fetch = function (cacheExpirationSeconds, success, error) {
     var args = [];
     if (typeof cacheExpirationSeconds === 'number') {