@encorekit/web-sdk 0.1.1 → 0.1.7

package/examples/ios-webview/README.md

@@ -0,0 +1,416 @@
+# Encore iOS WebView Integration Example
+
+This directory contains example Swift code for integrating Encore into your iOS app using WKWebView instead of the native Swift SDK.
+
+## Overview
+
+This approach is ideal for:
+- Apps that can't or don't want to add new SDK dependencies
+- Quick integration without modifying build configuration
+- Cross-platform teams familiar with web technologies
+- Apps already using web views for other features
+
+## Files
+
+- **`EncoreWebViewBridge.swift`** - Complete bridge implementation (copy this to your project)
+- **`ExampleViewController.swift`** - Example usage in a view controller
+- **`README.md`** - This file
+
+## Quick Start
+
+### 1. Add the Bridge to Your Project
+
+Copy `EncoreWebViewBridge.swift` to your Xcode project. No additional dependencies required!
+
+### 2. Basic Integration
+
+```swift
+import UIKit
+import WebKit
+
+class YourViewController: UIViewController {
+    private var encoreBridge: EncoreWebViewBridge!
+    private var webView: WKWebView!
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        // 1. Create configuration
+        let config = EncoreConfiguration(
+            apiKey: "your_api_key_here",
+            environment: "production",
+            userId: "user_123"
+        )
+        
+        // 2. Initialize bridge
+        encoreBridge = EncoreWebViewBridge(configuration: config)
+        encoreBridge.delegate = self
+        
+        // 3. Setup webView
+        webView = encoreBridge.setupWebView()
+        view.addSubview(webView)
+        
+        // 4. Configure constraints (webView should fill screen)
+        webView.translatesAutoresizingMaskIntoConstraints = false
+        NSLayoutConstraint.activate([
+            webView.topAnchor.constraint(equalTo: view.topAnchor),
+            webView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            webView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            webView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
+        ])
+        
+        // 5. Load embed
+        encoreBridge.loadEmbed()
+    }
+}
+```
+
+### 3. Implement Delegate Methods
+
+```swift
+extension YourViewController: EncoreWebViewBridgeDelegate {
+    func encoreBridgeDidBecomeReady(_ bridge: EncoreWebViewBridge) {
+        print("Encore is ready")
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, 
+                     didInitializeWithUserId userId: String) {
+        print("Initialized with user: \(userId)")
+        // Now you can present offers
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, 
+                     didGrantEntitlement entitlement: EncoreEntitlement) {
+        // User completed an offer!
+        print("Granted: \(entitlement.type)")
+        
+        // TODO: Apply the entitlement in your app
+        // - Unlock premium features
+        // - Apply discount
+        // - Update subscription status
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, 
+                     userDeclinedWithReason reason: EncoreDeclineReason) {
+        print("User declined: \(reason)")
+        // Handle decline (optional)
+    }
+    
+    func encoreBridge(_ bridge: EncoreWebViewBridge, 
+                     didEncounterError error: EncoreError) {
+        print("Error: \(error.message)")
+        // Handle error (optional)
+    }
+}
+```
+
+### 4. Present an Offer
+
+```swift
+// When you want to show an offer (e.g., during cancellation flow)
+encoreBridge.presentOffer()
+```
+
+## Use Cases
+
+### Subscription Cancellation Flow
+
+```swift
+func handleCancelSubscription() {
+    // Present retention offer before cancelling
+    encoreBridge.presentOffer()
+}
+
+// In delegate:
+func encoreBridge(_ bridge: EncoreWebViewBridge, 
+                 didGrantEntitlement entitlement: EncoreEntitlement) {
+    // User completed offer - keep subscription active!
+    keepSubscriptionActive()
+    showSuccessMessage()
+}
+
+func encoreBridge(_ bridge: EncoreWebViewBridge, 
+                 userDeclinedWithReason reason: EncoreDeclineReason) {
+    // User still wants to cancel - proceed
+    proceedWithCancellation()
+}
+```
+
+### Feature Paywall
+
+```swift
+func showPremiumFeature() {
+    guard userHasPremiumAccess() else {
+        // Show Encore offer before paywall
+        encoreBridge.presentOffer()
+        return
+    }
+    
+    // Show premium feature
+}
+```
+
+### Dynamic User Attributes
+
+```swift
+func updateUserContext() {
+    let attributes = [
+        "subscriptionTier": user.tier,
+        "monthsSubscribed": "\(user.subscriptionMonths)",
+        "lastActiveDate": ISO8601DateFormatter().string(from: Date())
+    ]
+    
+    encoreBridge.setUserAttributes(attributes)
+}
+```
+
+## Configuration Options
+
+### EncoreConfiguration
+
+```swift
+public struct EncoreConfiguration {
+    public let apiKey: String              // Required: Your Encore API key
+    public let environment: String         // "production" or "localhost"
+    public let userId: String?             // Optional: User identifier
+    public let attributes: [String: String]? // Optional: User attributes
+    public let logLevel: String?           // Optional: "debug" or "none"
+    public let uiConfiguration: [String: String]? // Optional: UI text customization
+}
+```
+
+### User Attributes
+
+You can pass user attributes for better targeting:
+
+```swift
+let attributes = [
+    // Identity
+    "email": "user@example.com",
+    "firstName": "Jane",
+    "lastName": "Doe",
+    
+    // Subscription
+    "subscriptionTier": "free",
+    "monthsSubscribed": "6",
+    "billingCycle": "monthly",
+    
+    // Demographics
+    "postalCode": "10001",
+    "city": "New York",
+    "state": "NY",
+    "countryCode": "US",
+    
+    // Engagement
+    "lastActiveDate": "2024-01-15",
+    "totalSessions": "150"
+]
+```
+
+### UI Configuration
+
+Customize the offer modal text:
+
+```swift
+let uiConfig = [
+    "titleText": "Special Offer for You!",
+    "subtitleText": "Complete offers to unlock premium features",
+    "offerDescriptionText": "Complete this offer:",
+    "applyCreditsButtonText": "Claim My Offer"
+]
+
+let config = EncoreConfiguration(
+    apiKey: "your_key",
+    environment: "production",
+    uiConfiguration: uiConfig
+)
+```
+
+## API Reference
+
+### EncoreWebViewBridge
+
+#### Methods
+
+```swift
+// Setup and load
+func setupWebView() -> WKWebView
+func loadEmbed()
+
+// Configuration
+func configure(_ configuration: EncoreConfiguration)
+
+// Offers
+func presentOffer()
+
+// User management
+func identify(userId: String, attributes: [String: String]? = nil)
+func setUserAttributes(_ attributes: [String: String])
+func reset()
+
+// State
+func getState()
+```
+
+#### Properties
+
+```swift
+weak var delegate: EncoreWebViewBridgeDelegate?
+var isReady: Bool { get }
+var isInitialized: Bool { get }
+var currentUserId: String? { get }
+```
+
+### Delegate Protocol
+
+```swift
+protocol EncoreWebViewBridgeDelegate: AnyObject {
+    func encoreBridgeDidBecomeReady(_ bridge: EncoreWebViewBridge)
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didInitializeWithUserId userId: String)
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didGrantEntitlement entitlement: EncoreEntitlement)
+    func encoreBridge(_ bridge: EncoreWebViewBridge, userDeclinedWithReason reason: EncoreDeclineReason)
+    func encoreBridge(_ bridge: EncoreWebViewBridge, didEncounterError error: EncoreError)
+}
+```
+
+## Important Notes
+
+### WebView Positioning
+
+The WebView should fill the entire screen (or your desired container) even though it's transparent. This ensures the offer modal can display properly when shown.
+
+```swift
+// Correct: Full screen
+webView.frame = view.bounds
+
+// Or with constraints
+NSLayoutConstraint.activate([
+    webView.topAnchor.constraint(equalTo: view.topAnchor),
+    webView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+    webView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+    webView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
+])
+```
+
+### Entitlement Validation
+
+**Important:** Always validate entitlements on your server, not in the iOS app. The client-side entitlement data is for UX purposes only.
+
+```swift
+// ❌ Don't do this
+func unlockPremium() {
+    if entitlement.type == "freeTrial" {
+        // Never trust client-side validation
+    }
+}
+
+// ✅ Do this instead
+func unlockPremium() {
+    // Call your server to validate
+    api.validateEntitlement(userId) { result in
+        if result.isValid {
+            // Server confirmed - safe to unlock
+        }
+    }
+}
+```
+
+### Thread Safety
+
+All delegate methods are called on the main thread, so you can safely update UI directly.
+
+### Memory Management
+
+The bridge holds a weak reference to its delegate to prevent retain cycles. Make sure your view controller maintains a strong reference to the bridge.
+
+```swift
+// ✅ Correct
+class MyVC: UIViewController {
+    private var encoreBridge: EncoreWebViewBridge! // Strong reference
+}
+
+// ❌ Wrong - bridge will be deallocated
+func setupBridge() {
+    let bridge = EncoreWebViewBridge() // Local variable
+    bridge.delegate = self
+    // bridge is deallocated when function returns
+}
+```
+
+### State Management & Page Reloads
+
+The bridge automatically handles page reloads and navigation events:
+
+- **On navigation start** (`didStartProvisionalNavigation`): State is reset (`isReady = false`, `isInitialized = false`)
+- **On navigation finish** (`didFinish`): Configuration is automatically re-applied
+- **Message queue**: Cleared on navigation to prevent stale messages
+
+This means:
+- ✅ **Page refreshes work correctly** - SDK is automatically re-initialized
+- ✅ **No stale state** - Each page load starts fresh
+- ✅ **No race conditions** - Configuration waits for JS to be ready
+
+```swift
+// You don't need to do anything special for page reloads
+// The bridge handles it automatically:
+
+// Initial load
+encoreBridge.loadEmbed()  // → SDK initializes
+
+// User refreshes page (swipe down, etc.)
+// → Bridge detects navigation start
+// → State is reset
+// → Page finishes loading
+// → Configuration is automatically re-applied
+// → SDK initializes again
+```
+
+**Important:** Don't rely on `isInitialized` staying `true` across navigations. If you need to track state across page loads, maintain it separately in your view controller.
+
+## Troubleshooting
+
+### Offers not showing
+
+1. Check that `didInitializeWithUserId` was called
+2. Verify your API key is correct
+3. Check network connectivity
+4. Look for error messages in delegate methods
+5. Try enabling debug mode: add `?debug=true` to embed URL
+
+### WebView blank/not loading
+
+1. Ensure Info.plist has network permissions
+2. Check the embed URL is accessible
+3. Verify WKWebView configuration allows JavaScript
+4. Check console for JavaScript errors
+
+### Messages not received
+
+1. Verify message handler name is "encore"
+2. Check that delegate is set
+3. Ensure bridge has strong reference
+4. Try adding print statements in delegate methods
+
+### Build errors
+
+1. Make sure you're targeting iOS 13.0 or later
+2. Import WebKit framework
+3. Check that EncoreWebViewBridge.swift is added to target
+
+## Requirements
+
+- iOS 13.0+
+- Xcode 12.0+
+- Swift 5.0+
+- Network connectivity
+
+## Support
+
+For issues or questions:
+- Email: admin@encorekit.com
+- Documentation: https://docs.encorekit.com
+
+## License
+
+This example code is provided as-is for integration purposes.
+

package/examples/ios-webview/SimpleEncoreView.swift

@@ -0,0 +1,94 @@
+//
+//  SimpleEncoreView.swift
+//  Encore iOS Simple Integration
+//
+//  Dead simple SwiftUI wrapper for Encore HTML tag
+//
+
+import SwiftUI
+import WebKit
+
+/// Simple SwiftUI view that displays Encore embed
+///
+/// Usage:
+/// ```swift
+/// EncoreWebView(
+///     apiKey: "your_api_key",
+///     userId: "user_123",
+///     attributes: ["email": "user@example.com"]
+/// )
+/// ```
+public struct EncoreWebView: View {
+    let apiKey: String
+    let userId: String
+    let environment: String
+    let attributes: [String: String]
+    let debug: Bool
+    
+    public init(
+        apiKey: String,
+        userId: String,
+        environment: String = "production",
+        attributes: [String: String] = [:],
+        debug: Bool = false
+    ) {
+        self.apiKey = apiKey
+        self.userId = userId
+        self.environment = environment
+        self.attributes = attributes
+        self.debug = debug
+    }
+    
+    public var body: some View {
+        WebViewRepresentable(url: buildURL())
+            .ignoresSafeArea()
+    }
+    
+    private func buildURL() -> URL {
+        EncoreURL.build(
+            apiKey: apiKey,
+            userId: userId,
+            environment: environment,
+            attributes: attributes,
+            debug: debug
+        )!
+    }
+}
+
+// MARK: - Private WebView Wrapper
+
+private struct WebViewRepresentable: UIViewRepresentable {
+    let url: URL
+    
+    func makeUIView(context: Context) -> WKWebView {
+        let webView = WKWebView()
+        webView.backgroundColor = .systemBackground
+        webView.isOpaque = true
+        webView.load(URLRequest(url: url))
+        return webView
+    }
+    
+    func updateUIView(_ webView: WKWebView, context: Context) {
+        // No updates needed
+    }
+}
+
+// MARK: - Preview
+
+#if DEBUG
+struct EncoreWebView_Previews: PreviewProvider {
+    static var previews: some View {
+        EncoreWebView(
+            apiKey: "test_api_key",
+            userId: "preview_user",
+            environment: "localhost",
+            attributes: [
+                "email": "preview@example.com",
+                "subscriptionTier": "free"
+            ],
+            debug: true
+        )
+    }
+}
+#endif
+

package/examples/ios-webview/SimpleExample.swift

@@ -0,0 +1,131 @@
+//
+//  SimpleExample.swift
+//  Encore iOS Simple Integration
+//
+//  The simplest possible integration - just open a URL in WKWebView
+//
+
+import UIKit
+import WebKit
+
+class SimpleEncoreViewController: UIViewController {
+    
+    private var webView: WKWebView!
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        // 1. Create WKWebView
+        webView = WKWebView(frame: view.bounds)
+        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        webView.backgroundColor = .clear
+        webView.isOpaque = false
+        view.addSubview(webView)
+        
+        // 2. Build Encore URL
+        let url = EncoreURL.build(
+            apiKey: "your_api_key_here",
+            userId: "user_123",
+            environment: "production",
+            attributes: [
+                "email": "user@example.com",
+                "subscriptionTier": "free"
+            ]
+        )!
+        
+        // 3. Load it!
+        webView.load(URLRequest(url: url))
+        
+        // That's it! The embed will auto-initialize and show offers.
+    }
+}
+
+// MARK: - SwiftUI Version
+
+import SwiftUI
+
+struct SimpleEncoreView: View {
+    var body: some View {
+        EncoreWebView(
+            apiKey: "your_api_key_here",
+            userId: "user_123",
+            attributes: [
+                "email": "user@example.com",
+                "subscriptionTier": "free"
+            ]
+        )
+    }
+}
+
+struct EncoreWebView: UIViewRepresentable {
+    let apiKey: String
+    let userId: String?
+    let environment: String
+    let attributes: [String: String]?
+    
+    init(
+        apiKey: String,
+        userId: String? = nil,
+        environment: String = "production",
+        attributes: [String: String]? = nil
+    ) {
+        self.apiKey = apiKey
+        self.userId = userId
+        self.environment = environment
+        self.attributes = attributes
+    }
+    
+    func makeUIView(context: Context) -> WKWebView {
+        let webView = WKWebView()
+        webView.backgroundColor = .clear
+        webView.isOpaque = false
+        
+        if let url = EncoreURL.build(
+            apiKey: apiKey,
+            userId: userId,
+            environment: environment,
+            attributes: attributes
+        ) {
+            webView.load(URLRequest(url: url))
+        }
+        
+        return webView
+    }
+    
+    func updateUIView(_ webView: WKWebView, context: Context) {
+        // No updates needed
+    }
+}
+
+// MARK: - Usage Examples
+
+extension SimpleEncoreViewController {
+    
+    /// Example: Show in cancellation flow
+    static func showInCancellationFlow(from viewController: UIViewController) {
+        let encoreVC = SimpleEncoreViewController()
+        encoreVC.modalPresentationStyle = .fullScreen
+        viewController.present(encoreVC, animated: true)
+    }
+    
+    /// Example: Show as modal sheet
+    static func showAsSheet(from viewController: UIViewController) {
+        let encoreVC = SimpleEncoreViewController()
+        if let sheet = encoreVC.sheetPresentationController {
+            sheet.detents = [.large()]
+            sheet.prefersGrabberVisible = true
+        }
+        viewController.present(encoreVC, animated: true)
+    }
+    
+    /// Example: Embed in existing view
+    static func embedInView(_ containerView: UIView, parentVC: UIViewController) {
+        let encoreVC = SimpleEncoreViewController()
+        parentVC.addChild(encoreVC)
+        containerView.addSubview(encoreVC.view)
+        encoreVC.view.frame = containerView.bounds
+        encoreVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        encoreVC.didMove(toParent: parentVC)
+    }
+}
+