Shopper Insights - Added Presentment Details Object and Update Presented Events

Braintree.xcodeproj/project.pbxproj

@@ -7,6 +7,11 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
+		04AA31182D07974D0043ACAB /* BTButtonType.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04AA31172D0797460043ACAB /* BTButtonType.swift */; };
+		04AA311A2D0797570043ACAB /* BTPresentmentDetails.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04AA31192D0797510043ACAB /* BTPresentmentDetails.swift */; };
+		04AA311E2D0798FC0043ACAB /* BTPageType.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04AA311D2D0798F70043ACAB /* BTPageType.swift */; };
+		04AA31202D07990E0043ACAB /* BTButtonOrder.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04AA311F2D07990A0043ACAB /* BTButtonOrder.swift */; };
+		04B001102D0CF46E00C0060D /* BTExperimentType.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04B0010F2D0CF46900C0060D /* BTExperimentType.swift */; };
 		0917F6E42A27BDC700ACED2E /* BTVenmoLineItem.swift in Sources */ = {isa = PBXBuildFile; fileRef = 096C6B2529CCDCEB00912863 /* BTVenmoLineItem.swift */; };
 		09357DCB2A2FBEC10096D449 /* BTVenmoLineItem_Tests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 09357DCA2A2FBEC10096D449 /* BTVenmoLineItem_Tests.swift */; };
 		1FEB89E614CB6BF0B9858EE4 /* Pods_Tests_IntegrationTests.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 85BD589D380436A0C9D1DEC1 /* Pods_Tests_IntegrationTests.framework */; };
@@ -729,6 +734,11 @@
 		035A59D91EA5DE97002960C8 /* BTLocalPaymentClient_UnitTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = BTLocalPaymentClient_UnitTests.swift; sourceTree = "<group>"; };
 		039A8BD91F9E993500D607E7 /* BTAmericanExpressRewardsBalance_Tests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTAmericanExpressRewardsBalance_Tests.swift; sourceTree = "<group>"; };
 		03F921C1200EBB200076CD80 /* BTThreeDSecurePostalAddress_Tests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTThreeDSecurePostalAddress_Tests.swift; sourceTree = "<group>"; };
+		04AA31172D0797460043ACAB /* BTButtonType.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTButtonType.swift; sourceTree = "<group>"; };
+		04AA31192D0797510043ACAB /* BTPresentmentDetails.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTPresentmentDetails.swift; sourceTree = "<group>"; };
+		04AA311D2D0798F70043ACAB /* BTPageType.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTPageType.swift; sourceTree = "<group>"; };
+		04AA311F2D07990A0043ACAB /* BTButtonOrder.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTButtonOrder.swift; sourceTree = "<group>"; };
+		04B0010F2D0CF46900C0060D /* BTExperimentType.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTExperimentType.swift; sourceTree = "<group>"; };
 		09357DCA2A2FBEC10096D449 /* BTVenmoLineItem_Tests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTVenmoLineItem_Tests.swift; sourceTree = "<group>"; };
 		096C6B2529CCDCEB00912863 /* BTVenmoLineItem.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BTVenmoLineItem.swift; sourceTree = "<group>"; };
 		162174E1192D9220008DC35D /* CoreGraphics.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreGraphics.framework; path = System/Library/Frameworks/CoreGraphics.framework; sourceTree = SDKROOT; };
@@ -1494,8 +1504,13 @@
 		804698292B27C4D70090878E /* BraintreeShopperInsights */ = {
 			isa = PBXGroup;
 			children = (
+				04AA311F2D07990A0043ACAB /* BTButtonOrder.swift */,
+				04AA31172D0797460043ACAB /* BTButtonType.swift */,
 				62EA90482B63071800DD79BC /* BTEligiblePaymentMethods.swift */,
 				800ED7822B4F5B66007D8A30 /* BTEligiblePaymentsRequest.swift */,
+				04B0010F2D0CF46900C0060D /* BTExperimentType.swift */,
+				04AA311D2D0798F70043ACAB /* BTPageType.swift */,
+				04AA31192D0797510043ACAB /* BTPresentmentDetails.swift */,
 				8037BFAF2B2CCC130017072C /* BTShopperInsightsAnalytics.swift */,
 				8064F38E2B1E492F0059C4CB /* BTShopperInsightsClient.swift */,
 				624B27F62B6AE0C2000AC08A /* BTShopperInsightsError.swift */,
@@ -3364,11 +3379,16 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				04AA311E2D0798FC0043ACAB /* BTPageType.swift in Sources */,
 				804698382B27C53B0090878E /* BTShopperInsightsRequest.swift in Sources */,
+				04B001102D0CF46E00C0060D /* BTExperimentType.swift in Sources */,
+				04AA31182D07974D0043ACAB /* BTButtonType.swift in Sources */,
 				624B27F72B6AE0C2000AC08A /* BTShopperInsightsError.swift in Sources */,
 				804698372B27C5390090878E /* BTShopperInsightsClient.swift in Sources */,
 				800ED7832B4F5B66007D8A30 /* BTEligiblePaymentsRequest.swift in Sources */,
 				8037BFB02B2CCC130017072C /* BTShopperInsightsAnalytics.swift in Sources */,
+				04AA311A2D0797570043ACAB /* BTPresentmentDetails.swift in Sources */,
+				04AA31202D07990E0043ACAB /* BTButtonOrder.swift in Sources */,
 				62EA90492B63071800DD79BC /* BTEligiblePaymentMethods.swift in Sources */,
 				804698392B27C53E0090878E /* BTShopperInsightsResult.swift in Sources */,
 			);

CHANGELOG.md

@@ -1,15 +1,22 @@
 # Braintree iOS SDK Release Notes
 
+## unreleased
+* BraintreeShopperInsights (BETA)
+  * Add `shopperSessionID` to `BTShopperInsightsClient` initializer
+  * Add `isPayPalAppInstalled()` and/or `isVenmoAppInstalled()`
+  * Replace `sendPayPalPresentedEvent()` and `sendPayPalPresentedEvent()` with `sendPresentedEvent(for:presentmentDetails:)`
+  * Add values to the following parameters to `presentmentDetails`:
+    * `experimentType`
+    * `pageType`
+    * `buttonOrder`
+  * Send `url` in `event_params` for App Switch events to PayPal's analytics service (FPTI)
+
 ## 6.25.0 (2024-12-11)
 * BraintreePayPal
   * Add `BTPayPalRequest.userPhoneNumber` optional property
   * Add `shopperSessionID` to `BTPayPalCheckoutRequest` and `BTPayPalVaultRequest`
 * BraintreeVenmo
   * Send `url` in `event_params` for App Switch events to PayPal's analytics service (FPTI)
-* BraintreeShopperInsights (BETA)
-  * Add `shopperSessionID` to `BTShopperInsightsClient` initializer
-  * Add `isPayPalAppInstalled()` and/or `isVenmoAppInstalled()`
-  * Send `url` in `event_params` for App Switch events to PayPal's analytics service (FPTI)
 * BraintreeVenmo
   * Send `url` in `event_params` for App Switch events to PayPal's analytics service (FPTI)
   * Add `BTVenmoClient(apiClient:universalLink:)` to use Universal Links when redirecting back from the Venmo flow

Demo/Application/Features/ShopperInsightsViewController.swift

@@ -104,16 +104,13 @@ class ShopperInsightsViewController: PaymentButtonBaseViewController {
     }
 
     @objc func payPalVaultButtonTapped(_ button: UIButton) {
-        let sampleExperiment =
-            """
-            [
-                { "experimentName" : "payment ready conversion experiment" },
-                { "experimentID" : "a1b2c3" },
-                { "treatmentName" : "treatment group 1" }
-            ]
-            """
-        let paymentMethods = ["Apple Pay", "Card", "PayPal"]
-        shopperInsightsClient.sendPayPalPresentedEvent(paymentMethodsDisplayed: paymentMethods, experiment: sampleExperiment)
+        let presentmentDetails = BTPresentmentDetails(
+            buttonOrder: .first,
+            experimentType: .control,
+            pageType: .about
+        )
+
+        shopperInsightsClient.sendPresentedEvent(for: .payPal, presentmentDetails: presentmentDetails)
         progressBlock("Tapped PayPal Vault")
         shopperInsightsClient.sendPayPalSelectedEvent()
 
@@ -131,7 +128,12 @@ class ShopperInsightsViewController: PaymentButtonBaseViewController {
     }
 
     @objc func venmoButtonTapped(_ button: UIButton) {
-        shopperInsightsClient.sendVenmoPresentedEvent()
+        let presentmentDetails = BTPresentmentDetails(
+            buttonOrder: .second,
+            experimentType: .control,
+            pageType: .about
+        )
+        shopperInsightsClient.sendPresentedEvent(for: .venmo, presentmentDetails: presentmentDetails)
         progressBlock("Tapped Venmo")
         shopperInsightsClient.sendVenmoSelectedEvent()
 

Sources/BraintreeCore/Analytics/FPTIBatchData.swift

@@ -30,6 +30,10 @@ struct FPTIBatchData: Codable {
     struct Event: Codable {
 
         let appSwitchURL: String?
+        /// The order or ranking in which payment buttons appear.
+        let buttonOrder: String?
+        /// The type of button displayed or presented
+        let buttonType: String?
         /// UTC millisecond timestamp when a networking task started establishing a TCP connection. See [Apple's docs](https://developer.apple.com/documentation/foundation/urlsessiontasktransactionmetrics#3162615).
         /// `nil` if a persistent connection is used.
         let connectionStartTime: Int?
@@ -39,6 +43,8 @@ struct FPTIBatchData: Codable {
         let endTime: Int?
         let errorDescription: String?
         let eventName: String
+        /// The experiment type that is sent to analytics to help improve the Shopper Insights feature experience.
+        let experimentType: String?
         /// True if the `BTConfiguration` was retrieved from local cache after `tokenize()` call.
         /// False if the `BTConfiguration` was fetched remotely after `tokenize()` call.
         let isConfigFromCache: Bool?
@@ -48,6 +54,8 @@ struct FPTIBatchData: Codable {
         let linkType: String?
         /// The experiment details associated with a shopper insights flow
         let merchantExperiment: String?
+        /// The type of page where the payment button is displayed or where an event occured.
+        let pageType: String?
         /// The list of payment methods displayed, in the same order in which they are rendered on the page, associated with the `BTShopperInsights` flow.
         let paymentMethodsDisplayed: String?
         /// Used for linking events from the client to server side request
@@ -65,33 +73,41 @@ struct FPTIBatchData: Codable {
 
         init(
             appSwitchURL: URL? = nil,
+            buttonOrder: String? = nil,
+            buttonType: String? = nil,
             connectionStartTime: Int? = nil,
             correlationID: String? = nil,
             endpoint: String? = nil,
             endTime: Int? = nil,
             errorDescription: String? = nil,
             eventName: String,
+            experimentType: String? = nil,
             isConfigFromCache: Bool? = nil,
             isVaultRequest: Bool? = nil,
             linkType: String? = nil,
             merchantExperiment: String? = nil,
+            pageType: String? = nil,
             paymentMethodsDisplayed: String? = nil,
             payPalContextID: String? = nil,
             requestStartTime: Int? = nil,
             shopperSessionID: String? = nil,
             startTime: Int? = nil
         ) {
             self.appSwitchURL = appSwitchURL?.absoluteString
+            self.buttonOrder = buttonOrder
+            self.buttonType = buttonType
             self.connectionStartTime = connectionStartTime
             self.correlationID = correlationID
             self.endpoint = endpoint
             self.endTime = endTime
             self.errorDescription = errorDescription
             self.eventName = eventName
+            self.experimentType = experimentType
             self.isConfigFromCache = isConfigFromCache
             self.isVaultRequest = isVaultRequest
             self.linkType = linkType
             self.merchantExperiment = merchantExperiment
+            self.pageType = pageType
             self.paymentMethodsDisplayed = paymentMethodsDisplayed
             self.payPalContextID = payPalContextID
             self.requestStartTime = requestStartTime
@@ -101,14 +117,18 @@ struct FPTIBatchData: Codable {
 
         enum CodingKeys: String, CodingKey {
             case appSwitchURL = "url"
+            case buttonOrder = "button_position"
+            case buttonType = "button_type"
             case connectionStartTime = "connect_start_time"
             case correlationID = "correlation_id"
             case errorDescription = "error_desc"
             case eventName = "event_name"
+            case experimentType = "experiment_type"
             case isConfigFromCache = "config_cached"
             case isVaultRequest = "is_vault"
             case linkType = "link_type"
             case merchantExperiment = "experiment"
+            case pageType = "page_type"
             case paymentMethodsDisplayed = "payment_methods_displayed"
             case payPalContextID = "paypal_context_id"
             case requestStartTime = "request_start_time"

Sources/BraintreeCore/BTAPIClient.swift

@@ -303,27 +303,33 @@ import Foundation
     @_documentation(visibility: private)
     public func sendAnalyticsEvent(
         _ eventName: String,
+        appSwitchURL: URL? = nil,
+        buttonOrder: String? = nil,
+        buttonType: String? = nil,
         correlationID: String? = nil,
         errorDescription: String? = nil,
         merchantExperiment: String? = nil,
         isConfigFromCache: Bool? = nil,
         isVaultRequest: Bool? = nil,
         linkType: LinkType? = nil,
+        pageType: String? = nil,
         paymentMethodsDisplayed: String? = nil,
         payPalContextID: String? = nil,
-        appSwitchURL: URL? = nil,
         shopperSessionID: String? = nil
     ) {
         analyticsService.sendAnalyticsEvent(
             FPTIBatchData.Event(
                 appSwitchURL: appSwitchURL,
+                buttonOrder: buttonOrder,
+                buttonType: buttonType,
                 correlationID: correlationID,
                 errorDescription: errorDescription,
                 eventName: eventName,
                 isConfigFromCache: isConfigFromCache,
                 isVaultRequest: isVaultRequest,
                 linkType: linkType?.rawValue,
                 merchantExperiment: merchantExperiment,
+                pageType: pageType,
                 paymentMethodsDisplayed: paymentMethodsDisplayed,
                 payPalContextID: payPalContextID,
                 shopperSessionID: shopperSessionID

Sources/BraintreeShopperInsights/BTButtonOrder.swift

@@ -0,0 +1,33 @@
+import Foundation
+
+/// The order or ranking in which payment buttons appear.
+/// - Warning: This module is in beta. It's public API may change or be removed in future releases.
+public enum BTButtonOrder: String {
+
+    /// 0
+    case first = "1"
+
+    /// 1
+    case second = "2"
+
+    /// 2
+    case third = "3"
+
+    /// 3
+    case fourth = "4"
+
+    /// 4
+    case fifth = "5"
+
+    /// 5
+    case sixth = "6"
+
+    /// 6
+    case seventh = "7"
+
+    /// 7
+    case eighth = "8"
+
+    /// 8
+    case other = "other"
+}

Sources/BraintreeShopperInsights/BTButtonType.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// The type of button displayed or presented
+/// Warning: This module is in beta. It's public API may change or be removed in future releases.
+public enum BTButtonType: String {
+
+    /// PayPal button
+    case payPal = "PayPal"
+
+    /// Venmo button
+    case venmo = "Venmo"
+
+    /// All button types other than PayPal or Venmo
+    case other = "Other"
+}

Sources/BraintreeShopperInsights/BTExperimentType.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+/// The experiment type that is sent to analytics to help improve the Shopper Insights feature experience.
+/// - Warning: This module is in beta. It's public API may change or be removed in future releases.
+public enum BTExperimentType: String {
+
+    /// The test experiment
+    case test
+
+    /// The control experiment
+    case control
+
+    public var formattedExperiment: String {
+        """
+            [
+                { "exp_name" : "PaymentReady" }
+                { "treatment_name" : "\(self.rawValue)" }
+            ]
+        """
+    }
+}

Sources/BraintreeShopperInsights/BTPageType.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+/// The type of page where the payment button is displayed or where an event occured.
+/// - Warning: This module is in beta. It's public API may change or be removed in future releases.
+public enum BTPageType: String {
+
+    /// A home page is the primary landing page that a visitor will view when they navigate to a website.
+    case homepage = "homepage"
+
+    /// An About page is a section on a website that provides information about a company, organization, or individual.
+    case about = "about"
+
+    /// A contact page is a page on a website for visitors to contact the organization or individual providing the website.
+    case contact = "contact"
+
+    /// An intermediary step that users pass through on their way to a product-listing page that doesn't provide a complete
+    /// list of products but may showcase a few products and provide links to product subcategories.
+    case productCategory = "product_category"
+
+    /// A product detail page (PDP) is a web page that outlines everything customers and buyers need to know about a
+    /// particular product.
+    case productDetails = "product_details"
+
+    /// The page a user sees after entering a search query.
+    case search = "search"
+
+    /// A cart is a digital shopping cart that allows buyers to inspect and organize items they plan to buy.
+    case cart = "cart"
+
+    /// A checkout page is the page related to payment and shipping/billing details on an eCommerce store.
+    case checkout = "checkout"
+
+    /// An order review page gives the buyer an overview of the goods or services that they have selected and summarizes
+    /// the order that they are about to place.
+    case orderReview = "order_review"
+
+    /// The order confirmation page summarizes an order after checkout completes.
+    case orderConfirmation = "order_confirmation"
+
+    /// Popup cart displayed after “add to cart” click.
+    case miniCart = "mini_cart"
+
+    /// Any other page available on a merchant’s site.
+    case other = "other"
+}

Sources/BraintreeShopperInsights/BTPresentmentDetails.swift

@@ -0,0 +1,30 @@
+import Foundation
+
+public class BTPresentmentDetails {
+
+    /// The order or ranking in which payment buttons appear.
+    var buttonOrder: BTButtonOrder
+
+    /// The experiment type that is sent to analytics to help improve the Shopper Insights feature experience.
+    var experimentType: BTExperimentType
+
+    /// The type of page where the event occurred.
+    var pageType: BTPageType
+
+    /// Detailed information, including button order, experiment type, and page type about the payment button that
+    /// is sent to analytics to help improve the Shopper Insights feature experience.
+    /// - Warning: This class is in beta. It's public API may change or be removed in future releases.
+    /// - Parameters:
+    ///    - buttonOrder: The order or ranking in which payment buttons appear.
+    ///    - experimentType: The experiment type that is sent to analytics to help improve the Shopper Insights feature experience.
+    ///    - pageType: The type of page where the payment button is displayed or where an event occured.
+    public init(
+        buttonOrder: BTButtonOrder,
+        experimentType: BTExperimentType,
+        pageType: BTPageType
+    ) {
+        self.buttonOrder = buttonOrder
+        self.experimentType = experimentType
+        self.pageType = pageType
+    }
+}