✨ Add support for custom components in experiences

appcues · Nov 6, 2024 · 9223b99 · 9223b99
1 parent 60f0fd5
commit 9223b99
Show file tree

Hide file tree

Showing 15 changed files with 286 additions and 7 deletions.
diff --git a/Sources/AppcuesKit/Appcues.swift b/Sources/AppcuesKit/Appcues.swift
@@ -21,6 +21,9 @@ public class Appcues: NSObject {
     @available(iOS 13.0, *)
     public static var elementTargeting: AppcuesElementTargeting = UIKitElementTargeting()
 
+    @available(iOS 13.0, *)
+    internal static var customComponentRegistry = CustomComponentRegistry()
+
     let container = DIContainer()
     let config: Appcues.Config
 
@@ -118,6 +121,17 @@ public class Appcues: NSObject {
         PushAutoConfig.configureAutomatically()
     }
 
+    /// Register a view controller that can be rendered in an `Experience`.
+    /// - Parameters:
+    ///   - identifier: View name
+    ///   - type: View controller type
+    public static func registerCustomComponent(identifier: String, type: AppcuesCustomComponentViewController.Type) {
+        // NOTE: this can't be @objc because the AppcuesCustomComponentView protocol inherits from UIView
+        guard #available(iOS 13.0, *) else { return }
+
+        customComponentRegistry.registerCustomComponent(identifier: identifier, type: type)
+    }
+
     /// Get the current version of the Appcues SDK.
     /// - Returns: Current version of the Appcues SDK.
     @objc(sdkVersion)

diff --git a/Sources/AppcuesKit/Data/Models/Experience/ExperienceComponent.swift b/Sources/AppcuesKit/Data/Models/Experience/ExperienceComponent.swift
@@ -27,6 +27,7 @@ internal indirect enum ExperienceComponent {
     case embed(EmbedModel)
     case optionSelect(OptionSelectModel)
     case textInput(TextInputModel)
+    case customComponent(CustomComponentModel)
 
     subscript<T>(dynamicMember keyPath: KeyPath<ComponentModel, T>) -> T {
         switch self {
@@ -39,6 +40,7 @@ internal indirect enum ExperienceComponent {
         case .embed(let model): return model[keyPath: keyPath]
         case .optionSelect(let model): return model[keyPath: keyPath]
         case .textInput(let model): return model[keyPath: keyPath]
+        case .customComponent(let model): return model[keyPath: keyPath]
         }
     }
 }
@@ -80,6 +82,8 @@ extension ExperienceComponent: Decodable {
             self = .optionSelect(try modelContainer.decode(OptionSelectModel.self))
         case "textInput":
             self = .textInput(try modelContainer.decode(TextInputModel.self))
+        case "customComponent":
+            self = .customComponent(try modelContainer.decode(CustomComponentModel.self))
         default:
             let context = DecodingError.Context(codingPath: container.codingPath, debugDescription: "unknown type '\(type)'")
             throw DecodingError.valueNotFound(Self.self, context)
@@ -279,6 +283,18 @@ extension ExperienceComponent {
         var textDescription: String? { label.textDescription }
     }
 
+    struct CustomComponentModel: ComponentModel {
+        let id: UUID
+
+        let identifier: String
+
+        let configDecoder: PluginDecoder
+
+        let style: Style?
+
+        var textDescription: String? { nil }
+    }
+
     struct SpacerModel: ComponentModel, Decodable {
         let id: UUID
         let spacing: Double?
@@ -360,3 +376,29 @@ extension ExperienceComponent.Style {
         let intrinsicSize: ExperienceComponent.IntrinsicSize?
     }
 }
+
+extension ExperienceComponent.CustomComponentModel: Decodable {
+    private enum CodingKeys: CodingKey {
+        case id, identifier, style, config
+    }
+
+    private struct CustomComponentDecoder: PluginDecoder {
+        private let container: KeyedDecodingContainer<CodingKeys>
+
+        init(_ container: KeyedDecodingContainer<CodingKeys>) {
+            self.container = container
+        }
+
+        func decode<T: Decodable>(_ type: T.Type) -> T? {
+            try? container.decode(T.self, forKey: .config)
+        }
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decode(UUID.self, forKey: .id)
+        identifier = try container.decode(String.self, forKey: .identifier)
+        configDecoder = CustomComponentDecoder(container)
+        style = try container.decodeIfPresent(ExperienceComponent.Style.self, forKey: .style)
+    }
+}
diff --git a/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesCloseAction.swift b/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesCloseAction.swift
@@ -30,6 +30,12 @@ internal class AppcuesCloseAction: AppcuesExperienceAction {
         markComplete = config?.markComplete ?? false
     }
 
+    init(appcues: Appcues?, renderContext: RenderContext, markComplete: Bool) {
+        self.appcues = appcues
+        self.renderContext = renderContext
+        self.markComplete = markComplete
+    }
+
     func execute(completion: @escaping ActionRegistry.Completion) {
         guard let appcues = appcues else { return completion() }
 

diff --git a/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesContinueAction.swift b/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesContinueAction.swift
@@ -40,6 +40,12 @@ internal class AppcuesContinueAction: AppcuesExperienceAction {
         }
     }
 
+    init(appcues: Appcues?, renderContext: RenderContext, stepReference: StepReference) {
+        self.appcues = appcues
+        self.renderContext = renderContext
+        self.stepReference = stepReference
+    }
+
     func execute(completion: @escaping ActionRegistry.Completion) {
         guard let appcues = appcues else { return completion() }
 

diff --git a/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesTrackAction.swift b/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesTrackAction.swift
@@ -30,6 +30,12 @@ internal class AppcuesTrackAction: AppcuesExperienceAction {
         self.attributes = config.attributes
     }
 
+    init(appcues: Appcues?, eventName: String, attributes: [String: Any]? = nil) {
+        self.appcues = appcues
+        self.eventName = eventName
+        self.attributes = attributes
+    }
+
     func execute(completion: ActionRegistry.Completion) {
         guard let appcues = appcues else { return completion() }
 

diff --git a/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesUpdateProfileAction.swift b/Sources/AppcuesKit/Presentation/Actions/Appcues/AppcuesUpdateProfileAction.swift
@@ -31,6 +31,11 @@ internal class AppcuesUpdateProfileAction: AppcuesExperienceAction {
         }
     }
 
+    init(appcues: Appcues?, properties: [String: Any]) {
+        self.appcues = appcues
+        self.properties = properties
+    }
+
     func execute(completion: ActionRegistry.Completion) {
         guard let appcues = appcues else { return completion() }
 

diff --git a/Sources/AppcuesKit/Presentation/CustomComponents/AppcuesCustomComponentViewController.swift b/Sources/AppcuesKit/Presentation/CustomComponents/AppcuesCustomComponentViewController.swift
@@ -0,0 +1,13 @@
+//
+//  AppcuesCustomComponentViewController.swift
+//  AppcuesKit
+//
+//  Created by Matt on 2024-10-22.
+//  Copyright © 2024 Appcues. All rights reserved.
+//
+
+import UIKit
+
+public protocol AppcuesCustomComponentViewController: UIViewController {
+    init?(configuration: AppcuesExperiencePluginConfiguration, actionController: AppcuesExperienceActions)
+}
diff --git a/Sources/AppcuesKit/Presentation/CustomComponents/AppcuesExperienceActions.swift b/Sources/AppcuesKit/Presentation/CustomComponents/AppcuesExperienceActions.swift
@@ -0,0 +1,66 @@
+//
+//  AppcuesExperienceActions.swift
+//  AppcuesKit
+//
+//  Created by Matt on 2024-10-22.
+//  Copyright © 2024 Appcues. All rights reserved.
+//
+
+import UIKit
+
+public class AppcuesExperienceActions {
+    private weak var appcues: Appcues?
+    private let renderContext: RenderContext
+    private let identifier: String
+
+    var actions: [Experience.Action]?
+
+    init(appcues: Appcues?, renderContext: RenderContext, identifier: String) {
+        self.appcues = appcues
+        self.renderContext = renderContext
+        self.identifier = identifier
+    }
+
+    @available(iOS 13.0, *)
+    public func triggerBlockActions() {
+        guard let actions = actions, let actionRegistry = appcues?.container.resolve(ActionRegistry.self) else { return }
+        actionRegistry.enqueue(
+            actionModels: actions,
+            level: .step,
+            renderContext: renderContext,
+            interactionType: "Button Tapped",
+            viewDescription: "Custom component \(identifier)"
+        )
+    }
+
+    @available(iOS 13.0, *)
+    public func track(name: String, properties: [String: Any]? = nil) {
+        enqueue(AppcuesTrackAction(appcues: appcues, eventName: name, attributes: properties))
+    }
+
+    @available(iOS 13.0, *)
+    public func nextStep() {
+        enqueue(AppcuesContinueAction(appcues: appcues, renderContext: renderContext, stepReference: .offset(1)))
+    }
+
+    @available(iOS 13.0, *)
+    public func previousStep() {
+        enqueue(AppcuesContinueAction(appcues: appcues, renderContext: renderContext, stepReference: .offset(-1)))
+    }
+
+    @available(iOS 13.0, *)
+    public func close(markComplete: Bool = false) {
+        enqueue(AppcuesCloseAction(appcues: appcues, renderContext: renderContext, markComplete: markComplete))
+    }
+
+    @available(iOS 13.0, *)
+    public func updateProfile(properties: [String: Any]) {
+        enqueue(AppcuesUpdateProfileAction(appcues: appcues, properties: properties))
+    }
+
+    @available(iOS 13.0, *)
+    private func enqueue(_ action: AppcuesExperienceAction) {
+        guard let actionRegistry = appcues?.container.resolve(ActionRegistry.self) else { return }
+        actionRegistry.enqueue(actionInstances: [action]) {}
+    }
+}
diff --git a/Sources/AppcuesKit/Presentation/Public/Plugins/AppcuesExperiencePluginConfiguration.swift b/Sources/AppcuesKit/Presentation/Public/Plugins/AppcuesExperiencePluginConfiguration.swift
@@ -10,7 +10,7 @@ import Foundation
 
 /// An object that decodes instances of a plugin configuration from an Experience JSON model.
 @objc
-internal class AppcuesExperiencePluginConfiguration: NSObject {
+public class AppcuesExperiencePluginConfiguration: NSObject {
 
     /// Context in which a plugin can be applied.
     @objc
@@ -43,7 +43,7 @@ internal class AppcuesExperiencePluginConfiguration: NSObject {
     /// Returns a value of the type you specify, decoded from a JSON object.
     /// - Parameter type: The type of the value to decode from the supplied plugin decoder.
     /// - Returns: A value of the specified type, if the decoder can parse the data.
-    internal func decode<T: Decodable>(_ type: T.Type) -> T? {
+    public func decode<T: Decodable>(_ type: T.Type) -> T? {
         return decoder.decode(type)
     }
 }
diff --git a/Sources/AppcuesKit/Presentation/Traits/Appcues/AppcuesBackgroundContentTrait.swift b/Sources/AppcuesKit/Presentation/Traits/Appcues/AppcuesBackgroundContentTrait.swift
@@ -18,6 +18,7 @@ internal class AppcuesBackgroundContentTrait: AppcuesStepDecoratingTrait, Appcue
 
     weak var metadataDelegate: AppcuesTraitMetadataDelegate?
 
+    private weak var appcues: Appcues?
     private let renderContext: RenderContext
 
     private let level: AppcuesExperiencePluginConfiguration.Level
@@ -26,6 +27,7 @@ internal class AppcuesBackgroundContentTrait: AppcuesStepDecoratingTrait, Appcue
     private weak var backgroundViewController: UIViewController?
 
     required init?(configuration: AppcuesExperiencePluginConfiguration) {
+        self.appcues = configuration.appcues
         self.renderContext = configuration.renderContext
 
         guard let config = configuration.decode(Config.self) else { return nil }
@@ -46,7 +48,7 @@ internal class AppcuesBackgroundContentTrait: AppcuesStepDecoratingTrait, Appcue
     func decorate(containerController: AppcuesExperienceContainerViewController) throws {
         guard level == .group || level == .experience else { return }
 
-        let emptyViewModel = ExperienceStepViewModel(renderContext: renderContext)
+        let emptyViewModel = ExperienceStepViewModel(renderContext: renderContext, appcues: appcues)
 
         backgroundViewController = applyBackground(with: emptyViewModel, parent: containerController)
     }

diff --git a/Sources/AppcuesKit/Presentation/Traits/TraitComposer.swift b/Sources/AppcuesKit/Presentation/Traits/TraitComposer.swift
@@ -16,12 +16,14 @@ internal protocol TraitComposing: AnyObject {
 @available(iOS 13.0, *)
 internal class TraitComposer: TraitComposing {
 
+    private weak var appcues: Appcues?
     private let traitRegistry: TraitRegistry
     private let actionRegistry: ActionRegistry
     private let config: Appcues.Config
     private let notificationCenter: NotificationCenter
 
     init(container: DIContainer) {
+        appcues = container.owner
         traitRegistry = container.resolve(TraitRegistry.self)
         actionRegistry = container.resolve(ActionRegistry.self)
         notificationCenter = container.resolve(NotificationCenter.self)
@@ -89,7 +91,8 @@ internal class TraitComposer: TraitComposing {
                 step: $0.step,
                 actionRegistry: actionRegistry,
                 renderContext: experience.renderContext,
-                config: config
+                config: config,
+                appcues: appcues
             )
             let stepViewController = ExperienceStepViewController(
                 viewModel: viewModel,

diff --git a/Sources/AppcuesKit/Presentation/UI/Components/AppcuesCustomComponent.swift b/Sources/AppcuesKit/Presentation/UI/Components/AppcuesCustomComponent.swift
@@ -0,0 +1,46 @@
+//
+//  AppcuesCustomComponent.swift
+//  AppcuesKit
+//
+//  Created by Matt on 2024-10-22.
+//  Copyright © 2024 Appcues. All rights reserved.
+//
+
+import SwiftUI
+
+@available(iOS 13.0, *)
+internal struct CustomComponentRepresentable: UIViewControllerRepresentable {
+    private let type: AppcuesCustomComponentViewController.Type
+    private let configuration: AppcuesExperiencePluginConfiguration
+    private let actionController: AppcuesExperienceActions
+
+    init?(on viewModel: ExperienceStepViewModel, for model: ExperienceComponent.CustomComponentModel) {
+        guard let customComponentData = viewModel.customComponent(for: model) else { return nil }
+        self.type = customComponentData.type
+        self.configuration = customComponentData.config
+        self.actionController = customComponentData.actionController
+    }
+
+    func makeUIViewController(context: Context) -> UIViewController {
+        let viewController = type.init(configuration: configuration, actionController: actionController)
+        return viewController ?? UIViewController()
+    }
+
+    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
+        // no-op
+    }
+}
+
+@available(iOS 13.0, *)
+internal struct AppcuesCustomComponent: View {
+    let model: ExperienceComponent.CustomComponentModel
+
+    @EnvironmentObject var viewModel: ExperienceStepViewModel
+
+    var body: some View {
+        let style = AppcuesStyle(from: model.style)
+
+        CustomComponentRepresentable(on: viewModel, for: model)
+            .applyAllAppcues(style)
+    }
+}
diff --git a/Sources/AppcuesKit/Presentation/UI/Components/ExperienceComponent+View.swift b/Sources/AppcuesKit/Presentation/UI/Components/ExperienceComponent+View.swift
@@ -30,6 +30,8 @@ extension ExperienceComponent {
             AnyView(AppcuesTextInput(model: model))
         case .optionSelect(let model):
             AnyView(AppcuesOptionSelect(model: model))
+        case .customComponent(let model):
+            AnyView(AppcuesCustomComponent(model: model))
         case .spacer(let model):
             AnyView(Spacer(minLength: CGFloat(model.spacing)))
         }