@encorekit/web-sdk 2.0.3 → 2.0.6

package/examples/ios-webview/EncoreURLBuilder.swift

@@ -1,87 +1,205 @@
 //
 //  EncoreURLBuilder.swift
-//  Encore iOS Simple Integration
+//  Encore hosted offer page, iOS integration
 //
-//  Dead simple: Build a URL, open it in WKWebView. That's it.
+//  Build a URL, open it in a WKWebView. That is the whole integration:
+//  there is no bridge, no message handler, and nothing to call back into.
+//
+//  Copy this one file into your project.
 //
 
 import Foundation
 
-/// Build Encore embed URLs with your configuration
+/// Builds URLs for the Encore hosted offer page.
+///
+/// The page's entire configuration surface is its query string, so this type is
+/// a thin, checkable wrapper around it rather than a client of any kind.
 public struct EncoreURL {
-    
-    /// Build an Encore embed URL
+
+    /// Which experience the page presents.
+    public enum UseCase: String {
+        /// The reward sheet. This is the hosted page's default.
+        case rewardUsers
+        /// The churn carousel, for when you open this from a cancellation flow.
+        case reduceChurn
+    }
+
+    /// The canonical hosted page.
+    ///
+    /// `/embed` and `/payrange` serve the same page and stay supported, so
+    /// builds already shipped against them keep working.
+    public static let defaultBaseURL = "https://encorekit.com/offers"
+
+    /// Targeting keys the page accepts over the query string.
+    ///
+    /// A key outside this set is dropped.
+    ///
+    /// Publisher defined values do NOT go here. Pass them through the separate
+    /// `custom:` parameter, which sends them `custom.` prefixed and caps them
+    /// at `maxCustomKeys`. Putting an already-prefixed `custom.foo` into
+    /// `attributes` does not work: it is not in this set, so it is dropped like
+    /// any other unrecognised key.
+    ///
+    /// `email`, `firstName`, `lastName`, `phoneNumber`, `dateOfBirth`,
+    /// `gender`, `latitude` and `longitude` are refused on purpose. A query
+    /// string is written to webview history and to hosting access logs, which
+    /// is no place for a direct identifier. If you need to target on one, ask
+    /// Encore for a short lived signed token rather than sending the raw value.
+    public static let acceptedAttributes: Set<String> = [
+        "countryCode", "postalCode", "city", "state", "language",
+        "subscriptionTier", "monthsSubscribed", "billingCycle",
+        "lastPaymentAmount", "lastActiveDate", "totalSessions",
+    ]
+
+    /// Length cap the builder applies to attribute and `custom.` values.
+    ///
+    /// The page caps every parameter it reads at this length; the builder only
+    /// pre-applies it to the targeting values it normalises, so `headline`,
+    /// `subheadline` and `userId` go out whole and are cut server side.
+    public static let maxValueLength = 256
+
+    /// The page accepts at most this many `custom.` keys per URL.
+    public static let maxCustomKeys = 20
+
+    /// Wire prefix for publisher defined keys.
+    private static let customPrefix = "custom."
+
+    /// Trim, drop blanks, and truncate, matching what the page does on receipt.
+    private static func normalized(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        return String(trimmed.prefix(maxValueLength))
+    }
+
+    /// Build a hosted offer page URL.
+    ///
     /// - Parameters:
-    ///   - apiKey: Your Encore API key
-    ///   - userId: User identifier (optional)
-    ///   - environment: "production" or "localhost" (default: "production")
-    ///   - attributes: User attributes for targeting (optional)
-    ///   - debug: Enable debug mode (default: false)
-    /// - Returns: URL to load in WKWebView
+    ///   - apiKey: Your publishable Encore key. Required.
+    ///   - userId: Your identifier for the end user. Required: the page shows
+    ///     an error state without it rather than a blank screen.
+    ///   - environment: `production`, `development`, `staging` or `localhost`.
+    ///   - useCase: Omit to take the page's own default, which is `rewardUsers`.
+    ///   - placement: Omit to let the page derive it from `useCase`, which
+    ///     keeps the reward and churn surfaces separable in reporting.
+    ///   - autoPresentOffer: Pass `false` to load the page without presenting.
+    ///   - headline: Overrides the default headline.
+    ///   - subheadline: Overrides the default subheadline.
+    ///   - attributes: Flat targeting values. See `acceptedAttributes`.
+    ///   - custom: Publisher defined values, sent as `custom.<key>`. Pass the
+    ///     bare name or the prefixed one: `plan` and `custom.plan` both go out
+    ///     as `custom.plan`. Passing both keeps one and names the other in the
+    ///     DEBUG drop log; release builds drop it without a diagnostic.
+    ///   - baseURL: Point this at a locally running site to test against it.
+    /// - Returns: The URL to load, or `nil` if `baseURL` is not a valid URL.
     public static func build(
         apiKey: String,
-        userId: String? = nil,
+        userId: String,
         environment: String = "production",
-        attributes: [String: String]? = nil,
-        debug: Bool = false
+        useCase: UseCase? = nil,
+        placement: String? = nil,
+        autoPresentOffer: Bool = true,
+        headline: String? = nil,
+        subheadline: String? = nil,
+        attributes: [String: String] = [:],
+        custom: [String: String] = [:],
+        baseURL: String = defaultBaseURL
     ) -> URL? {
-        guard var components = URLComponents(string: "https://encorekit.com/embed/") else {
-            return nil
-        }
-        
+        guard var components = URLComponents(string: baseURL) else { return nil }
+
         var queryItems: [URLQueryItem] = [
             URLQueryItem(name: "apiKey", value: apiKey),
-            URLQueryItem(name: "environment", value: environment)
+            URLQueryItem(name: "userId", value: userId),
+            URLQueryItem(name: "environment", value: environment),
         ]
-        
-        if let userId = userId {
-            queryItems.append(URLQueryItem(name: "userId", value: userId))
+
+        if let useCase {
+            queryItems.append(URLQueryItem(name: "useCase", value: useCase.rawValue))
         }
-        
-        if let attributes = attributes, !attributes.isEmpty {
-            // Encode attributes as JSON string
-            if let jsonData = try? JSONSerialization.data(withJSONObject: attributes),
-               let jsonString = String(data: jsonData, encoding: .utf8) {
-                queryItems.append(URLQueryItem(name: "attributes", value: jsonString))
-            }
+        if let placement {
+            queryItems.append(URLQueryItem(name: "placement", value: placement))
         }
-        
-        if debug {
-            queryItems.append(URLQueryItem(name: "debug", value: "true"))
+        // The page presents unless told not to, so only the opt out is worth
+        // sending. Spelling out the default would just make the URL longer.
+        if !autoPresentOffer {
+            queryItems.append(URLQueryItem(name: "autoPresentOffer", value: "false"))
         }
-        
-        components.queryItems = queryItems
-        return components.url
-    }
-    
-    /// Build URL for localhost testing
-    public static func buildLocal(
-        apiKey: String,
-        userId: String? = nil,
-        port: Int = 3001,
-        attributes: [String: String]? = nil
-    ) -> URL? {
-        var components = URLComponents(string: "http://localhost:\(port)/embed/")!
-        
-        var queryItems: [URLQueryItem] = [
-            URLQueryItem(name: "apiKey", value: apiKey),
-            URLQueryItem(name: "environment", value: "localhost"),
-            URLQueryItem(name: "debug", value: "true")
-        ]
-        
-        if let userId = userId {
-            queryItems.append(URLQueryItem(name: "userId", value: userId))
+        if let headline {
+            queryItems.append(URLQueryItem(name: "headline", value: headline))
+        }
+        if let subheadline {
+            queryItems.append(URLQueryItem(name: "subheadline", value: subheadline))
         }
-        
-        if let attributes = attributes, !attributes.isEmpty {
-            if let jsonData = try? JSONSerialization.data(withJSONObject: attributes),
-               let jsonString = String(data: jsonData, encoding: .utf8) {
-                queryItems.append(URLQueryItem(name: "attributes", value: jsonString))
+
+        // One parameter per attribute. An earlier version of this file packed
+        // them into a single JSON `attributes=` value, which the page ignores.
+        //
+        // The allowlist is enforced HERE rather than left to the page, and that
+        // is the whole point of it: a refused key is refused because the URL is
+        // itself the exposure. Once `email` has been written into a webview's
+        // history and a hosting access log, the page dropping it server side
+        // does not unwrite it.
+        var dropped: [String] = []
+
+        for key in attributes.keys.sorted() {
+            guard acceptedAttributes.contains(key) else {
+                dropped.append(key)
+                continue
+            }
+            // A blank value removes targeting just as surely as a refused
+            // key does, so it joins `dropped` rather than vanishing silently.
+            guard let value = normalized(attributes[key]) else {
+                dropped.append(key)
+                continue
             }
+            queryItems.append(URLQueryItem(name: key, value: value))
         }
-        
+
+        var customCount = 0
+        var claimedCustomNames = Set<String>()
+        for key in custom.keys.sorted() {
+            // Tolerate a key the caller already prefixed. `plan` and
+            // `custom.plan` must both go out as `custom.plan`, never
+            // `custom.custom.plan`, which the page would ignore.
+            let bare = key.hasPrefix(customPrefix)
+                ? String(key.dropFirst(customPrefix.count))
+                : key
+            let wireName = customPrefix + bare
+
+            guard !bare.isEmpty else {
+                dropped.append(key)
+                continue
+            }
+            // Because both spellings collapse to one wire name, a caller who
+            // passes `plan` AND `custom.plan` would otherwise emit the
+            // parameter twice and spend two of the 20 slots on it. First in
+            // sorted order wins; the loser is named so the clash is visible.
+            guard claimedCustomNames.insert(wireName).inserted else {
+                dropped.append(key)
+                continue
+            }
+            guard customCount < maxCustomKeys else {
+                dropped.append(wireName)
+                continue
+            }
+            guard let value = normalized(custom[key]) else {
+                dropped.append(wireName)
+                continue
+            }
+            queryItems.append(URLQueryItem(name: wireName, value: value))
+            customCount += 1
+        }
+
+        // Say what was dropped instead of letting targeting quietly
+        // underperform with nothing anywhere explaining why. DEBUG only: a
+        // release build drops the same keys without any diagnostic.
+        #if DEBUG
+        if !dropped.isEmpty {
+            print("[Encore] not sent in the offer URL: \(dropped.joined(separator: ", "))")
+        }
+        #endif
+
         components.queryItems = queryItems
         return components.url
     }
 }
-