@encorekit/web-sdk 0.1.1 → 0.1.7

package/examples/ios-webview/EncoreWebViewBridge.swift

@@ -0,0 +1,426 @@
+//
+//  EncoreWebViewBridge.swift
+//  Encore iOS WebView Bridge
+//
+//  A Swift bridge for integrating Encore via WKWebView
+//  instead of the native iOS SDK.
+//
+
+import Foundation
+import WebKit
+
+/// Entitlement types that can be granted to users
+public enum EncoreEntitlementType: String, Codable {
+    case freeTrial = "free_trial"
+    case discount = "discount"
+    case credit = "credit"
+}
+
+/// Entitlement granted to a user
+public struct EncoreEntitlement: Codable {
+    public let type: String
+    public let value: Int?
+    public let unit: String?
+    
+    public init(type: String, value: Int? = nil, unit: String? = nil) {
+        self.type = type
+        self.value = value
+        self.unit = unit
+    }
+}
+
+/// Reason why an entitlement was not granted
+public enum EncoreDeclineReason: String {
+    case userClosedModal
+    case userClickedOutside
+    case userDeclinedLastOffer
+    case noOffersAvailable
+    case error
+    case unknown
+}
+
+/// Error from Encore SDK
+public struct EncoreError: Error, Codable {
+    public let code: String
+    public let message: String
+    public let context: String?
+    
+    public init(code: String, message: String, context: String? = nil) {
+        self.code = code
+        self.message = message
+        self.context = context
+    }
+}
+
+/// Delegate protocol for Encore events
+public protocol EncoreWebViewBridgeDelegate: AnyObject {
+    /// Called when the embed page is ready
+    func encoreBridgeDidBecomeReady(_ bridge: EncoreWebViewBridge)
+    
+    /// Called when SDK is initialized successfully
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didInitializeWithUserId userId: String)
+    
+    /// Called when an entitlement is granted
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didGrantEntitlement entitlement: EncoreEntitlement)
+    
+    /// Called when user declines an offer
+    func encoreBridge(_ bridge: EncoreWebViewBridge, userDeclinedWithReason reason: EncoreDeclineReason)
+    
+    /// Called when an error occurs
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didEncounterError error: EncoreError)
+}
+
+/// Configuration for Encore SDK
+public struct EncoreConfiguration {
+    public let apiKey: String
+    public let environment: String
+    public let userId: String?
+    public let attributes: [String: String]?
+    public let logLevel: String?
+    public let uiConfiguration: [String: String]?
+    
+    public init(
+        apiKey: String,
+        environment: String = "production",
+        userId: String? = nil,
+        attributes: [String: String]? = nil,
+        logLevel: String? = nil,
+        uiConfiguration: [String: String]? = nil
+    ) {
+        self.apiKey = apiKey
+        self.environment = environment
+        self.userId = userId
+        self.attributes = attributes
+        self.logLevel = logLevel
+        self.uiConfiguration = uiConfiguration
+    }
+}
+
+/// Bridge class for communicating with Encore Web SDK in WKWebView
+public class EncoreWebViewBridge: NSObject {
+    
+    // MARK: - Properties
+    
+    public weak var delegate: EncoreWebViewBridgeDelegate?
+    public private(set) var webView: WKWebView?
+    
+    /// Indicates if the JavaScript embed is ready to receive messages
+    /// Reset to false when navigation starts (page reload/navigation)
+    public private(set) var isReady = false
+    
+    /// Indicates if the Encore SDK has been initialized in JavaScript
+    /// Reset to false when navigation starts to handle page reloads properly
+    public private(set) var isInitialized = false
+    
+    public private(set) var currentUserId: String?
+    
+    private let embedURL: URL
+    private let configuration: EncoreConfiguration?
+    
+    /// Message queue for storing messages sent before the embed is ready
+    /// Cleared on each navigation to prevent stale messages from being sent
+    private var messageQueue: [[String: Any]] = []
+    
+    // MARK: - Initialization
+    
+    /// Initialize with a custom embed URL
+    /// - Parameters:
+    ///   - embedURL: The URL of the Encore embed page
+    ///   - configuration: Optional configuration to auto-initialize SDK
+    public init(embedURL: URL, configuration: EncoreConfiguration? = nil) {
+        self.embedURL = embedURL
+        self.configuration = configuration
+        super.init()
+    }
+    
+    /// Initialize with default Encore embed URL
+    /// - Parameter configuration: Optional configuration to auto-initialize SDK
+    public convenience init(configuration: EncoreConfiguration? = nil) {
+        // Default to production embed URL
+        let url = URL(string: "https://encorekit.com/embed/")!
+        self.init(embedURL: url, configuration: configuration)
+    }
+    
+    // MARK: - Setup
+    
+    /// Setup and configure the WKWebView
+    /// Call this method and add the returned webView to your view hierarchy
+    /// - Returns: Configured WKWebView instance
+    public func setupWebView() -> WKWebView {
+        let config = WKWebViewConfiguration()
+        
+        // Enable JavaScript
+        config.preferences.javaScriptEnabled = true
+        
+        // Add message handler for Encore messages
+        let contentController = WKUserContentController()
+        contentController.add(self, name: "encore")
+        config.userContentController = contentController
+        
+        // Create webView with transparent background
+        let webView = WKWebView(frame: .zero, configuration: config)
+        webView.backgroundColor = .clear
+        webView.isOpaque = false
+        webView.scrollView.isScrollEnabled = false
+        webView.navigationDelegate = self
+        
+        self.webView = webView
+        
+        return webView
+    }
+    
+    /// Load the Encore embed page
+    public func loadEmbed() {
+        guard let webView = webView else {
+            print("[Encore] Error: WebView not setup. Call setupWebView() first.")
+            return
+        }
+        
+        var urlComponents = URLComponents(url: embedURL, resolvingAgainstBaseURL: true)
+        
+        // If configuration provided, add as URL parameters for quick initialization
+        if let config = configuration {
+            var queryItems: [URLQueryItem] = [
+                URLQueryItem(name: "apiKey", value: config.apiKey),
+                URLQueryItem(name: "environment", value: config.environment)
+            ]
+            
+            if let userId = config.userId {
+                queryItems.append(URLQueryItem(name: "userId", value: userId))
+            }
+            
+            urlComponents?.queryItems = queryItems
+        }
+        
+        guard let finalURL = urlComponents?.url else {
+            print("[Encore] Error: Invalid embed URL")
+            return
+        }
+        
+        let request = URLRequest(url: finalURL)
+        webView.load(request)
+    }
+    
+    // MARK: - Public Methods
+    
+    /// Configure the Encore SDK
+    /// - Parameter configuration: Configuration object
+    public func configure(_ configuration: EncoreConfiguration) {
+        var payload: [String: Any] = [
+            "apiKey": configuration.apiKey,
+            "environment": configuration.environment
+        ]
+        
+        if let userId = configuration.userId {
+            payload["userId"] = userId
+        }
+        
+        if let attributes = configuration.attributes {
+            payload["attributes"] = attributes
+        }
+        
+        if let logLevel = configuration.logLevel {
+            payload["logLevel"] = logLevel
+        }
+        
+        if let uiConfiguration = configuration.uiConfiguration {
+            payload["uiConfiguration"] = uiConfiguration
+        }
+        
+        sendMessage(type: "configure", payload: payload)
+    }
+    
+    /// Present an offer to the user
+    public func presentOffer() {
+        sendMessage(type: "presentOffer", payload: [:])
+    }
+    
+    /// Identify a user
+    /// - Parameters:
+    ///   - userId: User identifier
+    ///   - attributes: Optional user attributes
+    public func identify(userId: String, attributes: [String: String]? = nil) {
+        var payload: [String: Any] = ["userId": userId]
+        if let attributes = attributes {
+            payload["attributes"] = attributes
+        }
+        sendMessage(type: "identify", payload: payload)
+    }
+    
+    /// Set user attributes
+    /// - Parameter attributes: User attributes dictionary
+    public func setUserAttributes(_ attributes: [String: String]) {
+        sendMessage(type: "setUserAttributes", payload: ["attributes": attributes])
+    }
+    
+    /// Reset the SDK state
+    /// This sends a reset message to the JS SDK and clears the local state.
+    /// Note: Page reloads automatically reset state in didStartProvisionalNavigation
+    public func reset() {
+        sendMessage(type: "reset", payload: [:])
+        isInitialized = false
+        currentUserId = nil
+    }
+    
+    /// Get current SDK state
+    public func getState() {
+        sendMessage(type: "getState", payload: [:])
+    }
+    
+    // MARK: - Private Methods
+    
+    private func sendMessage(type: String, payload: [String: Any]) {
+        let message: [String: Any] = [
+            "type": type,
+            "payload": payload
+        ]
+        
+        if isReady {
+            postMessageToWebView(message)
+        } else {
+            // Queue messages until webview is ready
+            messageQueue.append(message)
+        }
+    }
+    
+    private func postMessageToWebView(_ message: [String: Any]) {
+        guard let webView = webView else { return }
+        
+        do {
+            let jsonData = try JSONSerialization.data(withJSONObject: message)
+            let jsonString = String(data: jsonData, encoding: .utf8) ?? "{}"
+            
+            let script = """
+            window.postMessage(\(jsonString), '*');
+            """
+            
+            webView.evaluateJavaScript(script) { _, error in
+                if let error = error {
+                    print("[Encore] Error posting message: \(error)")
+                }
+            }
+        } catch {
+            print("[Encore] Error serializing message: \(error)")
+        }
+    }
+    
+    private func flushMessageQueue() {
+        while !messageQueue.isEmpty {
+            let message = messageQueue.removeFirst()
+            postMessageToWebView(message)
+        }
+    }
+    
+    private func handleMessage(_ body: Any) {
+        guard let dict = body as? [String: Any],
+              let type = dict["type"] as? String else {
+            return
+        }
+        
+        let payload = dict["payload"] as? [String: Any] ?? [:]
+        
+        print("[Encore] Received message: \(type)")
+        
+        switch type {
+        case "encore:ready":
+            isReady = true
+            flushMessageQueue()
+            delegate?.encoreBridgeDidBecomeReady(self)
+            
+        case "encore:initialized":
+            isInitialized = true
+            if let userId = payload["userId"] as? String {
+                currentUserId = userId
+                delegate?.encoreBridge(self, didInitializeWithUserId: userId)
+            }
+            
+        case "encore:entitlementGranted":
+            if let entitlementData = payload["entitlement"] as? [String: Any],
+               let jsonData = try? JSONSerialization.data(withJSONObject: entitlementData),
+               let entitlement = try? JSONDecoder().decode(EncoreEntitlement.self, from: jsonData) {
+                delegate?.encoreBridge(self, didGrantEntitlement: entitlement)
+            }
+            
+        case "encore:userDeclined":
+            if let reasonString = payload["reason"] as? String,
+               let reason = EncoreDeclineReason(rawValue: reasonString) {
+                delegate?.encoreBridge(self, userDeclinedWithReason: reason)
+            } else {
+                delegate?.encoreBridge(self, userDeclinedWithReason: .unknown)
+            }
+            
+        case "encore:error":
+            if let jsonData = try? JSONSerialization.data(withJSONObject: payload),
+               let error = try? JSONDecoder().decode(EncoreError.self, from: jsonData) {
+                delegate?.encoreBridge(self, didEncounterError: error)
+            }
+            
+        case "encore:state":
+            // Handle state response if needed
+            print("[Encore] Current state: \(payload)")
+            
+        default:
+            print("[Encore] Unknown message type: \(type)")
+        }
+    }
+}
+
+// MARK: - WKScriptMessageHandler
+
+extension EncoreWebViewBridge: WKScriptMessageHandler {
+    public func userContentController(
+        _ userContentController: WKUserContentController,
+        didReceive message: WKScriptMessage
+    ) {
+        guard message.name == "encore" else { return }
+        handleMessage(message.body)
+    }
+}
+
+// MARK: - WKNavigationDelegate
+
+extension EncoreWebViewBridge: WKNavigationDelegate {
+    public func webView(
+        _ webView: WKWebView,
+        didStartProvisionalNavigation navigation: WKNavigation!
+    ) {
+        print("[Encore] WebView started loading")
+        
+        // Reset state when navigation starts - the JS environment will be reloaded
+        // This ensures we re-initialize even if the user refreshes or navigates
+        isReady = false
+        isInitialized = false
+        messageQueue.removeAll()
+        
+        print("[Encore] State reset for new navigation")
+    }
+    
+    public func webView(
+        _ webView: WKWebView,
+        didFinish navigation: WKNavigation!
+    ) {
+        print("[Encore] WebView finished loading")
+        
+        // If we have initial configuration and haven't initialized yet, do it now
+        // Note: isInitialized will be false after didStartProvisionalNavigation reset,
+        // so this will properly re-initialize on page reloads
+        if !isInitialized, let config = configuration {
+            print("[Encore] Auto-configuring SDK with stored configuration")
+            configure(config)
+        }
+    }
+    
+    public func webView(
+        _ webView: WKWebView,
+        didFail navigation: WKNavigation!,
+        withError error: Error
+    ) {
+        print("[Encore] WebView navigation failed: \(error.localizedDescription)")
+        
+        // Reset state on navigation failure as well
+        isReady = false
+        isInitialized = false
+        messageQueue.removeAll()
+    }
+}
+

package/examples/ios-webview/ExampleViewController.swift

@@ -0,0 +1,233 @@
+//
+//  ExampleViewController.swift
+//  Encore iOS WebView Example
+//
+//  Example implementation showing how to integrate Encore via WKWebView
+//
+
+import UIKit
+import WebKit
+
+class ExampleViewController: UIViewController {
+    
+    // MARK: - Properties
+    
+    private var encoreBridge: EncoreWebViewBridge!
+    private var webView: WKWebView!
+    
+    // UI Elements
+    private let statusLabel: UILabel = {
+        let label = UILabel()
+        label.textAlignment = .center
+        label.numberOfLines = 0
+        label.font = .systemFont(ofSize: 14)
+        label.textColor = .secondaryLabel
+        label.text = "Initializing Encore..."
+        return label
+    }()
+    
+    private let presentOfferButton: UIButton = {
+        let button = UIButton(type: .system)
+        button.setTitle("Present Offer", for: .normal)
+        button.titleLabel?.font = .systemFont(ofSize: 18, weight: .semibold)
+        button.backgroundColor = .systemBlue
+        button.setTitleColor(.white, for: .normal)
+        button.layer.cornerRadius = 12
+        button.isEnabled = false
+        return button
+    }()
+    
+    private let resultLabel: UILabel = {
+        let label = UILabel()
+        label.textAlignment = .center
+        label.numberOfLines = 0
+        label.font = .systemFont(ofSize: 16, weight: .medium)
+        label.textColor = .label
+        label.text = ""
+        return label
+    }()
+    
+    // MARK: - Lifecycle
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        title = "Encore WebView Example"
+        view.backgroundColor = .systemBackground
+        
+        setupEncoreBridge()
+        setupUI()
+    }
+    
+    // MARK: - Setup
+    
+    private func setupEncoreBridge() {
+        // Create configuration
+        let config = EncoreConfiguration(
+            apiKey: "your_api_key_here", // Replace with your actual API key
+            environment: "production", // or "localhost" for testing
+            userId: "user_123", // Optional: your user's ID
+            attributes: [ // Optional: user attributes for targeting
+                "email": "user@example.com",
+                "subscriptionTier": "free"
+            ]
+        )
+        
+        // Initialize bridge
+        encoreBridge = EncoreWebViewBridge(configuration: config)
+        encoreBridge.delegate = self
+        
+        // Setup webView
+        webView = encoreBridge.setupWebView()
+        
+        // Add webView to view hierarchy (invisible)
+        webView.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(webView)
+        
+        NSLayoutConstraint.activate([
+            // Make webView fill the entire screen
+            webView.topAnchor.constraint(equalTo: view.topAnchor),
+            webView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            webView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            webView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
+        ])
+        
+        // Load the embed page
+        encoreBridge.loadEmbed()
+    }
+    
+    private func setupUI() {
+        // Add UI elements on top of webView
+        let stackView = UIStackView(arrangedSubviews: [
+            statusLabel,
+            presentOfferButton,
+            resultLabel
+        ])
+        stackView.axis = .vertical
+        stackView.spacing = 20
+        stackView.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(stackView)
+        
+        NSLayoutConstraint.activate([
+            stackView.centerYAnchor.constraint(equalTo: view.centerYAnchor),
+            stackView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 40),
+            stackView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -40),
+            
+            presentOfferButton.heightAnchor.constraint(equalToConstant: 50)
+        ])
+        
+        presentOfferButton.addTarget(self, action: #selector(presentOfferTapped), for: .touchUpInside)
+    }
+    
+    // MARK: - Actions
+    
+    @objc private func presentOfferTapped() {
+        resultLabel.text = ""
+        encoreBridge.presentOffer()
+    }
+}
+
+// MARK: - EncoreWebViewBridgeDelegate
+
+extension ExampleViewController: EncoreWebViewBridgeDelegate {
+    
+    func encoreBridgeDidBecomeReady(_ bridge: EncoreWebViewBridge) {
+        print("✅ Encore bridge is ready")
+        statusLabel.text = "Encore is ready"
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didInitializeWithUserId userId: String) {
+        print("✅ Encore initialized with user ID: \(userId)")
+        statusLabel.text = "Initialized (User: \(userId))"
+        presentOfferButton.isEnabled = true
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didGrantEntitlement entitlement: EncoreEntitlement) {
+        print("🎉 Entitlement granted: \(entitlement)")
+        
+        // Handle the entitlement in your app
+        // For example, unlock premium features, apply discount, etc.
+        
+        let message = "Entitlement Granted!\nType: \(entitlement.type)"
+        resultLabel.text = message
+        resultLabel.textColor = .systemGreen
+        
+        // Show success alert
+        let alert = UIAlertController(
+            title: "Success!",
+            message: "You've earned a \(entitlement.type) entitlement!",
+            preferredStyle: .alert
+        )
+        alert.addAction(UIAlertAction(title: "OK", style: .default))
+        present(alert, animated: true)
+        
+        // TODO: Implement your app's logic to apply the entitlement
+        // Examples:
+        // - Update user's subscription status
+        // - Apply discount to checkout
+        // - Grant access to premium content
+        // - Update UI to reflect new entitlement
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, userDeclinedWithReason reason: EncoreDeclineReason) {
+        print("ℹ️ User declined offer: \(reason.rawValue)")
+        
+        let message = "Offer declined: \(reason.rawValue)"
+        resultLabel.text = message
+        resultLabel.textColor = .systemOrange
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didEncounterError error: EncoreError) {
+        print("❌ Encore error: \(error.code) - \(error.message)")
+        
+        let message = "Error: \(error.message)"
+        resultLabel.text = message
+        resultLabel.textColor = .systemRed
+        
+        // Show error alert
+        let alert = UIAlertController(
+            title: "Error",
+            message: error.message,
+            preferredStyle: .alert
+        )
+        alert.addAction(UIAlertAction(title: "OK", style: .default))
+        present(alert, animated: true)
+    }
+}
+
+// MARK: - Advanced Example: Cancellation Flow Integration
+
+extension ExampleViewController {
+    
+    /// Example: Present Encore offer during subscription cancellation
+    func handleSubscriptionCancellation() {
+        // User is trying to cancel their subscription
+        
+        // First, present the Encore offer as a retention tool
+        encoreBridge.presentOffer()
+        
+        // The delegate methods will be called:
+        // - If user completes offer: didGrantEntitlement() → Keep subscription active
+        // - If user declines: userDeclinedWithReason() → Proceed with cancellation
+    }
+    
+    /// Example: Check if user has active entitlements on app launch
+    func checkEntitlementsOnLaunch() {
+        // Note: Entitlement validation should be done server-side
+        // This is just for demonstration of the bridge API
+        
+        encoreBridge.getState()
+        // Response will be logged in console
+    }
+    
+    /// Example: Update user attributes dynamically
+    func updateUserData() {
+        let newAttributes = [
+            "subscriptionTier": "premium",
+            "lastActiveDate": ISO8601DateFormatter().string(from: Date())
+        ]
+        
+        encoreBridge.setUserAttributes(newAttributes)
+    }
+}
+