diff --git a/README.md b/README.md index 732909132..e3c57581c 100644 --- a/README.md +++ b/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 diff --git a/src/android/FirebasePlugin.java b/src/android/FirebasePlugin.java index 328a14c9f..7d6e48e8b 100755 --- a/src/android/FirebasePlugin.java +++ b/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()); } diff --git a/src/ios/FirebasePlugin.h b/src/ios/FirebasePlugin.h index 2474ba340..699354608 100644 --- a/src/ios/FirebasePlugin.h +++ b/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; diff --git a/src/ios/FirebasePlugin.m b/src/ios/FirebasePlugin.m index 11218acea..d424110af 100755 --- a/src/ios/FirebasePlugin.m +++ b/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 */ diff --git a/types/index.d.ts b/types/index.d.ts index 06bf28459..4ee2a1c08 100755 --- a/types/index.d.ts +++ b/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, diff --git a/www/firebase.js b/www/firebase.js index b6ad01dfd..a3d3dcf73 100644 --- a/www/firebase.js +++ b/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') {