feat(analytics): add logTransaction method (#967)

* feat(analytics): add `logTransaction` method

* style: format code

* fix(analytics): validate transaction ID before lookup

* docs(analytics): clarify transactionId property description

Author: robingenz

.changeset/add-log-transaction.md

@@ -0,0 +1,5 @@
+---
+'@capacitor-firebase/analytics': minor
+---
+
+feat(ios): add `logTransaction` method

packages/analytics/README.md

@@ -214,6 +214,7 @@ const initiateOnDeviceConversionMeasurementWithHashedPhoneNumber = async () => {
 * [`setEnabled(...)`](#setenabled)
 * [`isEnabled()`](#isenabled)
 * [`resetAnalyticsData()`](#resetanalyticsdata)
+* [`logTransaction(...)`](#logtransaction)
 * [`initiateOnDeviceConversionMeasurementWithEmailAddress(...)`](#initiateondeviceconversionmeasurementwithemailaddress)
 * [`initiateOnDeviceConversionMeasurementWithPhoneNumber(...)`](#initiateondeviceconversionmeasurementwithphonenumber)
 * [`initiateOnDeviceConversionMeasurementWithHashedEmailAddress(...)`](#initiateondeviceconversionmeasurementwithhashedemailaddress)
@@ -398,6 +399,25 @@ Only available for Android and iOS.
 --------------------
 
 
+### logTransaction(...)
+
+```typescript
+logTransaction(options: LogTransactionOptions) => Promise<void>
+```
+
+Logs a StoreKit 2 transaction.
+
+Only available for iOS (15.0+).
+
+| Param         | Type                                                                    |
+| ------------- | ----------------------------------------------------------------------- |
+| **`options`** | <code><a href="#logtransactionoptions">LogTransactionOptions</a></code> |
+
+**Since:** 8.2.0
+
+--------------------
+
+
 ### initiateOnDeviceConversionMeasurementWithEmailAddress(...)
 
 ```typescript
@@ -544,6 +564,13 @@ Only available for iOS.
 | **`enabled`** | <code>boolean</code> | 0.1.0 |
 
 
+#### LogTransactionOptions
+
+| Prop                | Type                | Description                                                | Since |
+| ------------------- | ------------------- | ---------------------------------------------------------- | ----- |
+| **`transactionId`** | <code>string</code> | The StoreKit 2 `Transaction.id` value as a numeric string. | 8.2.0 |
+
+
 #### InitiateOnDeviceConversionMeasurementWithEmailAddressOptions
 
 | Prop               | Type                | Description                                                          | Since |

packages/analytics/android/src/main/java/io/capawesome/capacitorjs/plugins/firebase/analytics/FirebaseAnalyticsPlugin.java

@@ -178,6 +178,11 @@ public void resetAnalyticsData(PluginCall call) {
         }
     }
 
+    @PluginMethod
+    public void logTransaction(PluginCall call) {
+        call.unimplemented("Not implemented on Android.");
+    }
+
     @PluginMethod
     public void initiateOnDeviceConversionMeasurementWithEmailAddress(PluginCall call) {
         call.unimplemented("Not implemented on Android.");

packages/analytics/ios/Plugin/FirebaseAnalytics.swift

@@ -1,4 +1,5 @@
 import Foundation
+import StoreKit
 
 import Capacitor
 import FirebaseCore
@@ -60,6 +61,25 @@ import FirebaseAnalytics
         Analytics.resetAnalyticsData()
     }
 
+    @available(iOS 15.0, *)
+    public func logTransaction(transactionId: String) async throws {
+        guard let id = UInt64(transactionId) else {
+            throw NSError(domain: "FirebaseAnalytics", code: 0, userInfo: [NSLocalizedDescriptionKey: "Invalid transaction identifier."])
+        }
+        var matchedTransaction: Transaction?
+        for await result in Transaction.all {
+            let transaction = FirebaseAnalyticsHelper.getTransaction(from: result)
+            if transaction.id == id {
+                matchedTransaction = transaction
+                break
+            }
+        }
+        guard let transaction = matchedTransaction else {
+            throw NSError(domain: "FirebaseAnalytics", code: 0, userInfo: [NSLocalizedDescriptionKey: "Transaction not found."])
+        }
+        Analytics.logTransaction(transaction)
+    }
+
     @objc public func initiateOnDeviceConversionMeasurement(email: String) {
         Analytics.initiateOnDeviceConversionMeasurement(emailAddress: email)
     }

packages/analytics/ios/Plugin/FirebaseAnalyticsHelper.swift

@@ -1,4 +1,5 @@
 import Foundation
+import StoreKit
 import FirebaseAnalytics
 import CommonCrypto
 
@@ -96,6 +97,16 @@ public class FirebaseAnalyticsHelper {
         return regex?.firstMatch(in: phoneNumber, range: range) != nil
     }
 
+    @available(iOS 15.0, *)
+    public static func getTransaction(from verificationResult: VerificationResult<Transaction>) -> Transaction {
+        switch verificationResult {
+        case .verified(let transaction):
+            return transaction
+        case .unverified(let transaction, _):
+            return transaction
+        }
+    }
+
     public static func sha256(_ string: String) -> Data {
         let data = string.data(using: .utf8)!
         var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))

packages/analytics/ios/Plugin/FirebaseAnalyticsPlugin.swift

@@ -22,6 +22,7 @@ public class FirebaseAnalyticsPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "setEnabled", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "isEnabled", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "resetAnalyticsData", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "logTransaction", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "initiateOnDeviceConversionMeasurementWithEmailAddress", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "initiateOnDeviceConversionMeasurementWithPhoneNumber", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "initiateOnDeviceConversionMeasurementWithHashedEmailAddress", returnType: CAPPluginReturnPromise),
@@ -34,6 +35,7 @@ public class FirebaseAnalyticsPlugin: CAPPlugin, CAPBridgedPlugin {
     public let errorEnabledMissing = "enabled must be provided."
     public let errorConsentTypeMissing = "consentType must be provided."
     public let errorConsentStatusMissing = "consentStatus must be provided."
+    public let errorTransactionIdMissing = "transactionId must be provided."
     public let errorEmailAddressMissing = "emailAddress must be provided."
     public let errorInvalidEmailFormat = "Invalid email format. Please provide a valid email address."
     public let errorPhoneNumberMissing = "phoneNumber must be provided."
@@ -125,6 +127,25 @@ public class FirebaseAnalyticsPlugin: CAPPlugin, CAPBridgedPlugin {
         call.resolve()
     }
 
+    @objc func logTransaction(_ call: CAPPluginCall) {
+        guard let transactionId = call.getString("transactionId") else {
+            call.reject(errorTransactionIdMissing)
+            return
+        }
+        if #available(iOS 15.0, *) {
+            Task {
+                do {
+                    try await implementation?.logTransaction(transactionId: transactionId)
+                    call.resolve()
+                } catch {
+                    call.reject(error.localizedDescription)
+                }
+            }
+        } else {
+            call.unimplemented("Not implemented on iOS < 15.0.")
+        }
+    }
+
     @objc func initiateOnDeviceConversionMeasurementWithEmailAddress(_ call: CAPPluginCall) {
         guard let emailAddress = call.getString("emailAddress") else {
             call.reject(errorEmailAddressMissing)

packages/analytics/src/definitions.ts

@@ -71,6 +71,14 @@ export interface FirebaseAnalyticsPlugin {
    * @since 0.1.0
    */
   resetAnalyticsData(): Promise<void>;
+  /**
+   * Logs a StoreKit 2 transaction.
+   *
+   * Only available for iOS (15.0+).
+   *
+   * @since 8.2.0
+   */
+  logTransaction(options: LogTransactionOptions): Promise<void>;
   /**
    * Initiates on-device conversion measurement with an email address.
    *
@@ -281,6 +289,18 @@ export enum ConsentStatus {
   Denied = 'DENIED',
 }
 
+/**
+ * @since 8.2.0
+ */
+export interface LogTransactionOptions {
+  /**
+   * The StoreKit 2 `Transaction.id` value as a numeric string.
+   *
+   * @since 8.2.0
+   */
+  transactionId: string;
+}
+
 /**
  * @since 7.2.0
  */

packages/analytics/src/web.ts

@@ -18,6 +18,7 @@ import type {
   InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions,
   IsEnabledResult,
   LogEventOptions,
+  LogTransactionOptions,
   SetConsentOptions,
   SetCurrentScreenOptions,
   SetEnabledOptions,
@@ -89,6 +90,10 @@ export class FirebaseAnalyticsWeb
     logEvent(analytics, options.name, options.params);
   }
 
+  public async logTransaction(_options: LogTransactionOptions): Promise<void> {
+    throw this.unimplemented('Not implemented on web.');
+  }
+
   public async setSessionTimeoutDuration(
     _options: SetSessionTimeoutDurationOptions,
   ): Promise<void> {