@encorekit/web-sdk 2.0.3 → 2.0.6

package/embed/README.md

@@ -1,409 +1,124 @@
-# Encore iOS WebView Embed
+# Encore Hosted Offer Page
 
-This directory contains the embeddable HTML page and JavaScript bridge that allows iOS apps to use Encore via WKWebView without installing the native Swift SDK.
+A publisher who cannot install an SDK opens one URL in a plain webview. Encore
+hosts the page, and the entire configuration surface is the query string.
 
-## 🎨 Mobile-Native UI
+There is no native bridge on any platform. Nothing is posted back to the host
+app, and no message handler needs registering. If you are looking for
+`webkit.messageHandlers`, a `WKScriptMessageHandler`, or an `encore:*` message
+protocol, they were removed: the bridge is what made the old embed iOS only,
+and dropping it is what made this page work everywhere.
 
-The embed now features an **iOS-native bottom sheet UI** that provides a mobile-optimized experience matching the iOS SDK's visual design:
+## The URL
 
-- ✅ **Bottom Sheet Design** - Slides up from bottom (not a centered popup)
-- ✅ **Native Animations** - Smooth 300ms cubic-bezier animations
-- ✅ **Swipe-to-Dismiss** - Pull down gesture to close
-- ✅ **Auto-Present** - Automatically shows offers on load
-- ✅ **iOS Styling** - SF Pro font, system blue, native shadows
-- ✅ **Safe Area Support** - Respects notches and home indicators
-- ✅ **Dark Mode** - Automatic dark mode support
-
-📖 **[Full Mobile UI Guide](./MOBILE-UI-GUIDE.md)** | 🧪 **[Testing Guide](../../encore-swift-sdk/EncoreSwiftUIDemo/MOBILE-UI-TESTING.md)**
-
-## Overview
-
-The embed solution consists of:
-
-- **`index.html`** - The main HTML page to be loaded in WKWebView
-- **`bridge.js`** - JavaScript-iOS communication bridge via `webkit.messageHandlers`
-- **`app.js`** - Application logic connecting Encore Web SDK to the bridge
-- **`styles.css`** - Base styling (transparent until offer shown)
-- **`mobile-styles.css`** - iOS-native bottom sheet components
-- **`mobile-overrides.css`** - Transforms Web SDK modal to mobile sheet
-
-## Architecture
-
-```
-iOS App (WKWebView)
-       ↕ (webkit.messageHandlers)
-  Bridge.js
-       ↕
-    App.js
-       ↕
-  Encore Web SDK
-```
-
-### URL Flow (How Offers Are Opened)
-
-When a user claims an offer, the URL flows through the system as follows:
-
-1. **SDK builds final URL** - `Encore.ts` constructs the advertiser URL with tracking parameters (transaction ID, user ID, etc.)
-2. **SDK calls window.open()** - The SDK opens the URL using the standard `window.open(finalUrl)` API
-3. **Embed intercepts** - `app.js` overrides `window.open()` to capture the URL before it opens
-4. **Embed sends to iOS** - The captured URL is sent via `bridge.sendToIOS('encore:openURL', { url })`
-5. **iOS opens Safari** - The native app receives the message and opens the URL in `SFSafariViewController`
-
-This design ensures:
-- ✅ **No DOM coupling** - The SDK doesn't need to write URLs to DOM attributes
-- ✅ **Clean separation** - The SDK is unaware of the iOS integration
-- ✅ **Tracking preserved** - All tracking parameters flow through naturally
-- ✅ **Framework agnostic** - Works regardless of how the SDK UI is implemented
-
-## Message Protocol
-
-### Web-to-iOS Messages
-
-Messages sent from JavaScript to iOS via `webkit.messageHandlers.encore.postMessage()`:
-
-| Message Type | Payload | Description |
-|-------------|---------|-------------|
-| `encore:ready` | `{ timestamp, hasURLConfig, isMobile }` | Embed app loaded and ready |
-| `encore:initialized` | `{ success, userId, version }` | SDK initialized successfully |
-| `encore:sheet:presented` | `{ timestamp }` | **[Mobile]** Bottom sheet shown |
-| `encore:sheet:dismissed` | `{ reason, timestamp }` | **[Mobile]** Bottom sheet closed |
-| `encore:openURL` | `{ url, timestamp }` | **[Mobile]** Request to open URL in Safari |
-| `encore:entitlementGranted` | `{ entitlement, timestamp }` | User completed offer |
-| `encore:userDeclined` | `{ reason, details, timestamp }` | User declined offer |
-| `encore:error` | `{ code, message, context }` | Error occurred |
-| `encore:userIdentified` | `{ success, userId }` | User identified |
-| `encore:attributesSet` | `{ success }` | Attributes set |
-| `encore:reset` | `{ success }` | SDK reset |
-| `encore:state` | `{ isInitialized, userId, version, config }` | Current state |
-
-### iOS-to-Web Messages
-
-Messages sent from iOS to JavaScript via `webView.evaluateJavaScript()` or `postMessage()`:
-
-| Message Type | Payload | Description |
-|-------------|---------|-------------|
-| `configure` | `{ apiKey, environment?, userId?, attributes?, logLevel? }` | Initialize SDK |
-| `presentOffer` | `{}` | Show offer modal |
-| `identify` | `{ userId, attributes? }` | Identify user |
-| `setUserAttributes` | `{ attributes }` | Update user attributes |
-| `reset` | `{}` | Reset SDK state |
-| `getState` | `{}` | Request current state |
-
-## Integration Methods
-
-### Method 1: URL Builder (Recommended for Mobile)
-
-Use the `EncoreURL` builder to create a properly formatted URL with auto-present:
-
-```swift
-import SwiftUI
-
-let url = EncoreURL.build(
-    apiKey: "your_api_key",
-    userId: "user123",
-    environment: "production",
-    autoPresentOffer: true,  // Auto-show offers
-    debug: false
-)
-
-// In SwiftUI
-.sheet(isPresented: $showEncore) {
-    EncoreWebView(
-        apiKey: "your_api_key",
-        userId: "user123",
-        autoPresentOffer: true
-    )
-}
 ```
-
-**Pros**: Dead simple, iOS-native UI, auto-presents, swipe gestures  
-**Cons**: API key visible in URL (use server-side API key rotation)
-
-### Method 2: URL Parameters (Manual)
-
-Load the embed page with configuration in URL:
-
-```swift
-let url = URL(string: "https://encorekit.com/embed/?apiKey=YOUR_KEY&userId=USER_123&environment=production&autoPresentOffer=true")!
-webView.load(URLRequest(url: url))
+https://encorekit.com/offers?apiKey=pk_live_...&userId=user_123
 ```
 
-### Method 3: postMessage (Advanced)
+`/embed` and `/payrange` serve the same page, so URLs already shipped against
+them keep working. Prefer `/offers` for anything new.
 
-Load empty embed page, then configure via postMessage:
+Open it in whatever webview the platform gives you and load the request. That
+is the whole integration.
 
 ```swift
-// 1. Load embed page
-webView.load(URL(string: "https://encorekit.com/embed/")!)
-
-// 2. Configure after load (in WKNavigationDelegate)
-func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
-    let config = """
-    window.postMessage({
-        type: 'configure',
-        payload: {
-            apiKey: '\(apiKey)',
-            userId: '\(userId)',
-            environment: 'production'
-        }
-    }, '*');
-    """
-    webView.evaluateJavaScript(config)
+guard var components = URLComponents(string: "https://encorekit.com/offers") else { return }
+components.queryItems = [
+    URLQueryItem(name: "apiKey", value: apiKey),
+    URLQueryItem(name: "userId", value: userId),
+]
+if let url = components.url {
+    webView.load(URLRequest(url: url))
 }
 ```
 
-**Pros**: More secure, flexible, dynamic configuration
-**Cons**: Slightly more code
-
-### Method 4: JavaScript with Callbacks (Most Control)
-
-For scenarios where you need to control the flow after initialization:
-
-```javascript
-// In your custom JavaScript or via evaluateJavaScript
-if (window.EncoreBridge && window.Encore) {
-  window.EncoreBridge.on('encore:initialized', (payload) => {
-    console.log('SDK initialized:', payload);
-    // Now safe to present offer
-    window.postMessage({ type: 'presentOffer', payload: {} }, '*');
-  });
-
-  window.EncoreBridge.on('encore:error', (payload) => {
-    console.error('Initialization error:', payload);
-  });
-
-  // Trigger initialization
-  window.postMessage({
-    type: 'configure',
-    payload: {
-      apiKey: 'pk_live_...',
-      userId: 'user_123',
-      environment: 'production'
-    }
-  }, '*');
-}
-```
-
-**Pros**: Full control, proper error handling, no race conditions
-**Cons**: More code, requires understanding of message flow
-
-## Usage Examples
-
-### Present an Offer
-
-```swift
-// From iOS
-let script = """
-window.postMessage({
-    type: 'presentOffer',
-    payload: {}
-}, '*');
-"""
-webView.evaluateJavaScript(script)
-```
+Build the query string with `URLComponents` rather than interpolating into a
+string, so values are percent encoded for you.
 
-### Handle Entitlement Granted
-
-```swift
-// In iOS message handler
-func userContentController(_ userContentController: WKUserContentController, 
-                          didReceive message: WKScriptMessage) {
-    guard message.name == "encore" else { return }
-    
-    guard let dict = message.body as? [String: Any],
-          let type = dict["type"] as? String else {
-        return
-    }
-    
-    switch type {
-    case "encore:entitlementGranted":
-        if let payload = dict["payload"] as? [String: Any],
-           let entitlement = payload["entitlement"] {
-            handleEntitlementGranted(entitlement)
-        }
-    case "encore:userDeclined":
-        if let payload = dict["payload"] as? [String: Any],
-           let reason = payload["reason"] as? String {
-            handleUserDeclined(reason)
-        }
-    case "encore:error":
-        if let payload = dict["payload"] as? [String: Any] {
-            handleError(payload)
-        }
-    case "encore:openURL":
-        if let payload = dict["payload"] as? [String: Any],
-           let urlString = payload["url"] as? String,
-           let url = URL(string: urlString) {
-            openInSafari(url: url)
-        }
-    default:
-        break
-    }
-}
-
-func openInSafari(url: URL) {
-    let safari = SFSafariViewController(url: url)
-    safari.delegate = self
-    present(safari, animated: true)
-}
-
-// SFSafariViewControllerDelegate
-func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
-    // User closed Safari, notify webview
-    let script = """
-    window.postMessage({
-        type: 'safariClosed',
-        payload: { timestamp: \(Date().timeIntervalSince1970 * 1000) }
-    }, '*');
-    """
-    webView.evaluateJavaScript(script)
-}
-```
+## Parameters
 
-## Bridge API
+`apiKey` and `userId` are both required. Without either, the page shows an
+error state naming what is missing rather than a blank screen.
 
-The `EncoreBridge` object provides methods for communication between JavaScript and iOS:
+| Parameter | Notes |
+|-----------|-------|
+| `apiKey` | Your publishable key |
+| `userId` | Your identifier for the end user |
 
-### Listening for Messages
+Optional.
 
-```javascript
-// Listen for messages (stays subscribed)
-const unsubscribe = bridge.on('encore:initialized', (payload) => {
-  console.log('SDK initialized:', payload);
-});
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| `environment` | `production` | One of `production`, `development`, `staging`, `localhost` |
+| `useCase` | `rewardUsers` | Or `reduceChurn` for the churn carousel |
+| `placement` | `hosted_reward` or `hosted_offer` | Follows `useCase` so the two stay separable in reporting |
+| `autoPresentOffer` | `true` | Set `false` to suppress the automatic presentation |
+| `headline` | | Overrides the default headline |
+| `subheadline` | | Overrides the default subheadline |
 
-// Stop listening
-unsubscribe();
+The default `useCase` here is `rewardUsers`, which deliberately differs from the
+Web SDK's own `reduceChurn`. The SDK default suits a save attempt fired as
+someone leaves. This page is opened deliberately by your app, and that moment is
+a reward far more often than it is a cancellation.
 
-// Listen once (automatically unsubscribes after first call)
-bridge.once('encore:initialized', (payload) => {
-  console.log('SDK initialized (one-time):', payload);
-  // Handler is automatically removed after this
-});
-```
+## Targeting attributes
 
-### Sending Messages
+Attributes are flat query parameters, one per key. An earlier revision of these
+examples packed them into a single JSON `attributes=` parameter; that form is
+ignored.
 
-```javascript
-// Send message to iOS
-bridge.sendToIOS('encore:customEvent', {
-  data: 'value',
-  timestamp: Date.now()
-});
 ```
-
-### Initialization Callbacks
-
-The `initializeSDK` function supports optional success/error callbacks to avoid race conditions:
-
-```javascript
-// Proper way to auto-present after initialization
-initializeSDK(
-  { apiKey: 'pk_...', userId: 'user_123' },
-  () => {
-    // Success - SDK is ready
-    presentOffer();
-  },
-  (error) => {
-    // Error - handle failure
-    console.error('Init failed:', error);
-  }
-);
+&countryCode=US&subscriptionTier=premium&custom.plan=gold
 ```
 
-**⚠️ Important**: Never use `setTimeout()` to wait for initialization. Always use callbacks or listen for the `encore:initialized` message to ensure the SDK is truly ready.
+Accepted: `countryCode`, `postalCode`, `city`, `state`, `language`,
+`subscriptionTier`, `monthsSubscribed`, `billingCycle`, `lastPaymentAmount`,
+`lastActiveDate`, `totalSessions`, and any `custom.` prefixed key.
 
-## Debug Mode
+Custom keys are capped at 20 per URL and every value is truncated at 256
+characters. An unknown parameter is ignored rather than forwarded.
 
-Enable debug mode to see message logs:
+### Refused on purpose
 
-1. **Via URL**: Add `?debug=true` to the embed URL
-2. **Via Console**: Run `enableEncoreDebug()` in the web inspector
-3. **Persistent**: Once enabled, it's saved to localStorage
+`email`, `firstName`, `lastName`, `phoneNumber`, `dateOfBirth`, `gender`,
+`latitude` and `longitude` are dropped, and the page reports that it dropped
+them. A query string lands in webview history and in hosting access logs, so
+direct identifiers and precise location do not belong in one. If you genuinely
+need one, ask for a short lived signed token instead of sending the raw value.
 
-Debug panel shows:
-- All messages sent/received
-- SDK initialization status
-- Errors and warnings
-- Timestamps
+## Learning about the entitlement
 
-## File Structure
+The page does not call your app back. Your backend asks Encore instead:
 
 ```
-embed/
-├── index.html              # Main HTML page
-├── bridge.js               # iOS-JavaScript bridge (SOURCE FILE - vanilla JS)
-├── app.js                  # Application logic (SOURCE FILE - vanilla JS)
-├── styles.css              # Base styles (transparent background)
-├── mobile-styles.css       # iOS-native bottom sheet UI
-├── mobile-overrides.css    # Web SDK → mobile sheet transforms
-├── dist/
-│   ├── bridge.min.js       # Minified bridge (generated)
-│   ├── bridge.min.js.map   # Source map (generated)
-│   ├── app.min.js          # Minified app (generated)
-│   └── app.min.js.map      # Source map (generated)
-├── README.md               # This file
-├── MOBILE-UI-GUIDE.md      # Comprehensive mobile UI docs
-└── NEXTJS-DEPLOYMENT.md    # Deployment guide
+GET https://api.encorekit.com/encore/publisher/sdk/v1/entitlements/server?userId=<userId>
 ```
 
-**Note**: `bridge.js` and `app.js` are vanilla JavaScript source files (not TypeScript). They are intentionally written as pure ES6+ to avoid transpilation overhead and are only minified for production.
-
-## Building for Production
-
-```bash
-# Build the embed bundle (minifies bridge.js and app.js)
-npm run build:embed
-
-# Or build everything (SDK + embed)
-npm run build
-
-# Output will be in embed/dist/
-```
+authenticated with your API key and HMAC signature. Poll it when the webview
+closes, or on your own schedule.
 
-## Security Considerations
+## One thing to know about webviews
 
-1. **HTTPS Only**: Always use HTTPS for the embed URL
-2. **API Key Security**: API keys are public but should have usage limits
-3. **Message Validation**: Bridge validates all message structures
-4. **CSP Headers**: Content Security Policy should be configured on server
-5. **Origin Validation**: Messages should validate expected origins
+When the user claims an offer, the page navigates the whole webview to the
+advertiser rather than opening a second window. `window.open` returns null in a
+bare `WebView` or `WKWebView` unless the host app implements the multiple window
+callbacks, so a top level navigation is the only handoff that works without any
+cooperation from you. Expect the webview to leave the offer page at that point.
 
-## Browser Compatibility
+## What used to be here
 
-- iOS 13+ (WKWebView)
-- Modern JavaScript (ES6+)
-- No external dependencies
+This directory once held a static embed page (`index.html`, `bridge.js`,
+`app.js` and its CSS) that spoke a `webkit.messageHandlers` bridge to a native
+iOS host. Those files are deleted. Nothing served them: their build output was
+gitignored and never published, the page loaded a bundle no build produced, and
+the copy that briefly hosted them was removed from the website separately.
 
-## Troubleshooting
-
-### Messages not being received by iOS
-
-Check:
-1. Message handler is registered: `userContentController.add(self, name: "encore")`
-2. WKWebView configuration is correct
-3. Debug mode is enabled to see logs
-
-### SDK not initializing
-
-Check:
-1. API key is valid
-2. Network connectivity
-3. CORS settings (if self-hosting)
-4. Check debug panel for error messages
-
-### Offer modal not showing
-
-Check:
-1. SDK is initialized (`encore:initialized` received)
-2. Offers are available for this user
-3. CSS/styles are loaded properly
-4. Check console for errors
+This README is all that remains, because the URL contract above is the
+integration that replaced them.
 
 ## Support
 
-For more information:
-- [Full iOS WebView Integration Guide](../docs/ios-webview-integration.md)
-- [Swift Example Code](../examples/ios-webview/)
-- [Encore Documentation](https://docs.encorekit.com)
-
+- **[Hosted Offer Page guide](https://docs.encorekit.com/publishers/web/guides/hosted-offer-page)** for the full integration walkthrough,
+  including the backend entitlement check
+- [Swift examples](../examples/ios-webview/) for a URL builder you can copy
+- [Encore documentation](https://docs.encorekit.com)