KM-17457: Introduce IAP processing KPI metrics

kp-diego-trevisan · kp-diego-trevisan · commit 99382b891fb6 · 2026-07-27T12:11:32.000+02:00
diff --git a/LocalPackages/PIALibrary/Package.swift b/LocalPackages/PIALibrary/Package.swift
@@ -69,6 +69,7 @@ let package = Package(
             name: "PIALibraryTests",
             dependencies: [
                 "PIALibrary",
+                .product(name: "PIAKPI", package: "PIAKPI"),
                 .product(
                     name: "TunnelKitOpenVPN",
                     package: "mobile-ios-openvpn",
diff --git a/LocalPackages/PIALibrary/Sources/PIALibrary/Account/DefaultAccountProvider.swift b/LocalPackages/PIALibrary/Sources/PIALibrary/Account/DefaultAccountProvider.swift
@@ -494,8 +494,14 @@ public final class DefaultAccountProvider: AccountProvider, ConfigurationAccess,
 
             accessedDatabase.plain.lastSignupEmail = request.email
 
+            // A new IAP transaction starts processing (Kape verification path).
+            ServiceQualityManager.shared.iapProcessingPurchaseEvent(origin: .signup)
+
+            var verificationSucceeded = false
             do {
                 let credentials = try await webServices.signup(with: signup)
+                verificationSucceeded = true
+                ServiceQualityManager.shared.iapProcessingSuccessEvent(origin: .signup)
 
                 if let transaction = request.transaction {
                     accessedStore.finishTransaction(transaction, success: true)
@@ -518,14 +524,19 @@ public final class DefaultAccountProvider: AccountProvider, ConfigurationAccess,
             } catch let error as ClientError where error == .badReceipt {
                 // If signup failed with badReceipt (HTTP 400), try login-with-receipt.
                 // This handles returning users (e.g. "Duplicate purchase" from API).
+                // The fallback reports the final verification outcome, so no event here.
                 await attemptLoginWithReceiptFallback(transaction: request.transaction, callback: callback)
             } catch {
-                if let urlError = error as? URLError, (urlError.code == .notConnectedToInternet) {
-                    DispatchQueue.main.async { callback?(nil, ClientError.internetUnreachable) }
-                    return
+                let isOffline = (error as? URLError)?.code == .notConnectedToInternet
+                let reportedError: Error = isOffline ? ClientError.internetUnreachable : error
+
+                // Report a verification failure only if success was not already reported
+                // (later account-setup calls failing is not a verification failure).
+                if !verificationSucceeded {
+                    ServiceQualityManager.shared.iapProcessingFailureEvent(origin: .signup, error: reportedError)
                 }
 
-                DispatchQueue.main.async { callback?(nil, error) }
+                DispatchQueue.main.async { callback?(nil, reportedError) }
             }
         }
 
@@ -538,16 +549,20 @@ public final class DefaultAccountProvider: AccountProvider, ConfigurationAccess,
             }
 
             guard let jws else {
+                ServiceQualityManager.shared.iapProcessingFailureEvent(origin: .signup, error: ClientError.badReceipt)
                 DispatchQueue.main.async { callback?(nil, ClientError.badReceipt) }
                 return
             }
 
             do {
                 try await webServices.token(receipt: jws)
             } catch {
+                ServiceQualityManager.shared.iapProcessingFailureEvent(origin: .signup, error: error)
                 DispatchQueue.main.async { callback?(nil, ClientError.badReceipt) }
                 return
             }
+            // Receipt verified via the login-with-receipt fallback.
+            ServiceQualityManager.shared.iapProcessingSuccessEvent(origin: .signup)
 
             if let transaction = transaction {
                 accessedStore.finishTransaction(transaction, success: true)
@@ -636,8 +651,14 @@ public final class DefaultAccountProvider: AccountProvider, ConfigurationAccess,
                 return
             }
 
+            // A renewal IAP transaction starts processing (Kape verification path).
+            ServiceQualityManager.shared.iapProcessingPurchaseEvent(origin: .renewal)
+
+            var verificationSucceeded = false
             do {
                 try await webServices.processPayment(credentials: user.credentials, request: payment)
+                verificationSucceeded = true
+                ServiceQualityManager.shared.iapProcessingSuccessEvent(origin: .renewal)
 
                 if let transaction = request.transaction {
                     accessedStore.finishTransaction(transaction, success: true)
@@ -651,6 +672,9 @@ public final class DefaultAccountProvider: AccountProvider, ConfigurationAccess,
                 Macros.postNotification(.PIAAccountDidRefresh, [.user: user])
                 DispatchQueue.main.async { callback?(user, nil) }
             } catch {
+                if !verificationSucceeded {
+                    ServiceQualityManager.shared.iapProcessingFailureEvent(origin: .renewal, error: error)
+                }
                 DispatchQueue.main.async { callback?(nil, error) }
             }
         }
diff --git a/LocalPackages/PIALibrary/Sources/PIALibrary/ServiceQuality/ServiceQualityManager.swift b/LocalPackages/PIALibrary/Sources/PIALibrary/ServiceQuality/ServiceQualityManager.swift
@@ -27,7 +27,7 @@ private let log = PIALogger.logger(for: ServiceQualityManager.self)
 public final class ServiceQualityManager: NSObject {
 
     public static let shared = ServiceQualityManager()
-    private let kpiPreferenceName = "PIA_KPI_PREFERENCE_NAME"
+    private static let kpiPreferenceName = "PIA_KPI_PREFERENCE_NAME"
     private var kpiManager: KPIAPI?
     private var isAppActive = true
 
@@ -68,12 +68,60 @@ public final class ServiceQualityManager: NSObject {
         case timeToConnect = "time_to_connect"
     }
 
+    /**
+     * Enum defining the in-app-purchase processing events.
+     * These track the KapeClientSDK receipt-verification funnel.
+     */
+    private enum KPIIapEvent: String {
+        case iapProcessingPurchase = "iap_processing_purchase"
+        case iapProcessingSuccess = "iap_processing_success"
+        case iapProcessingRetry = "iap_processing_retry"
+        case iapProcessingFailure = "iap_processing_failure"
+    }
+
+    /**
+     * Property keys for the IAP processing events. Their raw values are camelCase
+     * on purpose: they are the cross-platform (XV) wire contract, unlike the
+     * lower_snake_case keys used by the connection events above.
+     */
+    private enum KPIIapPropertyKey: String {
+        case origin
+        case environment
+        case retryCount
+        case error
+        case csi
+        case internalError
+        case rawError
+    }
+
+    /**
+     * The user-facing flow a purchase originated from, reported as the `origin`
+     * property. NOTE: the XV spec lists `origin` but does not enumerate its values;
+     * these map to the two purchase-crediting flows and can be adjusted if XV
+     * expects a fixed literal (e.g. a store name).
+     */
+    public enum KPIIapOrigin: String {
+        case signup
+        case renewal
+    }
+
     public override init() {
         super.init()
+        kpiManager = ServiceQualityManager.makeKPIManager()
+        registerAppStateObservers()
+    }
 
+    /// Injectable initializer used by unit tests to supply a mock `KPIAPI`.
+    init(kpiManager: KPIAPI?) {
+        super.init()
+        self.kpiManager = kpiManager
+        registerAppStateObservers()
+    }
+
+    private static func makeKPIManager() -> KPIAPI? {
         do {
             let provider: KPIClientStateProvider = Client.environment == .staging ? PIAKPIStagingClientStateProvider() : PIAKPIClientStateProvider()
-            kpiManager = try KPIBuilder()
+            return try KPIBuilder()
                 .setFlushEventMode(.perBatch)
                 .setKPIClientStateProvider(provider)
                 .setEventTimeRoundGranularity(.hours)
@@ -84,8 +132,11 @@ public final class ServiceQualityManager: NSObject {
                 .build()
         } catch {
             log.error("KPI manager build failed: \(error)")
+            return nil
         }
+    }
 
+    private func registerAppStateObservers() {
         NotificationCenter.default.addObserver(
             self,
             selector: #selector(appChangedState(with:)),
@@ -96,7 +147,6 @@ public final class ServiceQualityManager: NSObject {
             selector: #selector(appChangedState(with:)),
             name: UIApplication.didBecomeActiveNotification,
             object: nil)
-
     }
 
     deinit {
@@ -219,6 +269,103 @@ public final class ServiceQualityManager: NSObject {
         }
     }
 
+    // MARK: IAP processing events
+
+    /// A new IAP transaction starts processing on the KapeClientSDK path.
+    public func iapProcessingPurchaseEvent(origin: KPIIapOrigin) {
+        submitIapEvent(.iapProcessingPurchase, properties: baseIapProperties(origin: origin))
+    }
+
+    /// The purchase succeeded verification using KapeClientSDK.
+    public func iapProcessingSuccessEvent(origin: KPIIapOrigin, retryCount: Int = 0) {
+        var properties = baseIapProperties(origin: origin)
+        properties[KPIIapPropertyKey.retryCount.rawValue] = String(retryCount)
+        submitIapEvent(.iapProcessingSuccess, properties: properties)
+    }
+
+    /// A verification attempt failed and is being retried on the KapeClientSDK path.
+    /// NOTE: not wired yet — client-side retry logic is delivered by the separate
+    /// retry/XV ticket, which will call this with the incremented `retryCount`.
+    public func iapProcessingRetryEvent(origin: KPIIapOrigin, error: Error, retryCount: Int) {
+        var properties = baseIapProperties(origin: origin)
+        properties[KPIIapPropertyKey.retryCount.rawValue] = String(retryCount)
+        properties[KPIIapPropertyKey.error.rawValue] = iapErrorCode(for: error)
+        submitIapEvent(.iapProcessingRetry, properties: properties)
+    }
+
+    /// The purchase failed verification using KapeClientSDK.
+    public func iapProcessingFailureEvent(origin: KPIIapOrigin, error: Error, retryCount: Int? = nil) {
+        var properties = baseIapProperties(origin: origin)
+        properties[KPIIapPropertyKey.error.rawValue] = iapErrorCode(for: error)
+        if let retryCount {
+            properties[KPIIapPropertyKey.retryCount.rawValue] = String(retryCount)
+        }
+        properties.merge(iapErrorDetails(for: error)) { _, new in new }
+        submitIapEvent(.iapProcessingFailure, properties: properties)
+    }
+
+    private func baseIapProperties(origin: KPIIapOrigin) -> [String: String] {
+        [
+            KPIIapPropertyKey.origin.rawValue: origin.rawValue,
+            KPIIapPropertyKey.environment.rawValue: Client.environment.rawValue
+        ]
+    }
+
+    /// Short, stable identifier for the primary `error` property.
+    private func iapErrorCode(for error: Error) -> String {
+        switch error {
+        case let clientError as ClientError:
+            switch clientError {
+            case .unknown(let code, _): return "unknown_\(code)"
+            case .throttled(let retryAfter): return "throttled_\(retryAfter)"
+            case .libraryError: return "library_error"
+            default: return String(describing: clientError)
+            }
+        default:
+            let nsError = error as NSError
+            return "\(nsError.domain)_\(nsError.code)"
+        }
+    }
+
+    /// Optional diagnostic detail for failure events (`internalError`, `rawError`).
+    /// `csi` has no client-side source and is intentionally omitted.
+    private func iapErrorDetails(for error: Error) -> [String: String] {
+        var details: [String: String] = [
+            KPIIapPropertyKey.rawError.rawValue: String(describing: error)
+        ]
+        if let clientError = error as? ClientError {
+            switch clientError {
+            case .unknown(_, let message), .libraryError(let message):
+                if let message {
+                    details[KPIIapPropertyKey.internalError.rawValue] = message
+                }
+            default:
+                break
+            }
+        }
+        return details
+    }
+
+    private func submitIapEvent(_ event: KPIIapEvent, properties: [String: String]) {
+        guard Client.preferences.shareServiceQualityData, let kpiManager else { return }
+
+        let clientEvent = KPIClientEvent(
+            eventCountry: nil,
+            eventName: event.rawValue,
+            eventProperties: properties,
+            eventInstant: Date()
+        )
+
+        Task {
+            do {
+                try await kpiManager.submit(event: clientEvent)
+                log.debug("KPI event submitted \(clientEvent)")
+            } catch {
+                log.error("\(error)")
+            }
+        }
+    }
+
     public func availableData(completion: @escaping (([String]) -> Void)) {
         guard let kpiManager else {
             completion([])
diff --git a/LocalPackages/PIALibrary/Tests/PIALibraryTests/Mocks/MockKPIAPI.swift b/LocalPackages/PIALibrary/Tests/PIALibraryTests/Mocks/MockKPIAPI.swift
@@ -0,0 +1,60 @@
+//
+//  MockKPIAPI.swift
+//  PIALibraryTests
+//
+//  Copyright © 2026 Private Internet Access, Inc.
+//
+//  This file is part of the Private Internet Access iOS Client.
+//
+//  The Private Internet Access iOS Client is free software: you can redistribute it and/or
+//  modify it under the terms of the GNU General Public License as published by the Free
+//  Software Foundation, either version 3 of the License, or (at your option) any later version.
+//
+//  The Private Internet Access iOS Client is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+//  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+//  details.
+//
+//  You should have received a copy of the GNU General Public License along with the Private
+//  Internet Access iOS Client.  If not, see <https://www.gnu.org/licenses/>.
+//
+
+import Foundation
+import PIAKPI
+import XCTest
+
+/// Test double for `KPIAPI` that captures submitted events. Events are submitted from a
+/// detached `Task` inside `ServiceQualityManager`, so tests fulfill `submitExpectation`
+/// to await the submission before asserting.
+final class MockKPIAPI: KPIAPI, @unchecked Sendable {
+
+    private let lock = NSLock()
+    private var storedEvents: [KPIClientEvent] = []
+    private var submitExpectation: XCTestExpectation?
+
+    var submittedEvents: [KPIClientEvent] {
+        lock.lock()
+        defer { lock.unlock() }
+        return storedEvents
+    }
+
+    /// Fulfilled once for every `submit(event:)` call.
+    func expectSubmission(_ expectation: XCTestExpectation) {
+        lock.lock()
+        defer { lock.unlock() }
+        submitExpectation = expectation
+    }
+
+    func start() async {}
+    func stop() async throws {}
+    func flush() async throws {}
+    func recentEvents() async -> [String] { [] }
+
+    func submit(event: KPIClientEvent) async throws {
+        lock.lock()
+        storedEvents.append(event)
+        let expectation = submitExpectation
+        lock.unlock()
+        expectation?.fulfill()
+    }
+}
diff --git a/LocalPackages/PIALibrary/Tests/PIALibraryTests/ServiceQualityManagerTests.swift b/LocalPackages/PIALibrary/Tests/PIALibraryTests/ServiceQualityManagerTests.swift
