@encorekit/web-sdk 2.0.4 → 2.0.6

package/examples/ios-webview/README.md

@@ -1,396 +1,117 @@
-# Encore iOS WebView Integration Example
+# Encore on iOS without the native SDK
 
-This directory contains example Swift code for integrating Encore into your iOS app using WKWebView instead of the native Swift SDK.
+Open one URL in a `WKWebView`. Encore hosts the offer page and the query string
+configures it. There is nothing to install and nothing to implement.
 
-## 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
+If you want native entitlement callbacks, StoreKit handling and offline
+behaviour, use the [Swift SDK](https://github.com/EncoreKit/swift) instead. This
+directory is for apps that want the smallest possible integration.
 
 ## 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
+| File | Purpose |
+|------|---------|
+| `EncoreURLBuilder.swift` | Builds the URL. Copy this one. |
+| `SimpleEncoreView.swift` | SwiftUI view wrapping the webview. |
+| `SimpleExample.swift` | UIKit view controller and presentation patterns. |
 
-### 1. Add the Bridge to Your Project
+## Setup
 
-Copy `EncoreWebViewBridge.swift` to your Xcode project. No additional dependencies required!
+Copy `EncoreURLBuilder.swift` into your Xcode project, plus
+`SimpleEncoreView.swift` if you want the SwiftUI wrapper. No dependencies.
 
-### 2. Basic Integration
+## UIKit
 
 ```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()
-}
+let webView = WKWebView(frame: view.bounds)
+view.addSubview(webView)
 
-func encoreBridge(_ bridge: EncoreWebViewBridge, 
-                 userDeclinedWithReason reason: EncoreDeclineReason) {
-    // User still wants to cancel - proceed
-    proceedWithCancellation()
+if let url = EncoreURL.build(
+    apiKey: "pk_live_...",
+    userId: currentUser.id,
+    attributes: ["subscriptionTier": currentUser.tier]
+) {
+    webView.load(URLRequest(url: url))
 }
 ```
 
-### Feature Paywall
+## SwiftUI
 
 ```swift
-func showPremiumFeature() {
-    guard userHasPremiumAccess() else {
-        // Show Encore offer before paywall
-        encoreBridge.presentOffer()
-        return
+struct MyView: View {
+    @State private var showOffer = false
+
+    var body: some View {
+        Button("Show offer") { showOffer = true }
+            .sheet(isPresented: $showOffer) {
+                EncoreWebView(
+                    apiKey: "pk_live_...",
+                    userId: currentUser.id,
+                    attributes: ["subscriptionTier": currentUser.tier]
+                )
+            }
     }
-    
-    // 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"
 }
 ```
 
-### User Attributes
-
-You can pass user attributes for better targeting:
+## Parameters
 
-```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"
-]
-```
+`apiKey` and `userId` are required. The page shows an error state without them.
 
-## API Reference
+Optional: `environment` (`production`, `development`, `staging`, `localhost`),
+`useCase` (`rewardUsers` by default, or `reduceChurn`), `placement`,
+`autoPresentOffer`, `headline`, `subheadline`.
 
-### EncoreWebViewBridge
+Targeting attributes are flat query parameters. Accepted keys are
+`countryCode`, `postalCode`, `city`, `state`, `language`, `subscriptionTier`,
+`monthsSubscribed`, `billingCycle`, `lastPaymentAmount`, `lastActiveDate`,
+`totalSessions`, plus anything you pass through `custom:`.
 
-#### Methods
+`email`, `firstName`, `lastName`, `phoneNumber`, `dateOfBirth`, `gender`,
+`latitude` and `longitude` are refused. A URL is written to webview history and
+to hosting access logs, so it is the wrong channel for a direct identifier. Ask
+Encore for a short lived signed token if you need to target on one.
 
-```swift
-// Setup and load
-func setupWebView() -> WKWebView
-func loadEmbed()
+`EncoreURL.build` drops them before they reach the URL rather than relying on
+the page to ignore them, because by then the value has already been written into
+history and into a log. It also caps `custom.` keys at 20 and truncates values
+at 256 characters, matching the page. Anything dropped is printed in `DEBUG`
+builds so targeting does not quietly underperform.
 
-// Configuration
-func configure(_ configuration: EncoreConfiguration)
+See the **[Hosted Offer Page guide](https://docs.encorekit.com/publishers/web/guides/hosted-offer-page)** for the full integration
+walkthrough, or [the hosted page reference](../../embed/README.md) for the
+query string contract on its own.
 
-// Offers
-func presentOffer()
+## Knowing when a user earned something
 
-// User management
-func identify(userId: String, attributes: [String: String]? = nil)
-func setUserAttributes(_ attributes: [String: String])
-func reset()
+The page does not call your app back. Ask Encore from your backend:
 
-// State
-func getState()
 ```
-
-#### Properties
-
-```swift
-weak var delegate: EncoreWebViewBridgeDelegate?
-var isReady: Bool { get }
-var isInitialized: Bool { get }
-var currentUserId: String? { get }
+GET https://api.encorekit.com/encore/publisher/sdk/v1/entitlements/server?userId=<userId>
 ```
 
-### 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)
-}
-```
+authenticated with your API key plus an HMAC signature you compute with your
+API secret. The secret itself is never sent. Poll it when the webview is
+dismissed, or on your own schedule.
 
-## Important Notes
+## What to expect when a user claims
 
-### 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.
+Claiming navigates the whole webview to the advertiser rather than opening a
+second window. `window.open` returns null inside a `WKWebView` unless the host
+implements `WKUIDelegate.createWebViewWith`, so a top level navigation is the
+only handoff that works without cooperation from your app. Dismiss your sheet
+when the user is done and poll for the entitlement.
 
 ## 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
+**Blank page.** Check `apiKey` and `userId` are both present and that the key
+matches the environment you passed.
 
-This example code is provided as-is for integration purposes.
+**Targeting looks ignored.** Attributes go in as one parameter per key. A single
+JSON `attributes=` value is ignored, and refused keys are dropped.
 
+**No offers appear.** The campaign must be granted to your app and enabled.
+Granting alone is not enough.

package/examples/ios-webview/SimpleEncoreView.swift

@@ -1,57 +1,73 @@
 //
 //  SimpleEncoreView.swift
-//  Encore iOS Simple Integration
+//  Encore hosted offer page, SwiftUI wrapper
 //
-//  Dead simple SwiftUI wrapper for Encore HTML tag
+//  A SwiftUI view that loads the hosted offer page. Copy this file and
+//  `EncoreURLBuilder.swift` into your project.
 //
 
 import SwiftUI
 import WebKit
 
-/// Simple SwiftUI view that displays Encore embed
+/// Displays the Encore hosted offer page.
 ///
 /// Usage:
 /// ```swift
 /// EncoreWebView(
-///     apiKey: "your_api_key",
-///     userId: "user_123",
-///     attributes: ["email": "user@example.com"]
+///     apiKey: "pk_live_...",
+///     userId: currentUser.id,
+///     attributes: ["subscriptionTier": "premium"]
 /// )
 /// ```
+///
+/// There is no completion callback, and that is deliberate rather than
+/// missing. The page reports nothing back to the host app, so your backend
+/// learns about an entitlement by asking Encore for it:
+///
+///     GET https://api.encorekit.com/encore/publisher/sdk/v1/entitlements/server?userId=<userId>
+///
+/// authenticated with your API key plus an HMAC signature you compute with
+/// your API secret. The secret itself is never sent. Poll it when this view
+/// goes away.
 public struct EncoreWebView: View {
     let apiKey: String
     let userId: String
     let environment: String
+    let useCase: EncoreURL.UseCase?
     let attributes: [String: String]
-    let debug: Bool
-    
+
     public init(
         apiKey: String,
         userId: String,
         environment: String = "production",
-        attributes: [String: String] = [:],
-        debug: Bool = false
+        useCase: EncoreURL.UseCase? = nil,
+        attributes: [String: String] = [:]
     ) {
         self.apiKey = apiKey
         self.userId = userId
         self.environment = environment
+        self.useCase = useCase
         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
-        )!
+        Group {
+            if let url = EncoreURL.build(
+                apiKey: apiKey,
+                userId: userId,
+                environment: environment,
+                useCase: useCase,
+                attributes: attributes
+            ) {
+                WebViewRepresentable(url: url)
+            } else {
+                // Unreachable in practice: this view always builds against
+                // the hosted page's own base, which it does not expose. Showing
+                // nothing still beats trapping inside a publisher's app.
+                Color.clear
+            }
+        }
+        .ignoresSafeArea()
     }
 }
 
@@ -59,7 +75,7 @@ public struct EncoreWebView: View {
 
 private struct WebViewRepresentable: UIViewRepresentable {
     let url: URL
-    
+
     func makeUIView(context: Context) -> WKWebView {
         let webView = WKWebView()
         webView.backgroundColor = .systemBackground
@@ -67,10 +83,10 @@ private struct WebViewRepresentable: UIViewRepresentable {
         webView.load(URLRequest(url: url))
         return webView
     }
-    
-    func updateUIView(_ webView: WKWebView, context: Context) {
-        // No updates needed
-    }
+
+    // Loading once in makeUIView is the whole lifecycle. Reloading here would
+    // fire on every SwiftUI update and restart the offer mid presentation.
+    func updateUIView(_ webView: WKWebView, context: Context) {}
 }
 
 // MARK: - Preview
@@ -79,16 +95,13 @@ private struct WebViewRepresentable: UIViewRepresentable {
 struct EncoreWebView_Previews: PreviewProvider {
     static var previews: some View {
         EncoreWebView(
-            apiKey: "test_api_key",
+            apiKey: "pk_test_example",
             userId: "preview_user",
-            environment: "localhost",
             attributes: [
-                "email": "preview@example.com",
-                "subscriptionTier": "free"
-            ],
-            debug: true
+                "subscriptionTier": "free",
+                "countryCode": "US",
+            ]
         )
     }
 }
 #endif
-