@encorekit/web-sdk 0.1.1 → 0.1.7

package/embed/README.md

@@ -0,0 +1,409 @@
+# Encore iOS WebView Embed
+
+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.
+
+## 🎨 Mobile-Native UI
+
+The embed now features an **iOS-native bottom sheet UI** that provides a mobile-optimized experience matching the iOS SDK's visual design:
+
+- ✅ **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?, uiConfiguration? }` | 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))
+```
+
+### Method 3: postMessage (Advanced)
+
+Load empty embed page, then configure via postMessage:
+
+```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)
+}
+```
+
+**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)
+```
+
+### 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)
+}
+```
+
+## Bridge API
+
+The `EncoreBridge` object provides methods for communication between JavaScript and iOS:
+
+### Listening for Messages
+
+```javascript
+// Listen for messages (stays subscribed)
+const unsubscribe = bridge.on('encore:initialized', (payload) => {
+  console.log('SDK initialized:', payload);
+});
+
+// Stop listening
+unsubscribe();
+
+// 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
+});
+```
+
+### Sending Messages
+
+```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);
+  }
+);
+```
+
+**⚠️ 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.
+
+## Debug Mode
+
+Enable debug mode to see message logs:
+
+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
+
+Debug panel shows:
+- All messages sent/received
+- SDK initialization status
+- Errors and warnings
+- Timestamps
+
+## File Structure
+
+```
+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
+```
+
+**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/
+```
+
+## Security Considerations
+
+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
+
+## Browser Compatibility
+
+- iOS 13+ (WKWebView)
+- Modern JavaScript (ES6+)
+- No external dependencies
+
+## 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
+
+## 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)
+

package/embed/index.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+  <title>Encore Embed</title>
+  <link rel="stylesheet" href="embed/styles.css">
+  <!-- Mobile-native styles for iOS bottom sheet UI -->
+  <link rel="stylesheet" href="embed/mobile-styles.css">
+  <!-- Override Web SDK modal to work as bottom sheet -->
+  <link rel="stylesheet" href="embed/mobile-overrides.css">
+</head>
+<body>
+  <!-- 
+    This page is designed to be embedded in iOS WKWebView.
+    It remains transparent until an offer is presented.
+  -->
+  
+  <!-- Loading indicator (hidden by default) -->
+  <div id="encore-loading" class="encore-loading" style="display: none;">
+    <div class="encore-spinner"></div>
+  </div>
+
+  <!-- Debug panel (only shown in development) -->
+  <div id="encore-debug" class="encore-debug" style="display: none;">
+    <div class="debug-header">
+      <span>Encore Debug</span>
+      <div class="debug-controls">
+        <button id="debug-minimize" title="Minimize">−</button>
+        <button id="debug-close" title="Close">×</button>
+      </div>
+    </div>
+    <div id="debug-log" class="debug-log"></div>
+  </div>
+
+  <!-- Credit Claimed Confirmation View -->
+  <div id="encore-claimed" class="encore-claimed-view" style="display: none;">
+    <div class="claimed-content">
+      <div class="claimed-checkmark">✓</div>
+      <h2 class="claimed-title">Credit Claimed!</h2>
+      <p class="claimed-message">Your reward has been unlocked</p>
+      <button id="claimed-done" class="encore-button encore-button-primary">Done</button>
+    </div>
+  </div>
+
+  <!-- Load Encore Web SDK (local build) -->
+  <script src="embed/dist/encore.min.js"></script>
+  
+  <!-- Load iOS Bridge -->
+  <script src="embed/dist/bridge.min.js"></script>
+  
+  <!-- Load Application Logic -->
+  <script src="embed/dist/app.min.js"></script>
+</body>
+</html>

package/embed/styles.css

@@ -0,0 +1,154 @@
+/**
+ * Encore Embed Styles
+ * Minimal styles for the embed container
+ * The Web SDK provides its own modal styles
+ */
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html, body {
+  width: 100%;
+  height: 100%;
+  /* White background to fill the sheet */
+  background: white;
+  overflow: hidden;
+  /* No padding - SwiftUI sheet handles safe areas */
+  padding: 0;
+}
+
+/* Prevent text selection in embed */
+body {
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+}
+
+/* Loading indicator */
+.encore-loading {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 9997;
+}
+
+.encore-spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid rgba(0, 0, 0, 0.1);
+  border-top-color: #000;
+  border-radius: 50%;
+  animation: encore-spin 1s linear infinite;
+}
+
+@keyframes encore-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+  .encore-spinner {
+    border-color: rgba(255, 255, 255, 0.1);
+    border-top-color: #fff;
+  }
+}
+
+/* Debug panel */
+.encore-debug {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  max-height: 40vh;
+  background: rgba(0, 0, 0, 0.9);
+  color: #00ff00;
+  font-family: 'Courier New', monospace;
+  font-size: 12px;
+  z-index: 99999;
+  border-top: 2px solid #00ff00;
+  display: flex;
+  flex-direction: column;
+  transition: max-height 0.3s ease;
+}
+
+.encore-debug.minimized {
+  max-height: 40px;
+}
+
+.encore-debug.minimized .debug-log {
+  display: none;
+}
+
+.encore-debug.minimized .debug-header {
+  border-bottom: none;
+}
+
+.debug-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 12px;
+  background: rgba(0, 0, 0, 0.95);
+  border-bottom: 1px solid #00ff00;
+  font-weight: bold;
+  cursor: pointer;
+}
+
+.debug-controls {
+  display: flex;
+  gap: 8px;
+}
+
+#debug-minimize,
+#debug-close {
+  background: transparent;
+  border: 1px solid #00ff00;
+  color: #00ff00;
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  cursor: pointer;
+  font-size: 16px;
+  line-height: 1;
+  padding: 0;
+}
+
+#debug-minimize:active,
+#debug-close:active {
+  background: rgba(0, 255, 0, 0.2);
+}
+
+.debug-log {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px 12px;
+  -webkit-overflow-scrolling: touch;
+}
+
+.debug-entry {
+  margin-bottom: 4px;
+  word-break: break-word;
+}
+
+.debug-entry.error {
+  color: #ff0000;
+}
+
+.debug-entry.warning {
+  color: #ffaa00;
+}
+
+.debug-entry.info {
+  color: #00aaff;
+}
+
+/* Ensure Web SDK modal appears above everything */
+:root {
+  --encore-modal-z-index: 9998;
+  --encore-backdrop-z-index: 9997;
+}
+