Documentation: Error Reporting, Logging & Offline Mode Architecture Deep Dive

[RGG-jayoung]

Iterable Swift SDK: Architecture Documentation

This issue documents a comprehensive analysis of the error reporting, logging, and offline mode systems in the Iterable Swift SDK. This serves as developer reference documentation.

---

Table of Contents

1. Error Reporting & Logging System
2. Offline Mode & Task Persistence

---

1. Error Reporting & Logging System

1.1 Logging Architecture

Log Levels

The SDK defines three log levels in Constants.swift:492:

@objc(IterableLogLevel) public enum LogLevel: Int {
    case debug = 1
    case info
    case error
}

Global Logging Functions

Three convenience functions in IterableLogging.swift:

Function	Level	Emoji Marker
ITBDebug()	.debug	💚
ITBInfo()	.info	💛
ITBError()	.error	❤️

Each captures file, method, line number, and thread pointer automatically.

Log Message Format

Generated by IterableLogUtil.formatLogMessage:

HH:mm:ss.SSSS:0x7ff8c9c0e:FileName:methodName:123: Your message here

Built-in Log Delegates

Delegate	Behavior
DefaultLogDelegate	Uses os_log for messages >= minLogLevel (default: .info)
AllLogDelegate	Prints everything to console via print()
NoneLogDelegate	Silent - no output

Custom Log Delegate Protocol

@objc public protocol IterableLogDelegate: AnyObject {
    @objc(log:message:)
    func log(level: LogLevel, message: String)
}

---

1.2 Error Type Hierarchy

Error Type	Location	Purpose
IterableError	Pending.swift:7	Generic SDK errors
SendRequestError	RequestSender.swift:9	Network request failures
NetworkError	NetworkHelper.swift:7	Low-level network errors
IterableTaskError	IterableTaskError.swift:7	Offline task queue errors

SendRequestError Structure

public struct SendRequestError: Error {
    public let reason: String?           // Human-readable description
    public let data: Data?               // Raw response data
    public let httpStatusCode: Int?      // HTTP status code
    public let iterableCode: String?     // Iterable-specific error code (401 responses)
    public let originalError: Error?     // Underlying error
}

Authentication Error Types

AuthFailure:

@objcMembers public class AuthFailure: NSObject {
    public let userKey: String?
    public let failedAuthToken: String?
    public let failedRequestTime: Int
    public let failureReason: AuthFailureReason
}

AuthFailureReason enum:

• authTokenExpired
• authTokenGenericError
• authTokenExpirationInvalid
• authTokenSignatureInvalid
• authTokenFormatInvalid
• authTokenInvalidated
• authTokenPayloadInvalid
• authTokenUserKeyInvalid
• authTokenNull
• authTokenGenerationError
• authTokenMissing

---

1.3 Asynchronous Error Propagation

The SDK uses a custom Pending<Value, Failure> Promise implementation:

public class Pending<Value, Failure> where Failure: Error {
    func onSuccess(block: @escaping ((Value) -> Void)) -> Pending<Value, Failure>
    func onError(block: @escaping ((Failure) -> Void)) -> Pending<Value, Failure>
    func map<NewValue>(_ closure: @escaping (Value) -> NewValue) -> Pending<NewValue, Failure>
    func flatMap<NewValue>(_ closure: @escaping (Value) -> Pending<NewValue, Failure>) -> Pending<NewValue, Failure>
    func mapFailure<NewFailure>(_ closure: @escaping (Failure) -> NewFailure) -> Pending<Value, NewFailure>
}

---

1.4 Retry Mechanisms

Network Retry (NetworkHelper.swift)

• Max retries: 5
• Retry delay: 2 seconds (after first 2 immediate retries)
• Only retries on 5xx server errors
• 4xx errors fail immediately

JWT Auth Token Retry (RetryPolicy)

public class RetryPolicy {
    var maxRetry: Int           // Default: 10
    var retryInterval: Double   // Default: 6 seconds
    var retryBackoff: BackoffType  // .linear or .exponential
}

---

1.5 Health Monitoring & Circuit Breaker

HealthMonitor implements a circuit breaker pattern:

• Tracks database errors
• When tripped, canSchedule() and canProcess() return false
• RequestHandler falls back to online-only mode
• Max tasks limit: 1000

---

1.6 Notification-Based Error Events

static let iterableTaskScheduled = Notification.Name("itbl_task_scheduled")
static let iterableTaskFinishedWithSuccess = Notification.Name("itbl_task_finished_with_success")
static let iterableTaskFinishedWithRetry = Notification.Name("itbl_task_finished_with_retry")
static let iterableTaskFinishedWithNoRetry = Notification.Name("itbl_task_finished_with_no_retry")
static let iterableNetworkOffline = Notification.Name("itbl_network_offline")
static let iterableNetworkOnline = Notification.Name("itbl_network_online")

---

2. Offline Mode & Task Persistence

2.1 Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                         RequestHandler                            │
│  chooseRequestProcessor() → checks HealthMonitor.canSchedule()   │
└─────────────────┬──────────────────────────┬─────────────────────┘
                  │                          │
                  ▼                          ▼
┌─────────────────────────┐    ┌─────────────────────────────────┐
│  OnlineRequestProcessor │    │    OfflineRequestProcessor      │
│  (Immediate HTTP)       │    │                                 │
└─────────────────────────┘    │  IterableTaskScheduler          │
                               │       ↓                         │
                               │  CoreData (SQLite)              │
                               │       ↓                         │
                               │  IterableTaskRunner             │
                               │       ↓                         │
                               │  IterableAPICallTaskProcessor   │
                               └─────────────────────────────────┘

2.2 Offline Mode Activation

Controlled by remote configuration from Iterable backend:

private func checkRemoteConfiguration() {
    requestHandler.getRemoteConfiguration().onSuccess { remoteConfiguration in
        self.localStorage.offlineMode = remoteConfiguration.offlineMode
        self.requestHandler.offlineMode = remoteConfiguration.offlineMode
    }
}

2.3 CoreData Schema

Entity: IterableTaskManagedObject

Attribute	Type	Notes
id	String	UUID, indexed
name	String?	API path
type	String	Always "apiCall"
data	Binary	JSON-encoded request
scheduledAt	Date	Execution time, indexed
requestedAt	Date	Original request time
createdAt	Date	Record creation
attempts	Int64	Retry count
processing	Bool	Lock flag
failed	Bool	Permanent failure
blocking	Bool	Blocks queue

2.4 Task Scheduling Flow

1. OfflineRequestProcessor.sendIterableRequest() called
2. Creates IterableAPICallRequest with full request data
3. IterableTaskScheduler.schedule() encodes to JSON and saves to CoreData
4. Posts .iterableTaskScheduled notification
5. Returns Pending<> mapped to taskId

2.5 Task Runner

• Listens for: task scheduled, app foreground, connectivity changes
• Processes queue FIFO by scheduledAt
• Default interval: 1 minute between checks
• Respects HealthMonitor.canProcess() guard

2.6 Network Connectivity Detection

Dual-layer approach:

1. NWPathMonitor - Passive OS-level network change detection
2. Active HTTP probing - Checks apple.com and google.com

Polling intervals:

• Offline: 1 minute
• Online: 10 minutes

2.7 Task Result Handling

enum IterableTaskResult {
    case success(detail: TaskSuccessDetail?)
    case failureWithRetry(retryAfter: TimeInterval?, detail: TaskFailureDetail?)
    case failureWithNoRetry(detail: TaskFailureDetail?)
}

Retry decision:

• Error contains "offline" → retry later
• HTTP 4xx → no retry, delete task
• HTTP 5xx → no retry (already retried by NetworkHelper)

2.8 Supported Offline Operations

✅ Queued offline:

• updateCart()
• trackPurchase()
• trackPushOpen()
• track(event:)
• trackInAppOpen/Click/Close/Delivery()
• track(inboxSession:)
• inAppConsume()
• Embedded message events

❌ Always online:

• register(token:)
• disableDevice()
• updateUser()
• updateEmail()
• updateSubscriptions()
• Remote configuration fetch
• In-app message fetch

2.9 Timing Constants

Constant	Value
Task runner interval	1 minute
Offline polling	1 minute
Online polling	10 minutes
Connectivity timeout	5 seconds
Max queue size	1000 tasks

---

Future Additions

This issue will be updated with additional deep dives into:

• JWT Authentication Flow
• In-App Messaging System
• Unknown User Tracking
• Embedded Messaging
• Request Building & Validation

---

This documentation was created through code analysis of the Iterable Swift SDK.

[RGG-jayoung]

Deep Dive: 6 Aspects of Offline Mode

This comment provides an in-depth technical analysis of each of the six core aspects that make up Iterable SDK's offline mode system.

---

Aspect 1: Transparent Queuing

Overview

The SDK provides transparent queuing where API calls made while offline are automatically stored and sent when connectivity returns. The caller's code doesn't need to handle offline scenarios explicitly.

How It Works

1.1 Request Interception Point

When an API method is called (e.g., track(event:)), the RequestHandler intercepts it:

RequestHandler.swift:376-396

private func chooseRequestProcessor() -> Pending<RequestProcessorProtocol, Never> {
    // If offline mode disabled, use immediate HTTP
    guard offlineMode else {
        return Fulfill<RequestProcessorProtocol, Never>(value: onlineProcessor)
    }
    
    // Check if offline processor and health monitor exist
    guard let offlineProcessor = offlineProcessor,
          let healthMonitor = healthMonitor else {
        return Fulfill<RequestProcessorProtocol, Never>(value: onlineProcessor)
    }
    
    // Ask health monitor if we can schedule (queue not full, no DB errors)
    return healthMonitor.canSchedule().map { value -> RequestProcessorProtocol in
        value ? offlineProcessor : self.onlineProcessor
    }
}

1.2 Request Packaging

The OfflineRequestProcessor packages requests into IterableAPICallRequest:

OfflineRequestProcessor.swift:387-391

let apiCallRequest = IterableAPICallRequest(
    apiKey: apiKey,
    endpoint: endpoint,
    authToken: authManager?.getAuthToken(),  // Captures current auth token
    deviceMetadata: deviceMetadata,
    iterableRequest: iterableRequest          // The actual GET/POST request
)

1.3 Transparent Return Type

Both online and offline processors return the same type:

func track(event: String, ...) -> Pending<SendRequestValue, SendRequestError>

The caller receives a Pending<> promise that resolves when:

• Online mode: HTTP response received
• Offline mode: Task eventually executes and completes

1.4 Supported Operations Matrix

Operation	Offline Capable	Reason
track(event:)	✅	Fire-and-forget analytics
trackPurchase()	✅	Commerce events
updateCart()	✅	Commerce events
trackPushOpen()	✅	Engagement tracking
trackInAppOpen/Click/Close()	✅	In-app analytics
track(inboxSession:)	✅	Inbox analytics
inAppConsume()	✅	Message management
track(embedded*)	✅	Embedded messaging
register(token:)	❌	Needs server confirmation
disableDevice()	❌	Security-critical
updateUser()	❌	User profile (immediate)
updateEmail()	❌	Identity change (immediate)
updateSubscriptions()	❌	Preference change (immediate)
getInAppMessages()	❌	Needs response data
getRemoteConfiguration()	❌	SDK configuration

---

Aspect 2: FIFO Processing

Overview

Tasks are processed in First-In-First-Out order based on their scheduledAt timestamp. This ensures event ordering is preserved.

Implementation Details

2.1 Task Ordering Query

CoreDataPersistenceContext.nextTask() in IterableCoreDataPersistence.swift:132-139

func nextTask() throws -> IterableTask? {
    let taskManagedObjects: [IterableTaskManagedObject] = try CoreDataUtil.findSortedEntities(
        context: managedObjectContext,
        entity: PersistenceConst.Entity.Task.name,
        column: PersistenceConst.Entity.Task.Column.scheduledAt,
        ascending: true,    // ← OLDEST FIRST
        limit: 1            // ← Only one task at a time
    )
    return taskManagedObjects.first.map(PersistenceHelper.task(from:))
}

2.2 CoreData Index for Performance

The CoreData model defines an index on scheduledAt:

IterableDataModel.xcdatamodeld

<fetchIndex name="byScheduledAt">
    <fetchIndexElement property="scheduledAt" type="Binary" order="ascending"/>
</fetchIndex>

This ensures O(log n) lookup for the oldest task.

2.3 Timestamp Preservation

When a task is scheduled, the original request time is preserved:

IterableTaskScheduler.swift:32-37

try persistenceContext.create(task: IterableTask(
    id: taskId,
    name: apiCallRequest.getPath(),
    type: .apiCall,
    scheduledAt: scheduledAt ?? strongSelf.dateProvider.currentDate,  // Queue order
    requestedAt: strongSelf.dateProvider.currentDate                  // Original time
))

2.4 createdAt Field Injection

When the task is processed, the original scheduledAt time is injected into the request body:

IterableAPICallTaskProcessor.swift:22

let iterableRequest = decodedIterableRequest.addingCreatedAt(task.scheduledAt)

IterableAPICallRequest.swift:48-51

func addingCreatedAt(_ createdAt: Date) -> IterableAPICallRequest {
    addingBodyField(key: JsonKey.Body.createdAt,
                    value: IterableUtil.secondsFromEpoch(for: createdAt))
}

This means Iterable's backend receives the original event timestamp, not the send time.

2.5 Sequential Processing

The IterableTaskRunner processes one task at a time:

IterableTaskRunner.swift:159-176

if let task = try persistenceContext.nextTask() {
    execute(task: task).onSuccess { [weak self] executionResult in
        self?.persistenceContext.perform {
            switch executionResult {
            case .success, .failure, .error:
                // Immediately process next task
                self?.processTasks()
            case .processing, .retry:
                // Back off, schedule next check
                self?.scheduleNext()
            }
        }
    }
}

---

Aspect 3: Persistence (CoreData/SQLite)

Overview

Tasks are persisted to SQLite via CoreData, ensuring they survive app termination, crashes, and device restarts.

Implementation Details

3.1 Storage Location

CoreData stores the SQLite file in the app's default location:

<AppContainer>/Library/Application Support/IterableDataModel.sqlite

3.2 PersistentContainer Configuration

IterableCoreDataPersistence.swift:41-58

private static func create() -> PersistentContainer? {
    guard let managedObjectModel = createManagedObjectModel() else {
        ITBError("Could not initialize managed object model")
        return nil
    }
    
    let container = PersistentContainer(name: PersistenceConst.dataModelFileName, 
                                        managedObjectModel: managedObjectModel)
    container.loadPersistentStores { desc, error in
        if let error = error {
            ITBError("Unresolved error when creating PersistentContainer: \(error)")
        }
        ITBInfo("Successfully loaded persistent store at: \(desc.url?.description ?? "nil")")
    }
    
    // Enable automatic merge from parent contexts
    container.viewContext.automaticallyMergesChangesFromParent = true
    container.viewContext.mergePolicy = NSMergePolicy(merge: .mergeByPropertyStoreTrumpMergePolicyType)
    
    return container
}

3.3 Data Model Schema

IterableTaskManagedObject Attributes:

Attribute	Type	Purpose
id	String	UUID identifier (indexed)
name	String?	API path (e.g., /events/track)
type	String	Task type ("apiCall")
version	Int64	Schema version (1)
data	Binary	JSON-encoded IterableAPICallRequest
scheduledAt	Date	Execution order (indexed)
requestedAt	Date	Original request timestamp
createdAt	Date	DB record creation time
modifiedAt	Date?	Last modification time
attempts	Int64	Execution attempt count
lastAttemptedAt	Date?	Last attempt timestamp
processing	Bool	Lock flag during execution
failed	Bool	Permanent failure marker
blocking	Bool	Whether task blocks queue
taskFailureData	Binary?	Serialized failure info

3.4 Request Serialization

The complete API request is JSON-encoded:

IterableAPICallRequest (Codable):

struct IterableAPICallRequest: Codable {
    let apiKey: String
    let endpoint: String
    let authToken: String?
    let deviceMetadata: DeviceMetadata
    let iterableRequest: IterableRequest  // POST body or GET args
}

PostRequest Body Encoding:

func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(path, forKey: .path)
    try container.encode(args, forKey: .args)
    // Body is serialized to Data via JSONSerialization
    if let body = body {
        let bodyData = try JSONSerialization.data(withJSONObject: body, options: [])
        try container.encode(bodyData, forKey: .body)
    }
}

3.5 Background Context Usage

All persistence operations use background contexts:

IterableTaskScheduler.swift:23-24

let persistenceContext = persistenceContextProvider.newBackgroundContext()
persistenceContext.perform { [weak self] in
    // Database operations happen on background queue
}

PersistentContainer.newBackgroundContext():

override func newBackgroundContext() -> NSManagedObjectContext {
    let backgroundContext = super.newBackgroundContext()
    backgroundContext.automaticallyMergesChangesFromParent = true
    backgroundContext.mergePolicy = NSMergePolicy(merge: .mergeByPropertyStoreTrumpMergePolicyType)
    return backgroundContext
}

3.6 Merge Policy

mergeByPropertyStoreTrumpMergePolicyType means:

• On conflict, in-memory values overwrite persisted values
• Prevents stale reads from causing data loss

---

Aspect 4: Health Monitoring (Circuit Breaker)

Overview

The HealthMonitor implements a circuit breaker pattern that prevents cascading failures when the database becomes corrupted or unavailable.

Implementation Details

4.1 HealthMonitor State

HealthMonitor.swift:44-56

class HealthMonitor {
    private var errored = false  // Circuit breaker state
    
    init(dataProvider: HealthMonitorDataProviderProtocol,
         dateProvider: DateProviderProtocol,
         networkSession: NetworkSessionProtocol) {
        self.dataProvider = dataProvider
        self.dateProvider = dateProvider
        self.networkSession = networkSession
    }
    
    weak var delegate: HealthMonitorDelegate?
}

4.2 canSchedule() Check

Called before adding a task to the queue:

HealthMonitor.swift:58-85

func canSchedule() -> Pending<Bool, Never> {
    // Circuit breaker check
    guard errored == false else {
        return Fulfill<Bool, Never>(value: false)
    }

    let fulfill = Fulfill<Bool, Never>()
    do {
        try dataProvider.countTasks().onCompletion { count in
            // Queue capacity check (maxTasks = 1000)
            if count < self.dataProvider.maxTasks {
                fulfill.resolve(with: true)
            } else {
                fulfill.resolve(with: false)  // Queue full
            }
        } receiveError: { error in
            ITBError("DBError: " + error.localizedDescription)
            self.onError()  // Trip circuit breaker
            fulfill.resolve(with: false)
        }
    } catch let error {
        ITBError("DBError: " + error.localizedDescription)
        onError()
        fulfill.resolve(with: false)
    }

    return fulfill
}

4.3 canProcess() Check

Called before processing each task:

HealthMonitor.swift:87-89

func canProcess() -> Bool {
    return !errored  // Simple flag check
}

4.4 Error Handlers

Multiple error types can trip the circuit:

func onScheduleError(apiCallRequest: IterableAPICallRequest) {
    ITBError("Schedule error for \(apiCallRequest.getPath())")
    onError()
}

func onDeleteError(task: IterableTask) {
    ITBError("Delete error for task: \(task.id)")
    onError()
}

func onNextTaskError() {
    ITBError("Next task error")
    onError()
}

func onDeleteAllTasksError() {
    ITBError("Delete all tasks error")
    onError()
}

4.5 Circuit Breaker Trip

HealthMonitor.swift:117-120

private func onError() {
    errored = true
    delegate?.onDBError()  // Notify RequestHandler
}

4.6 RequestHandler Response

RequestHandler.swift:399-403

extension RequestHandler: HealthMonitorDelegate {
    func onDBError() {
        self.offlineMode = false  // ← FALLBACK TO ONLINE-ONLY
    }
}

Once tripped, all subsequent requests bypass the offline queue and go directly to HTTP.

4.7 Queue Capacity

DependencyContainerProtocol.swift:125-127

func createHealthMonitorDataProvider(persistenceContextProvider: IterablePersistenceContextProvider) 
    -> HealthMonitorDataProviderProtocol {
    HealthMonitorDataProvider(maxTasks: 1000, persistenceContextProvider: persistenceContextProvider)
}

Maximum 1000 tasks can be queued. Beyond that, requests fall back to online mode.

---

Aspect 5: Dual Connectivity Detection

Overview

The SDK uses two layers of connectivity detection to accurately determine network availability:

1. NWPathMonitor (passive OS-level monitoring)
2. Active HTTP probing (verification via actual requests)

Implementation Details

5.1 NetworkConnectivityManager Coordination

NetworkConnectivityManager.swift:42-53

func start() {
    // Layer 1: OS-level network monitoring
    networkMonitor.statusUpdatedCallback = { [weak self] in 
        self?.updateStatus()  // Triggers Layer 2
    }
    networkMonitor.start()
    
    // Start periodic polling timer
    startTimer()
}

5.2 Layer 1: NWPathMonitor

NetworkMonitor.swift:32-42

func start() {
    let networkMonitor = NWPathMonitor()
    networkMonitor.pathUpdateHandler = { path in
        ITBInfo("networkMonitor.pathUpdateHandler, path: \(path.debugDescription), status: \(path.status)")
        self.statusUpdatedCallback?()  // Just signals "something changed"
    }
    networkMonitor.start(queue: queue)
    self.networkMonitor = networkMonitor
}

Important: NWPathMonitor only reports that network interfaces changed—it doesn't verify actual connectivity.

5.3 Layer 2: Active HTTP Probing

NetworkConnectivityChecker.swift:98-105

private static let urlsToCheck: [URL] = [
    "https://www.apple.com/library/test/success.html",
    "https://www.google.com"
].compactMap { URL(string: $0) }

// Threshold: 50% of checks must succeed
private static let defaultIsThresholdMet: (Int, Int) -> Bool = { value, outOf in
    (Double(value) / Double(outOf)) * 100.0 >= 50.0
}

NetworkConnectivityChecker.checkConnectivity():

func checkConnectivity() -> Pending<Bool, Never> {
    let result = Fulfill<Bool, Never>()
    var successfulChecks: Int = 0, failedChecks: Int = 0
    let totalChecks = Self.urlsToCheck.count  // 2 URLs
    
    // Make requests to both URLs in parallel
    tasks = Self.urlsToCheck.map {
        return networkSession.createDataTask(with: $0, completionHandler: completionHandlerForUrl($0))
    }
    
    tasks.forEach { task in
        dispatchGroup.enter()
        tasksQueue.async { task.resume() }
    }
    
    dispatchGroup.notify(queue: updateQueue) { [self] in
        // At least 50% must succeed (1 of 2)
        let online = self.isThresholdMet(successfulChecks, totalChecks)
        result.resolve(with: online)
    }
    
    return result
}

5.4 Request Timeouts

NetworkConnectivityChecker.swift:90-96

private static let urlSessionConfiguration: URLSessionConfiguration = {
    let sessionConfiguration = URLSessionConfiguration.default
    sessionConfiguration.requestCachePolicy = .reloadIgnoringCacheData
    sessionConfiguration.timeoutIntervalForRequest = 5.0   // 5 second timeout
    sessionConfiguration.timeoutIntervalForResource = 5.0
    return sessionConfiguration
}()

5.5 Polling Intervals

NetworkConnectivityManager.swift:105-106

private static let defaultOfflineModePollingInterval: TimeInterval = 1 * 60.0   // 1 minute
private static let defaultOnlineModePollingInterval: TimeInterval = 10 * 60     // 10 minutes

• Offline: Poll every 1 minute (aggressive recovery)
• Online: Poll every 10 minutes (light health check)

5.6 State Change Propagation

NetworkConnectivityManager.swift:108-117

private var online = true {
    didSet {
        ITBInfo("online: \(online)")
        if online != oldValue {
            ITBInfo("connectivity changed")
            connectivityChangedCallback?(online)  // Notify TaskRunner
            resetTimer()  // Adjust polling interval
        }
    }
}

5.7 TaskRunner Response

IterableTaskRunner.swift:86-100

private func onConnectivityChanged(connected: Bool) {
    persistenceContext.perform { [weak self] in
        if connected {
            if self?.paused == true {
                self?.paused = false
                self?.run()  // Resume processing
            }
        } else {
            if self?.paused == false {
                self?.paused = true  // Pause processing
            }
        }
    }
}

---

Aspect 6: Promise Continuity

Overview

The most elegant aspect of the offline system is promise continuity—the original API call's promise resolves when the task eventually completes, even if that happens much later.

Implementation Details

6.1 Promise Creation at Call Time

When you call an API method:

OfflineRequestProcessor.sendIterableRequest() (line 374-418):

// 1. Schedule the task, get a taskId
return taskScheduler.schedule(apiCallRequest: apiCallRequest, context: IterableTaskContext(blocking: true))
    .mapFailure { error in SendRequestError.from(error: error) }
    .flatMap { taskId -> Pending<SendRequestValue, SendRequestError> in
        // 2. Register this taskId with the NotificationListener
        let pendingTask = notificationListener.futureFromTask(withTaskId: taskId)
        // 3. Apply success/failure handlers and return
        return RequestProcessorUtil.apply(
            successHandler: onSuccess,
            andFailureHandler: onFailure,
            andAuthManager: authManager,
            toResult: pendingTask,
            withIdentifier: identifier
        )
    }

6.2 NotificationListener Registry

OfflineRequestProcessor.NotificationListener (line 420-501):

private class NotificationListener: NSObject {
    // Map of taskId → promise to resolve
    private var pendingTasksMap = [String: Fulfill<SendRequestValue, SendRequestError>]()
    private var pendingTasksQueue = DispatchQueue(label: "pendingTasks")
    
    func futureFromTask(withTaskId taskId: String) -> Pending<SendRequestValue, SendRequestError> {
        let result = Fulfill<SendRequestValue, SendRequestError>()
        pendingTasksQueue.async { [weak self] in
            ITBInfo("adding pending task: \(taskId)")
            self?.pendingTasksMap[taskId] = result  // Store promise
        }
        return result
    }
}

6.3 Notification Subscription

init(notificationCenter: NotificationCenterProtocol) {
    super.init()
    // Listen for task completion
    notificationCenter.addObserver(self,
        selector: #selector(onTaskFinishedWithSuccess),
        name: .iterableTaskFinishedWithSuccess, object: nil)
    notificationCenter.addObserver(self,
        selector: #selector(onTaskFinishedWithNoRetry),
        name: .iterableTaskFinishedWithNoRetry, object: nil)
}

6.4 Task Execution and Notification

When IterableTaskRunner completes a task:

IterableTaskRunner.processTaskResultInQueue() (line 231-274):

switch taskResult {
case let .success(detail: detail):
    strongSelf.deleteTask(task: task)
    if let successDetail = detail as? SendRequestValue {
        let userInfo = IterableNotificationUtil.sendRequestValueToUserInfo(successDetail, taskId: task.id)
        // POST NOTIFICATION WITH taskId AND RESULT
        strongSelf.notificationCenter.post(
            name: .iterableTaskFinishedWithSuccess,
            object: strongSelf,
            userInfo: userInfo
        )
    }
    fulfill.resolve(with: .success)
    
case let .failureWithNoRetry(detail: detail):
    strongSelf.deleteTask(task: task)
    if let failureDetail = detail as? SendRequestError {
        let userInfo = IterableNotificationUtil.sendRequestErrorToUserInfo(failureDetail, taskId: task.id)
        strongSelf.notificationCenter.post(
            name: .iterableTaskFinishedWithNoRetry,
            object: strongSelf,
            userInfo: userInfo
        )
    }
    fulfill.resolve(with: .failure)
}

6.5 Promise Resolution

NotificationListener.resolveTask():

private func resolveTask(value: TaskSendRequestValue) {
    pendingTasksQueue.async { [weak self] in
        let taskId = value.taskId
        ITBInfo("task: \(taskId) finished with success")
        
        // Look up the stored promise
        if let fulfill = self?.pendingTasksMap[taskId] {
            // RESOLVE THE ORIGINAL PROMISE
            fulfill.resolve(with: value.sendRequestValue)
            self?.pendingTasksMap.removeValue(forKey: taskId)
        } else {
            ITBError("could not find fulfill for taskId: \(taskId)")
        }
    }
}

6.6 Complete Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│  T=0: IterableAPI.track("purchase")                                         │
│       │                                                                      │
│       ▼                                                                      │
│  OfflineRequestProcessor.sendIterableRequest()                              │
│       │                                                                      │
│       ├─► taskScheduler.schedule() → taskId: "uuid-abc-123"                 │
│       │                                                                      │
│       └─► notificationListener.futureFromTask("uuid-abc-123")               │
│               │                                                              │
│               └─► pendingTasksMap["uuid-abc-123"] = Fulfill<>()             │
│                                                                              │
│           Returns: Pending<SendRequestValue, SendRequestError>               │
│                         │                                                    │
│                         ▼                                                    │
│  Caller stores promise: promise.onSuccess { print("Done!") }                │
│                                                                              │
│  ═══════════════════════════════════════════════════════════════════════════│
│  T=5min: Network comes online                                                │
│                                                                              │
│  IterableTaskRunner.processTasks()                                          │
│       │                                                                      │
│       ├─► persistenceContext.nextTask() → task.id = "uuid-abc-123"          │
│       │                                                                      │
│       ├─► IterableAPICallTaskProcessor.process(task)                        │
│       │       │                                                              │
│       │       └─► HTTP POST to api.iterable.com/events/track                │
│       │               │                                                      │
│       │               └─► 200 OK, response data                             │
│       │                                                                      │
│       └─► notificationCenter.post(.iterableTaskFinishedWithSuccess,         │
│               userInfo: { taskId: "uuid-abc-123", data: {...} })            │
│                                                                              │
│  NotificationListener.onTaskFinishedWithSuccess()                           │
│       │                                                                      │
│       ├─► Extract taskId "uuid-abc-123" from notification                   │
│       │                                                                      │
│       └─► pendingTasksMap["uuid-abc-123"]?.resolve(with: data)              │
│                                                                              │
│  ═══════════════════════════════════════════════════════════════════════════│
│  Caller's .onSuccess { print("Done!") } IS NOW INVOKED                      │
└─────────────────────────────────────────────────────────────────────────────┘

6.7 Edge Case: App Restart

If the app is killed and restarted, the promises in pendingTasksMap are lost. However:

• Tasks persist in CoreData
• They will be processed when the app restarts
• But there's no callback to the original caller (they no longer exist)

This is an acceptable trade-off since:

1. The event data is not lost
2. Fire-and-forget analytics don't typically need callbacks
3. The alternative (persisting callbacks) would be complex and error-prone

---

Summary

Aspect	Key Implementation	File Location
Transparent Queuing	RequestHandler.chooseRequestProcessor()	RequestHandler.swift:376-396
FIFO Processing	CoreDataPersistenceContext.nextTask() with scheduledAt sort	IterableCoreDataPersistence.swift:132-139
Persistence	PersistentContainer with SQLite backing	IterableCoreDataPersistence.swift:24-79
Health Monitoring	HealthMonitor.canSchedule() with circuit breaker	HealthMonitor.swift:58-85
Dual Connectivity	NWPathMonitor + NetworkConnectivityChecker	NetworkMonitor.swift, NetworkConnectivityChecker.swift
Promise Continuity	NotificationListener.pendingTasksMap	OfflineRequestProcessor.swift:420-501

[RGG-jayoung]

Deep Dive: JWT Authentication Flow

This deep dive covers the complete JWT (JSON Web Token) authentication system in the Iterable Swift SDK, including token acquisition, refresh, retry mechanisms, and failure handling.

---

1. Architecture Overview

┌────────────────────────────────────────────────────────────────────────────────┐
│                              App Developer                                      │
│  ┌──────────────────────────────────────────────────────────────────────────┐  │
│  │  class MyAuthDelegate: IterableAuthDelegate {                             │  │
│  │      func onAuthTokenRequested(completion: @escaping (String?) -> Void) { │  │
│  │          // Fetch JWT from your backend                                   │  │
│  │          myBackend.getJWT { token in completion(token) }                  │  │
│  │      }                                                                    │  │
│  │      func onAuthFailure(_ failure: AuthFailure) {                         │  │
│  │          // Handle failure (e.g., log out user)                           │  │
│  │      }                                                                    │  │
│  │  }                                                                        │  │
│  └──────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────┬─────────────────────────────────┘
                                               │
                                               ▼
┌────────────────────────────────────────────────────────────────────────────────┐
│                             Iterable SDK                                        │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │                          AuthManager                                    │    │
│  │  - Requests tokens via delegate                                        │    │
│  │  - Decodes JWT expiration                                              │    │
│  │  - Schedules proactive refresh                                         │    │
│  │  - Implements retry with backoff                                       │    │
│  │  - Stores token in Keychain                                            │    │
│  └─────────────────────────┬──────────────────────────────────────────────┘    │
│                            │                                                    │
│  ┌─────────────────────────▼──────────────────────────────────────────────┐    │
│  │                     RequestProcessorUtil                                │    │
│  │  - Intercepts 401 responses                                            │    │
│  │  - Triggers token refresh on JWT errors                                │    │
│  │  - Retries failed requests with new token                              │    │
│  └─────────────────────────┬──────────────────────────────────────────────┘    │
│                            │                                                    │
│  ┌─────────────────────────▼──────────────────────────────────────────────┐    │
│  │                   IterableAPICallRequest                                │    │
│  │  - Injects "Authorization: Bearer <token>" header                      │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────────────────────────────────┘

---

2. Configuration

2.1 IterableConfig Settings

IterableConfig.swift:126-172

public class IterableConfig: NSObject {
    /// Implement this protocol to enable token-based authentication
    public weak var authDelegate: IterableAuthDelegate?
    
    /// How long before expiration to refresh the token (seconds)
    /// Default: 60 seconds
    public var expiringAuthTokenRefreshPeriod: TimeInterval = 60.0
    
    /// Retry policy for JWT refresh failures
    /// Default: 10 retries, 6 second interval, linear backoff
    public var retryPolicy: RetryPolicy = RetryPolicy(
        maxRetry: 10, 
        retryInterval: 6, 
        retryBackoff: .linear
    )
}

2.2 IterableAuthDelegate Protocol

IterableConfig.swift:91-94

@objc public protocol IterableAuthDelegate: AnyObject {
    /// Called when the SDK needs a new JWT token
    @objc func onAuthTokenRequested(completion: @escaping AuthTokenRetrievalHandler)
    
    /// Called when authentication fails
    @objc func onAuthFailure(_ authFailure: AuthFailure)
}

// Type alias for the completion handler
public typealias AuthTokenRetrievalHandler = (String?) -> Void

2.3 RetryPolicy Configuration

RetryPolicy.swift:11-38

public class RetryPolicy {
    /// Max consecutive retries before giving up (default: 10)
    var maxRetry: Int
    
    /// Base interval between retries in seconds (default: 6)
    var retryInterval: Double
    
    /// Backoff pattern: .linear or .exponential
    var retryBackoff: BackoffType
    
    public enum BackoffType {
        case linear       // Same interval each retry
        case exponential  // Doubles each retry
    }
}

Exponential Backoff Formula:

// Constants.swift:28
static let exponentialFactor = 2.0

// AuthManager.swift:134-141
func getNextRetryInterval() -> Double {
    var nextRetryInterval = Double(authRetryPolicy.retryInterval)
    if authRetryPolicy.retryBackoff == .exponential {
        nextRetryInterval = nextRetryInterval * pow(2.0, Double(retryCount - 1))
    }
    return nextRetryInterval
}

Example intervals with exponential backoff (base 6s):

Retry #	Interval
1	6s
2	12s
3	24s
4	48s
5	96s
...	...

---

3. Token Lifecycle

3.1 Initial Token Acquisition

When setEmail() or setUserId() is called:

InternalIterableAPI.swift:889-915

private func onLogin(_ authToken: String? = nil, onloginSuccess: (()->())? = nil) {
    guard isSDKInitialized() else { return }
    
    // Reset retry state for new login
    self.authManager.pauseAuthRetries(false)
    
    if let authToken {
        // Token provided directly by app
        self.authManager.setNewToken(authToken)
        completeUserLogin(onloginSuccessCallBack: onloginSuccess)
    } else if isEitherUserIdOrEmailSet() && config.authDelegate != nil {
        // Request token from delegate
        requestNewAuthToken(onloginSuccessCallBack: onloginSuccess)
    } else {
        // No auth delegate configured, proceed without JWT
        completeUserLogin(onloginSuccessCallBack: onloginSuccess)
    }
}

private func requestNewAuthToken(onloginSuccessCallBack: (()->())? = nil) {
    authManager.requestNewAuthToken(
        hasFailedPriorAuth: false, 
        onSuccess: { [weak self] token in
            if token != nil {
                self?.completeUserLogin(onloginSuccessCallBack: onloginSuccessCallBack)
            }
        }, 
        shouldIgnoreRetryPolicy: true  // First request always goes through
    )
}

3.2 Token Storage

Tokens are stored securely in the iOS Keychain:

LocalStorage.swift:39-44

var authToken: String? {
    get { keychain.authToken }
    set { keychain.authToken = newValue }
}

Migration from UserDefaults:

private func moveAuthDataFromUserDefaultsToKeychain() {
    // Migrates email, userId, authToken from UserDefaults to Keychain
    // for security (keychain is encrypted, UserDefaults is not)
}

3.3 Token Injection into Requests

IterableAPICallRequest.swift:61-75

private func createIterableHeaders(sentAt: Date, processorType: ProcessorType) -> [String: String] {
    var headers = [
        JsonKey.contentType: JsonValue.applicationJson,
        JsonKey.Header.sdkPlatform: JsonValue.iOS,
        JsonKey.Header.sdkVersion: IterableAPI.sdkVersion,
        JsonKey.Header.apiKey: apiKey,
        JsonKey.Header.sentAt: Self.format(sentAt: sentAt),
        JsonKey.Header.requestProcessor: Self.name(for: processorType)
    ]
    
    // Add JWT Bearer token if available
    if let authToken = authToken {
        headers[JsonKey.Header.authorization] = "Bearer \(authToken)"
    }
    
    return headers
}

---

4. Proactive Token Refresh

4.1 JWT Expiration Decoding

AuthManager.swift:281-300

static func decodeExpirationDateFromAuthToken(_ authToken: String) -> Int? {
    // JWT format: header.payload.signature
    let components = authToken.components(separatedBy: ".")
    guard components.count > 1 else { return nil }
    
    let encodedPayload = components[1]
    
    // Fix base64 padding
    let remaining = encodedPayload.count % 4
    let fixedEncodedPayload = encodedPayload + String(repeating: "=", count: (4 - remaining) % 4)
    
    // Decode and extract "exp" field
    guard let decoded = Data(base64Encoded: fixedEncodedPayload),
          let serialized = try? JSONSerialization.jsonObject(with: decoded) as? [String: Any],
          let payloadExpTime = serialized[JsonKey.JWT.exp] as? Int else {
        return nil
    }
    
    return payloadExpTime  // Unix timestamp
}

4.2 Scheduling Proactive Refresh

AuthManager.swift:191-211

private func queueAuthTokenExpirationRefresh(_ authToken: String?, onSuccess: AuthTokenRetrievalHandler? = nil) -> Bool {
    clearRefreshTimer()
    
    guard let authToken = authToken, 
          let expirationDate = AuthManager.decodeExpirationDateFromAuthToken(authToken) else {
        // Invalid token, schedule retry
        handleAuthFailure(failedAuthToken: authToken, reason: .authTokenPayloadInvalid)
        scheduleAuthTokenRefreshTimer(interval: getNextRetryInterval(), successCallback: onSuccess)
        return false
    }
    
    // Calculate when to refresh: expiration - current - buffer
    let timeIntervalToRefresh = TimeInterval(expirationDate) 
                              - dateProvider.currentDate.timeIntervalSince1970 
                              - expirationRefreshPeriod  // Default 60 seconds before expiry
    
    if timeIntervalToRefresh > 0 {
        scheduleAuthTokenRefreshTimer(interval: timeIntervalToRefresh, 
                                      isScheduledRefresh: true, 
                                      successCallback: onSuccess)
        return true
    }
    return false
}

4.3 Refresh Timer Execution

AuthManager.swift:213-243

func scheduleAuthTokenRefreshTimer(interval: TimeInterval, 
                                   isScheduledRefresh: Bool = false, 
                                   successCallback: AuthTokenRetrievalHandler? = nil) {
    // Prevent duplicate timers
    if isTimerScheduled && !isScheduledRefresh {
        addPendingCallback(successCallback)
        return
    }
    
    if shouldSkipTokenRefresh(isScheduledRefresh: isScheduledRefresh) {
        return
    }
    
    addPendingCallback(successCallback)
    
    expirationRefreshTimer = Timer.scheduledTimer(withTimeInterval: interval, repeats: false) { [weak self] _ in
        self?.isTimerScheduled = false
        
        if self?.localStorage.email != nil || self?.localStorage.userId != nil {
            self?.requestNewAuthToken(
                hasFailedPriorAuth: false, 
                onSuccess: { [weak self] token in
                    self?.invokePendingCallbacks(with: token)
                }, 
                shouldIgnoreRetryPolicy: isScheduledRefresh
            )
        } else {
            ITBDebug("Email or userId is not available. Skipping token refresh")
            self?.clearPendingCallbacks()
        }
    }
    
    isTimerScheduled = true
}

---

5. Reactive Token Refresh (401 Handling)

5.1 Request Interceptor

RequestProcessorUtil.swift:8-44

static func sendRequest(requestProvider: @escaping () -> Pending<SendRequestValue, SendRequestError>,
                        successHandler onSuccess: OnSuccessHandler? = nil,
                        failureHandler onFailure: OnFailureHandler? = nil,
                        authManager: IterableAuthManagerProtocol? = nil,
                        requestIdentifier identifier: String) -> Pending<SendRequestValue, SendRequestError> {
    
    let result = Fulfill<SendRequestValue, SendRequestError>()

    func attemptSend() {
        requestProvider().onSuccess { json in
            // Success: reset retry state
            resetAuthRetries(authManager: authManager, requestIdentifier: identifier)
            reportSuccess(result: result, value: json, successHandler: onSuccess, identifier: identifier)
        }
        .onError { error in
            // Check for JWT-specific 401 errors
            if error.httpStatusCode == 401, matchesJWTErrorCode(error.iterableCode) {
                ITBError("invalid JWT token, trying again: \(error.reason ?? "")")
                
                // Notify delegate of failure
                authManager?.handleAuthFailure(
                    failedAuthToken: authManager?.getAuthToken(), 
                    reason: getMappedErrorCodeForMessage(error.reason ?? "")
                )
                authManager?.setIsLastAuthTokenValid(false)
                
                // Schedule retry with backoff
                let retryInterval = authManager?.getNextRetryInterval() ?? 1
                DispatchQueue.main.async {
                    authManager?.scheduleAuthTokenRefreshTimer(
                        interval: retryInterval, 
                        isScheduledRefresh: false, 
                        successCallback: { _ in
                            attemptSend()  // Retry the original request
                        }
                    )
                }
            } else if error.httpStatusCode == 401, error.iterableCode == JsonValue.Code.badApiKey {
                // Bad API key - don't retry
                ITBError(error.reason)
                reportFailure(result: result, error: error, failureHandler: onFailure, identifier: identifier)
            } else {
                // Other errors - don't retry
                ITBError(error.reason)
                reportFailure(result: result, error: error, failureHandler: onFailure, identifier: identifier)
            }
        }
    }
    
    attemptSend()
    return result
}

5.2 JWT Error Code Detection

RequestProcessorUtil.swift:155-157

public static func matchesJWTErrorCode(_ errorCode: String?) -> Bool {
    return errorCode == JsonValue.Code.invalidJwtPayload 
        || errorCode == JsonValue.Code.badAuthorizationHeader 
        || errorCode == JsonValue.Code.jwtUserIdentifiersMismatched
}

Iterable Error Codes:

// Constants.swift:384-389
enum Code {
    static let badApiKey = "BadApiKey"
    static let invalidJwtPayload = "InvalidJwtPayload"
    static let badAuthorizationHeader = "BadAuthorizationHeader"
    static let jwtUserIdentifiersMismatched = "JwtUserIdentifiersMismatched"
}

5.3 Error Message to Reason Mapping

RequestProcessorUtil.swift:87-109

public static func getMappedErrorCodeForMessage(_ reason: String) -> AuthFailureReason {
    switch reason.lowercased() {
        case "exp must be less than 1 year from iat":
            return .authTokenExpirationInvalid
        case "jwt format is invalid":
            return .authTokenFormatInvalid
        case "jwt token is expired":
            return .authTokenExpired
        case "jwt is invalid":
            return .authTokenSignatureInvalid
        case "jwt payload requires a value for userid or email", "email could not be found":
            return .authTokenUserKeyInvalid
        case "jwt token has been invalidated":
            return .authTokenInvalidated
        case "invalid payload":
            return .authTokenPayloadInvalid
        case "jwt authorization header is not set":
            return .authTokenMissing
        default:
            return .authTokenGenericError
    }
}

---

6. Auth Failure Handling

6.1 AuthFailure Model

AuthFailure.swift:10-33

@objcMembers public class AuthFailure: NSObject {
    /// userId or email of the signed-in user
    public let userKey: String?
    
    /// The authToken which caused the failure
    public let failedAuthToken: String?
    
    /// Unix timestamp of the failed request
    public let failedRequestTime: Int
    
    /// Indicates the reason for failure
    public let failureReason: AuthFailureReason
}

6.2 AuthFailureReason Enum

AuthFailureReason.swift:10-22

@objc public enum AuthFailureReason: Int {
    case authTokenExpired           // Token past expiration
    case authTokenGenericError      // Unknown error
    case authTokenExpirationInvalid // exp > 1 year from iat
    case authTokenSignatureInvalid  // Signature verification failed
    case authTokenFormatInvalid     // Not valid JWT format
    case authTokenInvalidated       // Token revoked server-side
    case authTokenPayloadInvalid    // Missing required claims
    case authTokenUserKeyInvalid    // email/userId mismatch
    case authTokenNull              // Delegate returned nil
    case authTokenGenerationError   // Delegate threw error
    case authTokenMissing           // No Authorization header
}

6.3 Delegate Notification

AuthManager.swift:187-189

func handleAuthFailure(failedAuthToken: String?, reason: AuthFailureReason) {
    delegate?.onAuthFailure(
        AuthFailure(
            userKey: IterableUtil.getEmailOrUserId(), 
            failedAuthToken: failedAuthToken, 
            failedRequestTime: IterableUtil.secondsFromEpoch(for: dateProvider.currentDate), 
            failureReason: reason
        )
    )
}

---

7. Retry State Machine

7.1 State Variables

AuthManager.swift:105-118

private var authToken: String?
private var expirationRefreshTimer: Timer?

private var pendingAuth: Bool = false        // Request in flight
private var hasFailedPriorAuth: Bool = false // Last attempt failed

private var authRetryPolicy: RetryPolicy
private var retryCount: Int = 0              // Current retry attempt
private var isLastAuthTokenValid: Bool = false
private var pauseAuthRetry: Bool = false     // Stop all retries
private var isTimerScheduled: Bool = false   // Timer active

private var pendingSuccessCallbacks: [AuthTokenRetrievalHandler] = []

7.2 Request Guards

AuthManager.swift:40-63

func requestNewAuthToken(hasFailedPriorAuth: Bool = false,
                         onSuccess: AuthTokenRetrievalHandler? = nil,
                         shouldIgnoreRetryPolicy: Bool) {
    
    // Guard 1: Paused or max retries reached
    if shouldPauseRetry(shouldIgnoreRetryPolicy) || pendingAuth || hasFailedAuth(hasFailedPriorAuth) {
        return
    }
    
    self.hasFailedPriorAuth = hasFailedPriorAuth
    pendingAuth = true
    
    // Guard 2: Use cached valid token
    if shouldUseLastValidToken(shouldIgnoreRetryPolicy) {
        onAuthTokenReceived(retrievedAuthToken: authToken, onSuccess: onSuccess)
        return
    }
    
    // Request from delegate
    delegate?.onAuthTokenRequested { [weak self] retrievedAuthToken in
        self?.pendingAuth = false
        self?.retryCount += 1
        self?.onAuthTokenReceived(retrievedAuthToken: retrievedAuthToken, onSuccess: onSuccess)
    }
}

private func shouldPauseRetry(_ shouldIgnoreRetryPolicy: Bool) -> Bool {
    return (!shouldIgnoreRetryPolicy && pauseAuthRetry) ||
           (retryCount >= authRetryPolicy.maxRetry && !shouldIgnoreRetryPolicy)
}

private func shouldUseLastValidToken(_ shouldIgnoreRetryPolicy: Bool) -> Bool {
    return isLastAuthTokenValid && !shouldIgnoreRetryPolicy
}

7.3 Retry Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              REQUEST FLOW                                        │
│                                                                                  │
│   ┌─────────────┐                                                               │
│   │  API Call   │                                                               │
│   └──────┬──────┘                                                               │
│          │                                                                       │
│          ▼                                                                       │
│   ┌─────────────────────────────────────────────────────────────────┐           │
│   │  RequestProcessorUtil.sendRequest()                              │           │
│   │  - Adds "Authorization: Bearer <token>" header                   │           │
│   └──────┬──────────────────────────────────────────────────────────┘           │
│          │                                                                       │
│          ▼                                                                       │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────┐             │
│   │   HTTP      │───▶│   200 OK    │───▶│  Reset retry state      │             │
│   │  Request    │    └─────────────┘    │  Invoke success handler │             │
│   └──────┬──────┘                        └─────────────────────────┘             │
│          │                                                                       │
│          │  401 + JWT error code                                                │
│          ▼                                                                       │
│   ┌─────────────────────────────────────────────────────────────────┐           │
│   │  1. authManager.handleAuthFailure() → notifies delegate         │           │
│   │  2. authManager.setIsLastAuthTokenValid(false)                  │           │
│   │  3. Calculate next retry interval                               │           │
│   │  4. Schedule refresh timer                                      │           │
│   └──────┬──────────────────────────────────────────────────────────┘           │
│          │                                                                       │
│          │  Timer fires                                                         │
│          ▼                                                                       │
│   ┌─────────────────────────────────────────────────────────────────┐           │
│   │  authManager.requestNewAuthToken()                              │           │
│   │                                                                  │           │
│   │  Guards:                                                         │           │
│   │  ├── pauseAuthRetry == true? → STOP                             │           │
│   │  ├── retryCount >= maxRetry? → STOP                             │           │
│   │  ├── pendingAuth == true? → SKIP                                │           │
│   │  └── isLastAuthTokenValid == true? → USE CACHED                 │           │
│   └──────┬──────────────────────────────────────────────────────────┘           │
│          │                                                                       │
│          ▼                                                                       │
│   ┌─────────────────────────────────────────────────────────────────┐           │
│   │  delegate?.onAuthTokenRequested { token in ... }                │           │
│   │                                                                  │           │
│   │  retryCount += 1                                                │           │
│   │                                                                  │           │
│   │  if token != nil:                                               │           │
│   │    - Store in keychain                                          │           │
│   │    - Queue expiration refresh                                   │           │
│   │    - Retry original request ←──────────────────────┐            │           │
│   │  else:                                              │            │           │
│   │    - handleAuthFailure(.authTokenNull)              │            │           │
│   │    - Schedule another retry timer ─────────────────┘            │           │
│   └─────────────────────────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────────────────────────┘

---

8. Logout and Cleanup

AuthManager.swift:84-101

func logoutUser() {
    ITBInfo()
    
    // Clear token
    authToken = nil
    storeAuthToken()  // Saves nil to keychain
    
    // Cancel timers
    clearRefreshTimer()
    clearPendingCallbacks()

    // Clear unknown user data
    if localStorage.email != nil || localStorage.userId != nil || localStorage.userIdUnknownUser != nil {
        localStorage.unknownUserEvents = nil
        localStorage.unknownUserSessions = nil
        localStorage.unknownUserUpdate = nil
    }

    // Reset state
    isLastAuthTokenValid = false
}

---

9. Summary Table

Component	Location	Responsibility
IterableAuthDelegate	IterableConfig.swift:91-94	App-provided token fetcher
RetryPolicy	RetryPolicy.swift	Retry configuration
AuthManager	AuthManager.swift	Token lifecycle management
RequestProcessorUtil	RequestProcessorUtil.swift	401 interception & retry
AuthFailure	AuthFailure.swift	Failure info model
AuthFailureReason	AuthFailureReason.swift	Failure reason enum
LocalStorage	LocalStorage.swift	Keychain persistence

---

10. Best Practices for Implementation

10.1 Delegate Implementation

class MyAuthDelegate: IterableAuthDelegate {
    func onAuthTokenRequested(completion: @escaping (String?) -> Void) {
        // IMPORTANT: Call completion even on failure (pass nil)
        myBackend.fetchJWT(for: currentUserId) { result in
            switch result {
            case .success(let token):
                completion(token)
            case .failure:
                completion(nil)  // Don't throw, pass nil
            }
        }
    }
    
    func onAuthFailure(_ authFailure: AuthFailure) {
        // Log the failure
        analytics.track("auth_failure", [
            "reason": authFailure.failureReason.rawValue,
            "user": authFailure.userKey ?? "unknown"
        ])
        
        // For persistent failures, consider logging out
        if authFailure.failureReason == .authTokenInvalidated {
            // Token was revoked server-side
            logOutUser()
        }
    }
}

10.2 JWT Requirements

Your JWT should include:

• exp: Expiration timestamp (required for proactive refresh)
• email or userId: Must match the user set in SDK
• Signature: Verified by Iterable's backend

10.3 Configuration Recommendations

let config = IterableConfig()
config.authDelegate = MyAuthDelegate()
config.expiringAuthTokenRefreshPeriod = 60  // Refresh 1 min before expiry
config.retryPolicy = RetryPolicy(
    maxRetry: 5,       // Reduce if your backend has strict rate limits
    retryInterval: 10, // Increase if backend needs recovery time
    retryBackoff: .exponential  // Use exponential for production
)

[RGG-jayoung]

Deep Dive: In-App Messaging System

Overview

The Iterable SDK in-app messaging system enables displaying rich HTML messages to users within the app. It encompasses message fetching from servers, local persistence, display logic, user interaction tracking, and an inbox feature for persistent messages.

---

1. Architecture Components

┌─────────────────────────────────────────────────────────────────────────────┐
│                         In-App Messaging Architecture                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────┐    ┌──────────────────┐    ┌────────────────────────┐ │
│  │   InAppManager  │───▶│   InAppFetcher   │───▶│  ApiClient.getInApp()  │ │
│  │   (Orchestrator)│    │                  │    │                        │ │
│  └────────┬────────┘    └──────────────────┘    └────────────────────────┘ │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────┐    ┌──────────────────┐                               │
│  │  MessageParser  │───▶│  ContentParser   │                               │
│  │                 │    │  (HTML/Padding)  │                               │
│  └────────┬────────┘    └──────────────────┘                               │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                       MessagesProcessor                              │   │
│  │  • Priority ordering (priorityLevel)                                │   │
│  │  • Trigger evaluation (immediate/event/never)                       │   │
│  │  • Delegate consultation (onNew)                                    │   │
│  │  • Display eligibility check                                        │   │
│  └────────┬────────────────────────────────────────────────────────────┘   │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────┐    ┌──────────────────┐    ┌────────────────────────┐ │
│  │  InAppDisplayer │───▶│   InAppPresenter │───▶│  HtmlMessageVC         │ │
│  │                 │    │  (Timing/Delay)  │    │  (WKWebView)           │ │
│  └─────────────────┘    └──────────────────┘    └────────────────────────┘ │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                       Persistence Layer                              │   │
│  │  InAppFilePersister → itbl_inapp.json (Application Support)         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

2. InAppManager - The Central Orchestrator

Location: swift-sdk/Internal/in-app/InAppManager.swift

The InAppManager is the central coordinator for all in-app messaging operations:

class InAppManager {
    // Key dependencies
    private let requestHandler: RequestHandlerProtocol?
    private let deviceMetadata: DeviceMetadata
    private var fetcher: InAppFetcherProtocol
    private let displayer: InAppDisplayerProtocol
    private let persister: InAppPersistenceProtocol
    
    // Message state
    private var messagesMap = OrderedDictionary<String, IterableInAppMessage>()
    private var lastSyncTime: Date?
    
    // Auto-display control
    var isAutoDisplayPaused: Bool = false
}

Key Lifecycle Methods:

Method	Purpose
start()	Begins the in-app system, loads persisted messages, syncs with server
scheduleSync()	Schedules a fetch from server (silent push triggered)
show(message:)	Displays a specific message immediately
remove(message:)	Removes and consumes a message
onInAppRemoved(messageId:)	Handles server-side message removal

---

3. Message Data Model

Location: swift-sdk/Core/Models/IterableInAppMessage.swift

@objcMembers public final class IterableInAppMessage: NSObject {
    public let messageId: String           // Unique identifier
    public let campaignId: NSNumber?       // Associated campaign
    public let trigger: IterableInAppTrigger  // Display trigger type
    public let createdAt: Date?            // Creation timestamp
    public let expiresAt: Date?            // Expiration timestamp
    public let content: IterableInAppContent  // HTML content + styling
    public let saveToInbox: Bool           // Persist to inbox
    public let inboxMetadata: IterableInboxMetadata?  // Inbox display info
    public let customPayload: [AnyHashable: Any]?     // Custom data
    public let priorityLevel: Double       // Display priority (lower = higher priority)
    public let jsonOnly: Bool              // Data-only message (no display)
    
    // Mutable state
    var didProcessTrigger: Bool = false    // Already evaluated for display
    var consumed: Bool = false             // Marked for deletion
    public internal(set) var read: Bool    // User has seen this
}

Trigger Types:

Type	Behavior
.immediate	Show as soon as available (default)
.event	Show in response to specific events (push-to-in-app)
.never	Never auto-display; manual show only

---

4. Message Fetching & Parsing

InAppFetcher (InAppInternal.swift:28-58):

class InAppFetcher: InAppFetcherProtocol {
    func fetch() -> Pending<[IterableInAppMessage], Error> {
        // Fetches up to 100 messages from server
        InAppHelper.getInAppMessagesFromServer(
            apiClient: apiClient,
            authManager: authManager,
            number: numMessages  // 100
        )
    }
}

InAppMessageParser - Parses server JSON:

struct InAppMessageParser {
    static func parse(payload: [AnyHashable: Any]) -> [Result<IterableInAppMessage, ParseError>] {
        // 1. Extract inAppMessages array
        // 2. Pre-process JSON (move saveToInbox, trigger from customPayload)
        // 3. Parse each message, consume failures
    }
}

Content Parsing (InAppContentParser.swift):

• Parses HTML content with display settings
• Extracts padding configuration (top/bottom: AutoExpand or percentage, left/right: percentage)
• Validates href tags exist in HTML
• Parses background color and animation settings

struct HtmlContentParser {
    static func tryCreate(from json: [AnyHashable: Any]) -> InAppContentParseResult {
        guard let html = json[JsonKey.html] as? String else {
            return .failure(reason: "no html")
        }
        guard html.range(of: Const.href) \!= nil else {
            return .failure(reason: "No href tag found")
        }
        // Parse padding, animation, backgroundColor...
    }
}

---

5. Message Processing & Display Logic

MessagesProcessor (InAppManager+Functions.swift):

struct MessagesProcessor {
    mutating func processMessages() -> MessagesProcessorResult {
        switch processNextMessage() {
        case .show(message):
            // Mark processed, consume if not inbox
            return .show(message: message, messagesMap: messagesMap)
        case .skip(message):
            // Delegate said skip, try next
            return processMessages()  // Recursive
        case .skipAndConsume(message):
            // JSON-only message, consume immediately
            return .noShow(message: message, messagesMap: messagesMap)
        case .none, .wait:
            return .noShow(message: nil, messagesMap: messagesMap)
        }
    }
}

Processing Order:

1. Filter to unprocessed, immediate-trigger, unread messages
2. Sort by priorityLevel (ascending - lower number = higher priority)
3. Check isOkToShowNow (not already showing, not paused)
4. Consult delegate via onNew(message:)
5. Show or skip based on delegate response

Display Eligibility Checks:

func isOkToShowNow(message: IterableInAppMessage) -> Bool {
    \!isAutoDisplayPaused &&           // Auto-display enabled
    \!displayer.isShowingInApp() &&    // No message currently shown
    \!message.didProcessTrigger        // Not already processed
}

---

6. Display Presentation

InAppDisplayer (InAppDisplayer.swift):

class InAppDisplayer: InAppDisplayerProtocol {
    @discardableResult
    static func showIterableHtmlMessage(_ htmlString: String,
                                        messageMetadata: IterableInAppMessageMetadata?,
                                        padding: Padding,
                                        onClickCallback: ((URL) -> Void)?) -> ShowResult {
        guard \!InAppPresenter.isPresenting else {
            return .notShown("In-app notification is being presented.")
        }
        guard InAppDisplayer.getTopViewController() \!= nil else {
            return .notShown("No top view controller.")
        }
        
        let htmlMessageVC = IterableHtmlMessageViewController.create(...)
        let presenter = InAppPresenter(htmlMessageViewController: htmlMessageVC)
        presenter.show()
        return .shown
    }
}

InAppPresenter - Handles timing/delays:

class InAppPresenter {
    static var isPresenting = false  // Prevents concurrent displays
    
    func show() {
        InAppPresenter.isPresenting = true
        // Start 0.75s delay timer for webview to load
        delayTimer = Timer.scheduledTimer(withTimeInterval: maxDelay) { _ in
            self.presentAfterDelayValidation()
        }
    }
    
    func webViewDidFinish() {
        // Cancel timer early if webview loaded
        delayTimer?.invalidate()
        presentAfterDelayValidation()
    }
}

IterableHtmlMessageViewController - The actual UI:

class IterableHtmlMessageViewController: UIViewController {
    // Uses WKWebView to render HTML
    // Tracks in-app open/close/click events
    // Handles URL interception for custom actions
    
    // Location types: .full, .top, .center, .bottom
    // Animation support for entrance/exit
}

---

7. URL Handling & Actions

InAppHelper.InAppClickedUrl - Categorizes clicked URLs:

URL Type	Pattern	Handling
localResource	applewebdata://	Resource name extraction
iterableCustomAction	iterable://something	Custom Iterable action
customAction	action:// or itbl://	App-defined custom action
regularUrl	https://	Standard URL handling

static func parse(inAppUrl url: URL) -> InAppClickedUrl? {
    switch scheme {
    case .applewebdata:
        return .localResource(name: urlPath)
    case .iterable:
        return .iterableCustomAction(name: dropScheme(url))
    case .action, .itbl:
        return .customAction(name: dropScheme(url))
    case .other:
        return .regularUrl(url)
    }
}

---

8. Persistence Layer

InAppFilePersister - JSON file-based persistence:

class InAppFilePersister: InAppPersistenceProtocol {
    // Stores in: Application Support/itbl_inapp.json
    
    func getMessages() -> [IterableInAppMessage] {
        guard let data = FileHelper.read(filename: filename, ext: ext) else {
            return []
        }
        return try? JSONDecoder().decode([IterableInAppMessage].self, from: data)
    }
    
    func persist(_ messages: [IterableInAppMessage]) {
        guard let encoded = try? JSONEncoder().encode(messages) else { return }
        FileHelper.write(filename: filename, ext: ext, data: encoded)
    }
}

IterableInAppMessage Codable - Full serialization support:

• Encodes/decodes all properties including mutable state
• Handles custom payload via JSON serialization
• Preserves trigger dictionaries
• Codable color conversion for backgroundColor

---

9. Server Synchronization

MessagesObtainedHandler - Merges server messages with local:

struct MessagesObtainedHandler {
    func handle() -> MergeMessagesResult {
        // Find removed messages (in local, not in server)
        // Find added messages (in server, not in local)
        // Selective overwrite: only if server.read && \!client.read
        // Track inbox changes
        
        return MergeMessagesResult(
            inboxChanged: removedInboxCount + addedInboxCount > 0,
            messagesMap: newMessagesMap,
            deliveredMessages: addedMessages.filter { \!$0.read }
        )
    }
}

Sync triggers:

1. App launch (start())
2. Silent push notification (scheduleSync())
3. User identity change
4. Manual refresh

---

10. Delegate Protocol

IterableInAppDelegate - App controls display decisions:

@objc public protocol IterableInAppDelegate {
    func onNew(message: IterableInAppMessage) -> InAppShowResponse
}

// Default implementation
@objcMembers open class DefaultInAppDelegate: IterableInAppDelegate {
    open func onNew(message: IterableInAppMessage) -> InAppShowResponse {
        return .show  // Always show by default
    }
}

InAppShowResponse:

• .show - Display the in-app immediately
• .skip - Skip this message, continue to next

---

11. Analytics Tracking

Events Tracked:

Event	Trigger	Data
trackInAppOpen	Message displayed	messageId, location, inboxSessionId
trackInAppClick	User clicks link	messageId, location, clickedUrl
trackInAppClose	Message dismissed	messageId, location, source (back/link)
track(inAppDelivery:)	New message received	Full message metadata
inAppConsume	Message consumed	messageId

Close Sources:

• .back - User navigated back
• .link - User clicked a link

---

12. Inbox Feature

Messages with saveToInbox: true are persisted and accessible via:

public protocol IterableInAppManagerProtocol {
    func getMessages() -> [IterableInAppMessage]        // All messages
    func getInboxMessages() -> [IterableInAppMessage]   // Inbox only
    func getUnreadInboxMessagesCount() -> Int           // Unread count
    func set(read: Bool, forMessage: IterableInAppMessage)  // Mark read
}

Inbox Change Notifications:

// Posted when inbox content changes
NotificationCenter.default.post(name: .iterableInboxChanged, object: nil)

---

13. JSON-Only Messages

Messages with jsonOnly: true:

• Carry data in customPayload without display
• Auto-consumed after processing
• saveToInbox forced to false
• HTML content set to empty string
• Useful for data-only push notifications

---

14. Error Handling

Parse Failures:

enum ParseError: Error {
    case parseFailed(reason: String, messageId: String?)
}

When parsing fails:

1. Error logged via ITBError(reason)
2. If messageId available, message auto-consumed on server
3. Processing continues with remaining messages

Display Failures (ShowResult):

• .shown - Successfully displayed
• .notShown(String) - Failed with reason:
  • "In-app notification is being presented."
  • "No top view controller."
  • "Invalid content type"
  • "No message available for display validation."

---

15. Security Considerations

JavaScript Disabled:

@available(iOS 14.0, *)
preferences.allowsContentJavaScript = false

URL Validation:

• Scheme validation before processing
• Invalid schemes logged as errors
• Local resource access detected and handled

---

Key Files Reference

File	Purpose
InAppManager.swift	Central orchestrator (686 lines)
InAppManager+Functions.swift	Message processing logic
InAppDisplayer.swift	Display coordination
InAppPresenter.swift	Presentation timing
InAppPersistence.swift	File-based persistence + Codable
InAppContentParser.swift	HTML/padding parsing
InAppMessageParser.swift	Server response parsing
InAppHelper.swift	URL parsing utilities
InAppInternal.swift	Fetcher + protocols
IterableHtmlMessageViewController.swift	WKWebView-based UI
IterableInAppMessage.swift	Data model
IterableMessaging.swift	Public types + delegate

[RGG-jayoung]

Deep Dive: Unknown User Tracking (Anonymous User Activation)

Overview

The Iterable SDK provides a sophisticated unknown user tracking system that captures user behavior before they sign in or create an account. This allows marketing teams to understand anonymous visitor activity and enables seamless transition of that history to known user profiles.

The system is called UUA (Unknown User Activation) internally.

---

1. Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                        Unknown User Tracking Architecture                                │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                          │
│   ┌──────────────────────────────────────────────────────────────────────────────────┐  │
│   │                           CONSENT GATE                                            │  │
│   │   visitorUsageTracked = true  →  Events stored                                   │  │
│   │   visitorUsageTracked = false →  Events discarded                                │  │
│   └──────────────────────────────────────────────────────────────────────────────────┘  │
│                                       │                                                  │
│                                       ▼                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                        UnknownUserManager                                        │   │
│   │  • trackUnknownUserEvent()         • trackUnknownUserPurchaseEvent()            │   │
│   │  • trackUnknownUserUpdateCart()    • trackUnknownUserUpdateUser()               │   │
│   │  • trackUnknownUserTokenRegistration()                                          │   │
│   │  • updateUnknownUserSession()      • getUnknownUserCriteria()                   │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                         │                          │                                     │
│                         ▼                          ▼                                     │
│   ┌─────────────────────────────┐    ┌─────────────────────────────────────────────┐   │
│   │   Local Storage (UserDefs)  │    │    CriteriaCompletionChecker                │   │
│   │  • unknownUserEvents[]      │    │    • Evaluates stored events vs criteria    │   │
│   │  • unknownUserUpdate{}      │    │    • AND/OR/NOT combinators                 │   │
│   │  • unknownUserSessions{}    │    │    • Field comparators (=, !=, >, <, etc.)  │   │
│   │  • criteriaData             │    │    • Returns matched criteriaId             │   │
│   └─────────────────────────────┘    └─────────────────────────────────────────────┘   │
│                                                    │                                     │
│                                                    ▼                                     │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                        Criteria Match Flow                                       │   │
│   │  1. createUnknownUser(criteriaId)                                               │   │
│   │  2. Generate UUID for userId                                                    │   │
│   │  3. trackUnknownUserSession() API call                                          │   │
│   │  4. Store userIdUnknownUser in Keychain                                         │   │
│   │  5. Notify via unknownUserHandler.onUnknownUserCreated(userId)                  │   │
│   │  6. setUserId(userId, isUnknownUser: true)                                      │   │
│   │  7. syncEvents() - replay stored events via track APIs                          │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                          │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                        User Merge (Login Flow)                                   │   │
│   │  UnknownUserMerge.tryMergeUser()                                                │   │
│   │  • Merges unknown user profile → known user profile                             │   │
│   │  • ApiClient.mergeUser(sourceUserId: unknownId, destinationEmail/userId)        │   │
│   │  • Replays events if identityResolution.replayOnVisitorToKnown = true           │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                          │
└─────────────────────────────────────────────────────────────────────────────────────────┘

---

2. Configuration Options

IterableConfig Properties:

Property	Type	Default	Description
enableUnknownUserActivation	Bool	true	Master switch for UUA
enableForegroundCriteriaFetch	Bool	true	Refresh criteria on app foreground
eventThresholdLimit	Int	100	Max events stored locally
unknownUserHandler	IterableUnknownUserHandler?	nil	Callback when unknown user created
identityResolution	IterableIdentityResolution	see below	Controls merge/replay behavior

IterableIdentityResolution:

public class IterableIdentityResolution {
    public var replayOnVisitorToKnown: Bool?      // Replay events on login (default: true)
    public let mergeOnUnknownUserToKnown: Bool?   // Merge profiles on login (default: true)
}

---

3. UnknownUserManager - Core Component

Location: swift-sdk/Internal/UnknownUserManager.swift

Key Responsibilities:

public class UnknownUserManager: UnknownUserManagerProtocol {
    // Event tracking (stores locally)
    func trackUnknownUserEvent(name:, dataFields:)
    func trackUnknownUserPurchaseEvent(total:, items:, dataFields:)
    func trackUnknownUserUpdateCart(items:)
    func trackUnknownUserUpdateUser(_ dataFields:)
    func trackUnknownUserTokenRegistration(token:)
    
    // Session management
    func updateUnknownUserSession()
    
    // Criteria management  
    func getUnknownUserCriteria()
    func getLastCriteriaFetch() -> Double
    func updateLastCriteriaFetch(currentTime:)
    
    // Event sync
    func syncEvents()
    func syncNonSyncedEvents()  // 2-second delay for race condition
    func clearVisitorEventsAndUserData()
}

---

4. Event Storage

Events stored in UserDefaults:

// Custom events array (up to eventThresholdLimit)
var unknownUserEvents: [[AnyHashable: Any]]? {
    // Each event contains:
    // - eventType: "customEvent" | "purchase" | "updateCart" | "tokenRegistration"
    // - eventName: String (for custom events)
    // - eventTimeStamp: Int (seconds from epoch)
    // - dataFields: [AnyHashable: Any]?
    // - createdAt: Int
}

// User profile updates (merged, single object)
var unknownUserUpdate: [AnyHashable: Any]?

// Session tracking
var unknownUserSessions: IterableUnknownUserSessionsWrapper? {
    // itbl_unknown_user_sessions:
    //   - totalUnknownUserSessionCount: Int
    //   - lastUnknownUserSession: Int (timestamp)
    //   - firstUnknownUserSession: Int (timestamp)
}

Secure Storage (Keychain):

var userIdUnknownUser: String?  // UUID generated after criteria match

---

5. Consent Management

Consent is required before tracking:

func setVisitorUsageTracked(isVisitorUsageTracked: Bool) {
    localStorage.visitorUsageTracked = isVisitorUsageTracked
    
    if isVisitorUsageTracked {
        // Store consent timestamp
        localStorage.visitorConsentTimestamp = Int64(Date().timeIntervalSince1970 * 1000)
    } else {
        localStorage.visitorConsentTimestamp = nil
    }
    
    // Clear all stored data on consent change
    localStorage.unknownUserEvents = nil
    localStorage.unknownUserSessions = nil
    localStorage.unknownUserUpdate = nil
    localStorage.userIdUnknownUser = nil
    
    if isVisitorUsageTracked && config.enableUnknownUserActivation {
        unknownUserManager.getUnknownUserCriteria()
        unknownUserManager.updateUnknownUserSession()
    }
}

Early return in storeEventData:

private func storeEventData(type: String, data: [AnyHashable: Any], ...) {
    // Consent gate - early return if no consent
    if !self.localStorage.visitorUsageTracked {
        ITBInfo("UUA CONSENT NOT GIVEN - no events being stored")
        return
    }
    // ... store event
}

---

6. Criteria Evaluation System

CriteriaCompletionChecker - Evaluates stored events against server criteria:

struct CriteriaCompletionChecker {
    func getMatchedCriteria() -> String? {
        // Parse criteriaList from server JSON
        // For each criteria:
        //   - Get searchQuery
        //   - evaluateTree(node: searchQuery, localEventData: events)
        //   - Return criteriaId if matched
    }
}

Combinator Logic:

func evaluateTree(node:, localEventData:) -> Bool {
    switch combinator {
    case "And":
        // All subqueries must pass
        return searchQueries.allSatisfy { evaluateTree($0) }
    case "Or":
        // Any subquery must pass
        return searchQueries.contains { evaluateTree($0) }
    case "Not":
        // All subqueries must fail
        return !searchQueries.contains { evaluateTree($0) }
    }
}

Comparator Types:

Comparator	Description
Equals	Exact match
DoesNotEquals	Not equal
IsSet	Value exists and is not empty
GreaterThan	Numeric >
LessThan	Numeric <
GreaterThanOrEqualTo	Numeric >=
LessThanOrEqualTo	Numeric <=
Contains	String contains
StartsWith	String prefix match
MatchesRegex	Regular expression

---

7. Unknown User Creation Flow

When criteria match:

private func createUnknownUser(_ criteriaId: String) {
    // 1. Build session data
    var unknownUserSessions = convertToDictionary(data: localStorage.unknownUserSessions)
    let userId = IterableUtil.generateUUID()
    unknownUserSessions[JsonKey.matchedCriteriaId] = Int(criteriaId)
    
    // 2. Check push notification opt-in
    notificationStateProvider.isNotificationsEnabled { isEnabled in
        if isEnabled {
            unknownUserSessions[JsonKey.mobilePushOptIn] = Bundle.main.appPackageName
        }
        
        // 3. Track session to server
        IterableAPI.implementation?.apiClient.trackUnknownUserSession(
            createdAt: timestamp,
            withUserId: userId,
            dataFields: localStorage.unknownUserUpdate,
            requestJson: unknownUserSessions
        ).onSuccess { _ in
            // 4. Store userId
            self.localStorage.userIdUnknownUser = userId
            
            // 5. Notify app
            self.config.unknownUserHandler?.onUnknownUserCreated(userId: userId)
            
            // 6. Login as unknown user
            IterableAPI.implementation?.setUserId(userId, isUnknownUser: true)
            
            // 7. Send consent data
            self.sendConsentAfterCriteriaMatch(userId: userId)
            
            // 8. Sync stored events (2-second delay)
            self.syncNonSyncedEvents()
        }.onError { error in
            self.isCriteriaMatched = false
            if error.httpStatusCode == 409 {
                self.getUnknownUserCriteria()  // Refetch on conflict
            }
        }
    }
}

---

8. Event Synchronization

When unknown user is created, sync stored events to server:

func syncEvents() {
    if let events = localStorage.unknownUserEvents {
        for var eventData in events {
            switch eventData[JsonKey.eventType] {
            case EventType.customEvent:
                IterableAPI.implementation?.track(eventName, withBody: eventData)
            case EventType.purchase:
                IterableAPI.implementation?.trackPurchase(total, items, dataFields, createdAt)
            case EventType.updateCart:
                IterableAPI.implementation?.updateCart(items, createdAt)
            }
        }
    }
    
    // Sync user profile updates
    if var userUpdate = localStorage.unknownUserUpdate {
        IterableAPI.implementation?.updateUser(userUpdate, mergeNestedObjects: false)
    }
}

---

9. User Merge (Known User Login)

UnknownUserMerge handles profile merging when user logs in:

class UnknownUserMerge: UnknownUserMergeProtocol {
    func tryMergeUser(destinationUser:, isEmail:, merge:, onMergeResult:) {
        let unknownUserId = localStorage.userIdUnknownUser
        
        if unknownUserId != nil && destinationUser != nil && merge {
            apiClient.mergeUser(
                sourceEmail: nil,
                sourceUserId: unknownUserId,
                destinationEmail: isEmail ? destinationUser : nil,
                destinationUserId: isEmail ? nil : destinationUser
            ).onSuccess { _ in
                onMergeResult(.mergesuccessful, nil)
            }.onError { error in
                onMergeResult(.mergefailed, error.reason)
            }
        } else {
            onMergeResult(.mergenotrequired, nil)
        }
    }
}

Merge Results:

• .mergesuccessful - Profiles merged
• .mergefailed - API error during merge
• .mergenotrequired - No unknown user or merge disabled

---

10. Criteria Fetch Timing

On App Launch:

if config.enableUnknownUserActivation {
    unknownUserManager.getUnknownUserCriteria()
    unknownUserManager.updateUnknownUserSession()
}

On App Foreground:

// Only if:
// - enableForegroundCriteriaFetch = true
// - enableUnknownUserActivation = true
// - visitorUsageTracked = true
// - No known user set
// - No unknown user set
// - 10 minute cooldown since last fetch

if currentTime - lastCriteriaFetch >= Const.criteriaFetchingCooldown {
    unknownUserManager.getUnknownUserCriteria()
}

---

11. InternalIterableAPI Integration

Event Interception Pattern:

func track(event eventName: String, dataFields: [AnyHashable: Any]?, ...) {
    // If no known user AND no unknown user AND UUA enabled
    if !isEitherUserIdOrEmailSet() && localStorage.userIdUnknownUser == nil {
        if config.enableUnknownUserActivation {
            ITBInfo("UUA ENABLED - unknown user track custom event")
            unknownUserManager.trackUnknownUserEvent(name: eventName, dataFields: dataFields)
        }
        return rejectWithInitializationError(onFailure: onFailure)
    }
    // ... normal tracking to server
}

Methods with UUA interception:

• track(event:dataFields:)
• updateUser(_:mergeNestedObjects:)
• updateCart(items:)
• trackPurchase(_:items:dataFields:)
• registerForPush(token:)

---

12. Data Flow Summary

User Action (no login)
        │
        ▼
┌───────────────────┐
│ Consent Check     │──── visitorUsageTracked = false ──▶ DISCARD
└───────────────────┘
        │ true
        ▼
┌───────────────────┐
│ Store Locally     │──▶ unknownUserEvents[] (max 100)
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Evaluate Criteria │──▶ CriteriaCompletionChecker
└───────────────────┘
        │ match
        ▼
┌───────────────────┐
│ Create Unknown    │──▶ trackUnknownUserSession API
│ User              │──▶ Generate UUID
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Sync Events       │──▶ track(), trackPurchase(), updateCart()
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ User Logs In      │──▶ setEmail/setUserId
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Merge Profiles    │──▶ mergeUser API (if enabled)
│ Replay Events     │──▶ syncEvents() (if enabled)
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Clear Local Data  │──▶ clearVisitorEventsAndUserData()
└───────────────────┘

---

13. Key Files Reference

File	Purpose
UnknownUserManager.swift	Core UUA logic, event storage, criteria evaluation
UnknownUserManager+Functions.swift	CriteriaCompletionChecker, comparators
UnknownUserManagerProtocol.swift	Protocol definition
UnknownUserMerge.swift	Profile merge on login
IterableIdentityResolution.swift	Merge/replay configuration
LocalStorage.swift	Storage abstraction
IterableUserDefaults.swift	UserDefaults implementation
IterableKeychain.swift	Secure userId storage
IterableConfig.swift	Configuration options
InternalIterableAPI.swift	Event interception integration

---

14. Security Considerations

1. Consent Gating - Events only stored if visitorUsageTracked = true
2. Keychain Storage - userIdUnknownUser stored in secure Keychain
3. Event Limits - Max 100 events stored locally (eventThresholdLimit)
4. Timestamp Validation - All events include createdAt for audit trail
5. Consent Timestamp - Tracks when consent was given (visitorConsentTimestamp)
6. Conflict Handling - 409 errors trigger criteria refetch

[RGG-jayoung]

Deep Dive: Embedded Messaging System

Overview

Embedded messaging allows developers to display native, non-intrusive messages within their app UI at designated "placements." Unlike in-app messages that appear as overlays, embedded messages integrate directly into the app's content flow (cards, banners, notifications) and are fully customizable by the developer.

---

1. Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                        Embedded Messaging Architecture                                   │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                          │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                      IterableEmbeddedManager                                     │   │
│   │  • Fetches messages from server                                                 │   │
│   │  • Manages message state per placement                                          │   │
│   │  • Handles click/action routing                                                 │   │
│   │  • Notifies listeners of updates                                                │   │
│   │  • Auto-syncs on app foreground                                                 │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                         │                          │                                     │
│                         ▼                          ▼                                     │
│   ┌─────────────────────────────┐    ┌─────────────────────────────────────────────┐   │
│   │  EmbeddedMessagingProcessor │    │    EmbeddedSessionManager (Singleton)       │   │
│   │  • Diff current vs fetched  │    │    • Tracks impression sessions             │   │
│   │  • Identify new messages    │    │    • Measures display duration              │   │
│   │  • Identify removed IDs     │    │    • Aggregates display counts              │   │
│   └─────────────────────────────┘    └─────────────────────────────────────────────┘   │
│                                                                                          │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                       UI Layer (Developer-Controlled)                            │   │
│   │  ┌─────────────────────┐  ┌─────────────────────┐  ┌────────────────────────┐  │   │
│   │  │  IterableEmbedded   │  │  Custom UIView      │  │  SwiftUI View          │  │   │
│   │  │  View (OOTB)        │  │  (from elements)    │  │  (from elements)       │  │   │
│   │  │  • Card             │  │                     │  │                        │  │   │
│   │  │  • Banner           │  │                     │  │                        │  │   │
│   │  │  • Notification     │  │                     │  │                        │  │   │
│   │  └─────────────────────┘  └─────────────────────┘  └────────────────────────┘  │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                          │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                       Analytics Tracking                                         │   │
│   │  • track(embeddedMessageReceived:)   - When new message fetched                 │   │
│   │  • track(embeddedMessageClick:)      - When user clicks message/button          │   │
│   │  • track(embeddedMessageImpression:) - When message becomes visible             │   │
│   │  • track(embeddedMessageDismiss:)    - When message dismissed                   │   │
│   │  • track(embeddedSession:)           - Session with all impressions             │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                          │
└─────────────────────────────────────────────────────────────────────────────────────────┘

---

2. Configuration

Enable embedded messaging in IterableConfig:

let config = IterableConfig()
config.enableEmbeddedMessaging = true  // Default: false
IterableAPI.initialize(apiKey: "YOUR_API_KEY", config: config)

---

3. Data Model

IterableEmbeddedMessage - The core message object:

public final class IterableEmbeddedMessage: NSObject {
    public let metadata: EmbeddedMessageMetadata
    public let elements: EmbeddedMessageElements?
    public let payload: [AnyHashable: Any]?  // Custom data
}

EmbeddedMessageMetadata:

Property	Type	Description
messageId	String	Unique message identifier
campaignId	Int?	Associated campaign
isProof	Bool?	Test/proof message flag
placementId	Int?	Placement location identifier

EmbeddedMessageElements:

Property	Type	Description
title	String?	Message title
body	String?	Message body text
mediaUrl	String?	Image URL
mediaUrlCaption	String?	Accessibility caption
buttons	[EmbeddedMessageElementsButton]?	Action buttons
text	[EmbeddedMessageElementsText]?	Additional text elements
defaultAction	EmbeddedMessageElementsDefaultAction?	Tap action

Button Structure:

public struct EmbeddedMessageElementsButton: Codable {
    public let id: String
    public let title: String?
    public let action: EmbeddedMessageElementsButtonAction?
}

public struct EmbeddedMessageElementsButtonAction: Codable {
    public let type: String    // e.g., "openUrl"
    public let data: String?   // URL or action data
}

---

4. IterableEmbeddedManager

Location: swift-sdk/Internal/IterableEmbeddedManager.swift

Public API:

public protocol IterableEmbeddedManagerProtocol {
    // Retrieve messages
    func getMessages() -> [IterableEmbeddedMessage]
    func getMessages(for placementId: Int) -> [IterableEmbeddedMessage]
    
    // Sync from server
    func syncMessages(completion: @escaping () -> Void)
    func syncMessages(placementIds: [Int]?, completion: @escaping () -> Void)
    
    // Handle interactions
    func handleEmbeddedClick(message: IterableEmbeddedMessage, 
                             buttonIdentifier: String?, 
                             clickedUrl: String)
    
    // Listener management
    func addUpdateListener(_ listener: IterableEmbeddedUpdateDelegate)
    func removeUpdateListener(_ listener: IterableEmbeddedUpdateDelegate)
    
    // Reset state
    func reset()
}

Key Implementation Details:

class IterableEmbeddedManager {
    // Messages organized by placementId
    private var messages: [Int: [IterableEmbeddedMessage]] = [:]
    
    // Thread-safe message access
    private let messageProcessingQueue = DispatchQueue(
        label: "com.iterable.embedded.messages", 
        qos: .userInitiated
    )
    
    // Weak references to listeners (no retain cycles)
    private var listeners: NSHashTable<IterableEmbeddedUpdateDelegate> = 
        NSHashTable(options: [.weakMemory])
    
    // Track which messages have been reported as received
    private var trackedMessageIds: Set<String> = Set()
}

---

5. Message Synchronization

Sync Triggers:

1. SDK initialization (if enableEmbeddedMessaging = true)
2. App becomes active (foreground observer)
3. Manual call to syncMessages()

Sync Flow:

private func retrieveEmbeddedMessages(placementIds: [Int]?, completion: @escaping () -> Void) {
    apiClient.getEmbeddedMessages(placementIds: placementIds)
        .onCompletion(
            receiveValue: { embeddedMessagesPayload in
                // 1. Convert placements to dictionary
                var fetchedMessagesDict: [Int: [IterableEmbeddedMessage]] = [:]
                for placement in placements {
                    fetchedMessagesDict[placement.placementId\!] = placement.embeddedMessages
                }
                
                // 2. Preserve unrequested placement messages
                if let placementIds, \!placementIds.isEmpty {
                    for (placementId, currentMessages) in currentMessagesSnapshot 
                        where \!requestedPlacementIds.contains(placementId) {
                        fetchedMessagesDict[placementId] = currentMessages
                    }
                }
                
                // 3. Process diff
                let processor = EmbeddedMessagingProcessor(
                    currentMessages: currentMessagesSnapshot,
                    fetchedMessages: fetchedMessagesDict
                )
                
                // 4. Update state and notify
                self.setMessages(processor)
                self.trackNewlyRetrieved(processor)
                self.notifyUpdateDelegates(processor)
            },
            receiveError: { error in
                if error.reason == "SUBSCRIPTION_INACTIVE" ||
                   error.reason == "Invalid API Key" {
                    self.notifyDelegatesOfInvalidApiKeyOrSyncStop()
                }
            }
        )
}

---

6. EmbeddedMessagingProcessor

Location: swift-sdk/Internal/EmbeddedMessagingProcessor.swift

Compares current messages with fetched messages:

struct EmbeddedMessagingProcessor {
    // Returns the new message set
    func processedMessagesList() -> [Int: [IterableEmbeddedMessage]] {
        return fetchedMessages
    }
    
    // Messages that were fetched but not in current set
    func newlyRetrievedMessages() -> [Int: [IterableEmbeddedMessage]] {
        var newMessages: [Int: [IterableEmbeddedMessage]] = [:]
        for (placementId, fetchedMessagesList) in fetchedMessages {
            let currentMessageIds = currentMessages[placementId]?.map { $0.metadata.messageId } ?? []
            let newFetchedMessages = fetchedMessagesList.filter { 
                \!currentMessageIds.contains($0.metadata.messageId) 
            }
            if \!newFetchedMessages.isEmpty {
                newMessages[placementId] = newFetchedMessages
            }
        }
        return newMessages
    }
    
    // Message IDs that were in current but not in fetched
    func newlyRemovedMessageIds() -> [Int: [String]] {
        // ... inverse logic
    }
}

---

7. Session & Impression Tracking

EmbeddedSessionManager - Singleton for tracking viewing sessions:

public class EmbeddedSessionManager {
    public static let shared = EmbeddedSessionManager()
    
    public var session: IterableEmbeddedSession?
    var currentlyTrackingImpressions: [String: (
        totalDisplayDuration: TimeInterval, 
        startTime: Date, 
        tracking: Bool
    )] = [:]
    
    public func startSession() {
        if session?.isActive == true { return }
        session = IterableEmbeddedSession(
            embeddedSessionId: UUID().uuidString,
            embeddedSessionStart: Date(),
            impressions: [],
            isActive: true
        )
    }
    
    public func endSession() {
        // Pause all impressions
        for messageId in currentlyTrackingImpressions.keys {
            pauseImpression(messageId: messageId)
        }
        
        // Set end time and update durations
        session?.embeddedSessionEnd = Date()
        updateDisplayDurations()
        
        // Track to server if impressions exist
        if \!session.impressions.isEmpty {
            IterableAPI.track(embeddedSession: session)
        }
        session?.isActive = false
    }
    
    public func startImpression(messageId: String, placementId: Double) {
        // Track new impression or increment displayCount
    }
    
    public func pauseImpression(messageId: String) {
        // Pause timing without ending session
    }
}

IterableEmbeddedImpression:

public class IterableEmbeddedImpression: Codable {
    public let messageId: String
    public let placementId: Double
    public var displayCount: Int           // How many times shown
    public var displayDuration: TimeInterval  // Total time visible
}

---

8. Click Handling

URL Scheme Parsing (EmbeddedHelper):

URL Type	Pattern	Handling
localResource	applewebdata://	Extract resource name
iterableCustomAction	iterable://	SDK-defined actions (delete, dismiss)
customAction	action:// or itbl://	App-defined custom actions
regularUrl	Any other scheme	Standard URL handling

Click Flow:

public func handleClick(clickedUrl: URL?, forMessage message: IterableEmbeddedMessage) {
    guard let url = clickedUrl, 
          let embeddedClickedUrl = EmbeddedHelper.parse(embeddedUrl: url) else {
        return
    }
    
    switch embeddedClickedUrl {
    case .iterableCustomAction(name: let name):
        handleIterableCustomAction(name: name, forMessage: message)
    case .customAction(name: let name):
        handleUrlOrAction(urlOrAction: name)
    case .localResource(name: let name):
        handleUrlOrAction(urlOrAction: name)
    case .regularUrl:
        handleUrlOrAction(urlOrAction: url.absoluteString)
    }
}

Action Execution:

private func handleUrlOrAction(urlOrAction: String) {
    guard let action = createAction(fromUrlOrAction: urlOrAction) else { return }
    
    let context = IterableActionContext(action: action, source: .embedded)
    DispatchQueue.main.async {
        ActionRunner.execute(
            action: action,
            context: context,
            urlHandler: IterableUtil.urlHandler(fromUrlDelegate: self.urlDelegate, inContext: context),
            customActionHandler: IterableUtil.customActionHandler(fromCustomActionDelegate: self.customActionDelegate, inContext: context),
            urlOpener: self.urlOpener,
            allowedProtocols: self.allowedProtocols
        )
    }
}

---

9. Update Delegate Protocol

IterableEmbeddedUpdateDelegate - Callbacks for UI updates:

@objc public protocol IterableEmbeddedUpdateDelegate {
    // Required
    func onMessagesUpdated()
    func onEmbeddedMessagingDisabled()
    
    // Optional
    @objc optional func onEmbeddedMessagingSyncSucceeded()
    @objc optional func onEmbeddedMessagingSyncFailed(_ error: String?)
}

Listener Management:

• Uses NSHashTable with weakMemory option
• Listeners auto-removed when deallocated
• No retain cycles

---

10. OOTB UI Component

IterableEmbeddedView - Pre-built UIKit component:

public class IterableEmbeddedView: UIView {
    // IBOutlets for customization
    @IBOutlet weak public var contentView: UIView\!
    @IBOutlet weak public var labelTitle: UILabel\!
    @IBOutlet weak public var labelDescription: UILabel\!
    @IBOutlet weak public var primaryBtn: IterableEMButton\!
    @IBOutlet weak public var secondaryBtn: IterableEMButton\!
    @IBOutlet weak public var imgView: UIImageView?
    @IBOutlet weak public var cardImageView: UIImageView?
    
    public var message: IterableEmbeddedMessage?
}

View Types:

public enum IterableEmbeddedViewType: String {
    case banner        // Horizontal with small image
    case card          // Vertical with large image
    case notification  // No image, colored background
}

Configuration:

public class IterableEmbeddedViewConfig {
    var backgroundColor: UIColor?
    var borderColor: UIColor?
    var borderWidth: CGFloat?
    var borderCornerRadius: CGFloat?
    var primaryBtnBackgroundColor: UIColor?
    var primaryBtnTextColor: UIColor?
    var secondaryBtnBackgroundColor: UIColor?
    var secondaryBtnTextColor: UIColor?
    var titleTextColor: UIColor?
    var bodyTextColor: UIColor?
}

Usage:

let embeddedView = IterableEmbeddedView(
    message: message,
    viewType: .card,
    config: customConfig
)

---

11. Analytics Events

Tracked Events:

Event	Trigger	Data
embeddedMessageReceived	New message fetched	messageId, deviceInfo
embeddedMessageClick	User clicks button/message	messageId, buttonIdentifier, targetUrl
embeddedMessageImpression	Message becomes visible	messageId, deviceInfo
embeddedMessageDismiss	Message dismissed	messageId
embeddedSession	Session ends	sessionId, start/end times, all impressions

API Endpoints:

POST /embedded-messaging/events/received
POST /embedded-messaging/events/click
POST /embedded-messaging/events/impression
POST /embedded-messaging/events/dismiss
POST /embedded-messaging/events/session
GET  /embedded-messaging/messages

---

12. Serialization

EmbeddedMessagingSerialization:

struct EmbeddedMessagingSerialization {
    static func encode(placements: [Placement]) -> Data
    static func decode(placements: Data) -> [IterableEmbeddedMessage]
    static func encode(payload: [AnyHashable: Any]?) -> Data?
    static func decode(payload: Data?) -> [AnyHashable: Any]?
}

Placement Structure:

struct Placement: Codable {
    let placementId: Int?
    let embeddedMessages: [IterableEmbeddedMessage]
}

struct PlacementsPayload: Codable {
    let placements: [Placement]
}

---

13. Empty Manager Pattern

EmptyEmbeddedManager - No-op implementation when disabled:

When enableEmbeddedMessaging = false, the SDK uses EmptyEmbeddedManager which returns empty arrays and does nothing, avoiding unnecessary network calls and processing.

---

Key Files Reference

File	Purpose
IterableEmbeddedManager.swift	Main manager (282 lines)
EmbeddedMessagingProcessor.swift	Diff processing
EmbeddedSessionManager.swift	Impression session tracking
EmbeddedHelper.swift	URL parsing utilities
MiscEmbeddedClasses.swift	Session/Impression models
EmbeddedMessagingSerialization.swift	Codable extensions
IterableEmbeddedMessage.swift	Data model
IterableEmbeddedUpdateDelegate.swift	Update callback protocol
IterableEmbeddedManagerProtocol.swift	Public API
IterableEmbeddedView.swift	OOTB UIKit component (530 lines)
EmptyEmbeddedManager.swift	No-op implementation

[RGG-jayoung]

Deep Dive: Request Building & Validation

Overview

The Iterable SDK employs a layered architecture for building and sending API requests. This includes request model abstractions, validation at multiple stages, authentication injection, retry logic, and error mapping. The system is designed to be stateless, type-safe, and supports both online and offline processing modes.

---

1. Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                        Request Building & Validation Architecture                        │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                          │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                      Public API Layer (IterableAPI)                              │   │
│   │  track(event:)  trackPurchase()  updateUser()  updateCart()  register() ...     │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                                       │                                                  │
│                                       ▼                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                           RequestHandler                                         │   │
│   │  • Routes to online/offline processor                                           │   │
│   │  • Health monitor consultation                                                  │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                       │                              │                                   │
│                       ▼                              ▼                                   │
│   ┌─────────────────────────────┐    ┌─────────────────────────────────────────────┐   │
│   │  OnlineRequestProcessor     │    │  OfflineRequestProcessor                    │   │
│   │  (Direct API calls)         │    │  (Queue for later)                          │   │
│   └─────────────────────────────┘    └─────────────────────────────────────────────┘   │
│                       │                                                                  │
│                       ▼                                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                         ApiClient                                                │   │
│   │  • Creates RequestCreator with Auth                                             │   │
│   │  • Calls request creation methods                                               │   │
│   │  • Sends via RequestSender                                                      │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                       │                                                                  │
│                       ▼                                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                      RequestCreator (Stateless)                                  │   │
│   │  • 30+ create*Request methods                                                   │   │
│   │  • Auth validation (email OR userId required)                                   │   │
│   │  • Returns Result<IterableRequest, IterableError>                               │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                       │                                                                  │
│                       ▼                                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                    IterableAPICallRequest                                        │   │
│   │  • Adds apiKey, endpoint, authToken                                             │   │
│   │  • Creates HTTP headers (SDK version, platform, sentAt)                         │   │
│   │  • convertToURLRequest()                                                        │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                       │                                                                  │
│                       ▼                                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                    IterableRequestUtil                                           │   │
│   │  • Path combination                                                             │   │
│   │  • URL component building                                                       │   │
│   │  • Query string encoding                                                        │   │
│   │  • Header injection                                                             │   │
│   │  • Returns URLRequest                                                           │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                       │                                                                  │
│                       ▼                                                                  │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐   │
│   │                     NetworkHelper                                                │   │
│   │  • URLSession wrapper                                                           │   │
│   │  • Retry logic (5 retries for 500+ errors)                                      │   │
│   │  • Response parsing                                                             │   │
│   │  • Error classification                                                         │   │
│   └─────────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                          │
└─────────────────────────────────────────────────────────────────────────────────────────┘

---

2. Request Model Hierarchy

IterableRequest - Abstract request type:

enum IterableRequest: Codable {
    case get(GetRequest)
    case post(PostRequest)
    
    // Add fields dynamically (for createdAt injection)
    func addingBodyField(key: AnyHashable, value: Any) -> IterableRequest
}

GetRequest:

struct GetRequest: Codable {
    let path: String
    let args: [String: String]?  // Query parameters
}

PostRequest:

struct PostRequest: Codable {
    let path: String
    let args: [String: String]?
    let body: [AnyHashable: Any]?  // JSON body
}

IterableAPICallRequest - Complete request wrapper:

struct IterableAPICallRequest: Codable {
    let apiKey: String
    let endpoint: String          // e.g., "https://api.iterable.com/api/"
    let authToken: String?        // JWT token
    let deviceMetadata: DeviceMetadata
    let iterableRequest: IterableRequest
    
    enum ProcessorType {
        case offline
        case online
    }
    
    func convertToURLRequest(sentAt: Date, processorType: ProcessorType) -> URLRequest?
}

---

3. RequestCreator - The Request Factory

Location: swift-sdk/Internal/api-client/Request/RequestCreator.swift (793 lines)

Design:

• Stateless, pure functional struct
• Receives Auth and DeviceMetadata at creation
• Every method returns Result<IterableRequest, IterableError>
• Validates auth before building any request

Authentication Validation Pattern:

func createTrackEventRequest(_ eventName: String, dataFields: [AnyHashable: Any]?) 
    -> Result<IterableRequest, IterableError> {
    
    // VALIDATION: Require email OR userId
    if case .none = auth.emailOrUserId {
        ITBError(Self.authMissingMessage)  // "Both email and userId are nil"
        return .failure(IterableError.general(description: Self.authMissingMessage))
    }
    
    // Build request body
    var body = [AnyHashable: Any]()
    setCurrentUser(inDict: &body)  // Inject email or userId
    body.setValue(for: JsonKey.eventName, value: eventName)
    
    if let dataFields = dataFields {
        body[JsonKey.dataFields] = dataFields
    }
    
    return .success(.post(createPostRequest(path: Const.Path.trackEvent, body: body)))
}

User Identity Injection:

private func setCurrentUser(inDict dict: inout [AnyHashable: Any]) {
    switch auth.emailOrUserId {
    case let .email(email):
        dict.setValue(for: JsonKey.email, value: email)
    case let .userId(userId):
        dict.setValue(for: JsonKey.userId, value: userId)
    case let .userIdUnknownUser(userId):
        dict.setValue(for: JsonKey.userId, value: userId)
    case .none:
        ITBInfo("Current user is unavailable")
    }
}

---

4. Request Categories

API Request Methods in RequestCreator:

Category	Methods
User Management	createUpdateEmailRequest, createUpdateUserRequest, createRegisterTokenRequest, createDisableDeviceRequest, createUpdateSubscriptionsRequest, createMergeUserRequest
Commerce	createUpdateCartRequest (2 variants), createTrackPurchaseRequest (2 variants)
Events	createTrackEventRequest (2 variants), createTrackPushOpenRequest
In-App	createGetInAppMessagesRequest, createTrackInAppOpenRequest, createTrackInAppClickRequest, createTrackInAppCloseRequest, createTrackInAppDeliveryRequest, createInAppConsumeRequest, createTrackInboxSessionRequest
Embedded	createGetEmbeddedMessagesRequest, createEmbeddedMessageReceivedRequest, createEmbeddedMessageClickRequest, createEmbeddedMessageDismissRequest, createEmbeddedMessageImpressionRequest, createTrackEmbeddedSessionRequest
Unknown User	createGetCriteriaRequest, createTrackUnknownUserSessionRequest, createTrackConsentRequest
Config	createGetRemoteConfigurationRequest

---

5. Session-Level Validation

Inbox Session Validation:

func createTrackInboxSessionRequest(inboxSession: IterableInboxSession) 
    -> Result<IterableRequest, IterableError> {
    
    // Validate auth
    if case .none = auth.emailOrUserId {
        return .failure(IterableError.general(description: Self.authMissingMessage))
    }
    
    // Validate session UUID
    guard let inboxSessionId = inboxSession.id else {
        return .failure(IterableError.general(description: "expecting session UUID"))
    }
    
    // Validate start time
    guard let sessionStartTime = inboxSession.sessionStartTime else {
        return .failure(IterableError.general(description: "expecting session start time"))
    }
    
    // Validate end time
    guard let sessionEndTime = inboxSession.sessionEndTime else {
        return .failure(IterableError.general(description: "expecting session end time"))
    }
    
    // Build valid request...
}

---

6. HTTP Headers

Standard Headers (createIterableHeaders):

Header	Key	Value
Content-Type	Content-Type	application/json
SDK Platform	SDK-Platform	iOS
SDK Version	SDK-Version	e.g., 6.5.4
API Key	Api-Key	Your API key
Sent At	Sent-At	Unix timestamp (seconds)
Request Processor	SDK-Request-Processor	Online or Offline
Authorization	Authorization	Bearer <JWT> (if auth token present)

private func createIterableHeaders(sentAt: Date, processorType: ProcessorType) -> [String: String] {
    var headers = [
        JsonKey.contentType: JsonValue.applicationJson,
        JsonKey.Header.sdkPlatform: JsonValue.iOS,
        JsonKey.Header.sdkVersion: IterableAPI.sdkVersion,
        JsonKey.Header.apiKey: apiKey,
        JsonKey.Header.sentAt: "\(IterableUtil.secondsFromEpoch(for: sentAt))",
        JsonKey.Header.requestProcessor: processorType == .online ? "Online" : "Offline"
    ]
    
    if let authToken = authToken {
        headers[JsonKey.Header.authorization] = "Bearer \(authToken)"
    }
    
    return headers
}

---

7. URL Building

IterableRequestUtil:

struct IterableRequestUtil {
    static func createPostRequest(
        forApiEndPoint apiEndPoint: String,  // "https://api.iterable.com/api/"
        path: String,                         // "events/track"
        headers: [String: String]? = nil,
        args: [String: String]? = nil,
        body: [AnyHashable: Any]? = nil
    ) -> URLRequest? {
        
        // 1. Combine endpoint + path
        let endPointCombined = pathCombine(path1: apiEndPoint, path2: path)
        
        // 2. Build URL components
        guard var components = URLComponents(string: endPointCombined) else {
            return nil
        }
        
        // 3. Add query parameters
        if let args = args {
            components.queryItems = args.map { 
                URLQueryItem(name: $0.key, value: $0.value) 
            }
        }
        
        // 4. Encode + signs properly
        components.percentEncodedQuery = components.percentEncodedQuery?
            .replacingOccurrences(of: "+", with: "%2B")
        
        // 5. Create URLRequest
        var request = URLRequest(url: components.url!)
        request.httpMethod = "POST"
        request.httpBody = dictToJsonData(body)
        
        // 6. Add headers
        headers?.forEach { request.setValue($0.value, forHTTPHeaderField: $0.key) }
        
        return request
    }
}

---

8. Network Layer & Retry Logic

NetworkHelper:

struct NetworkHelper {
    static let maxRetryCount = 5
    static let retryDelaySeconds = 2
    
    static func sendRequest<T>(
        _ request: URLRequest,
        converter: @escaping (Data) throws -> T?,
        usingSession networkSession: NetworkSessionProtocol
    ) -> Pending<T, NetworkError> {
        
        func sendRequestWithRetries(request: URLRequest, retriesLeft: Int) {
            networkSession.makeRequest(request) { data, response, error in
                let result = createResultFromNetworkResponse(...)
                
                switch result {
                case .success(let value):
                    fulfill.resolve(with: value)
                case .failure(let error):
                    if shouldRetry(error: error, retriesLeft: retriesLeft) {
                        retryRequest(...)
                    } else {
                        fulfill.reject(with: error)
                    }
                }
            }
        }
        
        // Start with max retries
        sendRequestWithRetries(request: request, retriesLeft: maxRetryCount)
    }
    
    // Retry only on 500+ errors
    func shouldRetry(error: NetworkError, retriesLeft: Int) -> Bool {
        return error.httpStatusCode ?? 0 >= 500 && retriesLeft > 0
    }
}

Retry Delay Strategy:

func retryRequest(retriesLeft: Int) {
    var delay: DispatchTimeInterval = .seconds(0)
    
    // Add 2-second delay after first 2 immediate retries
    if retriesLeft <= 3 {
        delay = .seconds(retryDelaySeconds)  // 2 seconds
    }
    
    DispatchQueue.global().asyncAfter(deadline: .now() + delay) {
        sendRequestWithRetries(retriesLeft: retriesLeft - 1)
    }
}

---

9. Error Classification

NetworkError:

struct NetworkError: Error {
    let reason: String?
    let data: Data?
    let httpStatusCode: Int?
    let originalError: Error?
}

SendRequestError - Higher-level error:

public struct SendRequestError: Error {
    public let reason: String?
    public let data: Data?
    public let httpStatusCode: Int?
    public let iterableCode: String?  // e.g., "InvalidJwtPayload"
    public let originalError: Error?
}

HTTP Status Code Handling:

Status	Behavior
200	Parse JSON, return success
400-499	Parse error message from response body msg field
401	Extract iterableCode for JWT error classification
500+	Retry up to 5 times with backoff

---

10. JWT Error Handling

RequestProcessorUtil - JWT Error Detection:

public static func matchesJWTErrorCode(_ errorCode: String?) -> Bool {
    return errorCode == JsonValue.Code.invalidJwtPayload ||      // "InvalidJwtPayload"
           errorCode == JsonValue.Code.badAuthorizationHeader || // "BadAuthorizationHeader"
           errorCode == JsonValue.Code.jwtUserIdentifiersMismatched  // "JwtUserIdentifiersMismatched"
}

JWT Error Code Mapping:

public static func getMappedErrorCodeForMessage(_ reason: String) -> AuthFailureReason {
    switch reason.lowercased() {
    case "exp must be less than 1 year from iat":
        return .authTokenExpirationInvalid
    case "jwt format is invalid":
        return .authTokenFormatInvalid
    case "jwt token is expired":
        return .authTokenExpired
    case "jwt is invalid":
        return .authTokenSignatureInvalid
    case "jwt payload requires a value for userid or email", "email could not be found":
        return .authTokenUserKeyInvalid
    case "jwt token has been invalidated":
        return .authTokenInvalidated
    case "invalid payload":
        return .authTokenPayloadInvalid
    case "jwt authorization header is not set":
        return .authTokenMissing
    default:
        return .authTokenGenericError
    }
}

401 Retry Flow:

func attemptSend() {
    requestProvider().onSuccess { json in
        resetAuthRetries(authManager: authManager)
        reportSuccess(result: result, value: json)
    }
    .onError { error in
        if error.httpStatusCode == 401, matchesJWTErrorCode(error.iterableCode) {
            // JWT error - refresh token and retry
            authManager?.handleAuthFailure(
                failedAuthToken: authManager?.getAuthToken(),
                reason: getMappedErrorCodeForMessage(error.reason ?? "")
            )
            authManager?.setIsLastAuthTokenValid(false)
            
            let retryInterval = authManager?.getNextRetryInterval() ?? 1
            authManager?.scheduleAuthTokenRefreshTimer(
                interval: retryInterval,
                isScheduledRefresh: false,
                successCallback: { _ in attemptSend() }  // Recursive retry
            )
        } else if error.iterableCode == JsonValue.Code.badApiKey {
            // Bad API key - no retry
            reportFailure(result: result, error: error)
        } else {
            reportFailure(result: result, error: error)
        }
    }
}

---

11. API Endpoints

Defined in Constants.swift (Const.Path):

Category	Endpoint
Commerce	commerce/updateCart, commerce/trackPurchase
Users	users/update, users/updateEmail, users/updateSubscriptions, users/registerDeviceToken, users/disableDevice, users/merge
Events	events/track, events/trackPushOpen, events/trackInAppClick, events/trackInAppOpen, events/trackInAppClose, events/trackInAppDelivery, events/inAppConsume, events/trackInboxSession
In-App	inApp/getMessages
Embedded	embedded-messaging/messages, embedded-messaging/events/received, embedded-messaging/events/click, embedded-messaging/events/dismiss, embedded-messaging/events/impression, embedded-messaging/events/session
Unknown User	unknownuser/list, unknownuser/events/session, unknownuser/consent
Config	mobile/getRemoteConfiguration

Data Regions:

@objc public class IterableDataRegion: NSObject {
    @objc public static let US = "https://api.iterable.com/api/"
    @objc public static let EU = "https://api.eu.iterable.com/api/"
}

---

12. Auth Model

struct Auth: Codable {
    let userId: String?
    let email: String?
    let authToken: String?
    let userIdUnknownUser: String?
    
    var emailOrUserId: EmailOrUserId {
        if let email = email {
            return .email(email)
        } else if let userId = userId {
            return .userId(userId)
        } else if let userIdUnknownUser = userIdUnknownUser {
            return .userIdUnknownUser(userIdUnknownUser)
        } else {
            return .none
        }
    }
    
    enum EmailOrUserId {
        case email(String)
        case userId(String)
        case userIdUnknownUser(String)
        case none
    }
}

---

13. Validation Summary

Pre-Request Validation (RequestCreator):

1. ✅ Email OR userId must be present
2. ✅ Session IDs must not be empty
3. ✅ Session timestamps must be present
4. ✅ Required fields validated before building body

URL Validation (IterableRequestUtil):

1. ✅ Valid URL components
2. ✅ Proper query string encoding (+ → %2B)
3. ✅ Path combination handles trailing slashes

Network Validation (NetworkHelper):

1. ✅ HTTP status code classification
2. ✅ Response body parsing
3. ✅ JSON conversion validation

JWT Validation (RequestProcessorUtil):

1. ✅ 401 error code detection
2. ✅ Iterable-specific JWT error codes
3. ✅ Error reason mapping to AuthFailureReason

---

Key Files Reference

File	Purpose
RequestCreator.swift	Request factory (793 lines)
IterableRequest.swift	Request model + Codable
IterableAPICallRequest.swift	Complete request wrapper
IterableRequestUtil.swift	URL building utilities
RequestSender.swift	Request dispatch + error conversion
NetworkHelper.swift	HTTP layer + retry logic
RequestProcessorUtil.swift	JWT error handling + retry
Constants.swift	API paths, JSON keys (530 lines)
Auth.swift	Auth model

[RGG-jayoung]

Deep Dive 9: QA Testing Guide for SDK Error Logging

This guide provides practical methods for QA team members and developers to manually trigger and validate Iterable SDK error logging.

Proxy Setup

Use one of these tools to intercept SDK traffic to api.iterable.com:

Tool	Platform	Setup
Charles Proxy	macOS	Map Remote, Rewrite, Breakpoints
Proxyman	macOS	Similar to Charles, modern UI
mitmproxy	CLI	mitmproxy -p 8080 + scripts

iOS Simulator config: Settings → Wi-Fi → Configure Proxy → Manual → localhost:8080

---

Error Category 1: Auth Missing (25 error sites)

Log message: "Both email and userId are nil"

Method	How to Test	SDK Behavior
Logout then call API	IterableAPI.setEmail(nil) then IterableAPI.track(event: "test")	Error logged, request rejected locally (never sent)
Fresh install	Don't call setEmail() or setUserId(), call any tracking method	Same - rejected before network

No proxy needed - client-side validation error.

---

Error Category 2: Network/Server Errors

Key endpoints:

https://api.iterable.com/api/events/track
https://api.iterable.com/api/inApp/getMessages
https://api.iterable.com/api/users/update
https://api.iterable.com/api/commerce/trackPurchase

Scenario	Proxy Action	SDK Behavior
500 Server Error	Return status 500	Retries 5x (first 2 immediate, next 3 with 2s delay), then fails
502/503/504	Return 50x status	Same retry logic
Timeout	Add 120s delay	Request times out, logs network error
Connection refused	Block request	"The Internet connection appears to be offline"
Empty response	Return 200 with empty body	"No data received" error
Malformed JSON	Return {broken json	"Could not convert data" error

Charles Proxy setup for 500:

1. Tools → Rewrite
2. Match: api.iterable.com/api/events/track
3. Response: Status 500, body {"msg": "Internal Server Error"}

---

Error Category 3: JWT/Authentication Errors (401)

Scenario	Proxy Response	SDK Behavior
Expired JWT	401 + {"msg": "JWT token is expired", "code": "InvalidJwtPayload"}	Refreshes token, retries request
Invalid JWT	401 + {"msg": "JWT is invalid", "code": "InvalidJwtPayload"}	Calls authDelegate.onAuthFailure()
Bad API Key	401 + {"msg": "Invalid API key", "code": "BadApiKey"}	Fails immediately, no retry
Missing JWT	401 + {"msg": "JWT authorization header is not set", "code": "BadAuthorizationHeader"}	Triggers auth refresh

Log output:

❤️ ...:RequestProcessorUtil:attemptSend:23: invalid JWT token, trying again: JWT token is expired

---

Error Category 4: In-App Message Content Errors

Scenario	How to Trigger	SDK Behavior
Invalid HTML	Return malformed content.html in getMessages	"Invalid Content in message"
Missing content	Return message with no content field	Message skipped, error logged
Bad URL in message	Use itbl://invalid scheme	"Could not create action from"

---

Error Category 5: Embedded Message Errors

Scenario	Proxy Response	SDK Behavior
JSON decode failure	Return {malformed	"unable to decode JSON payload"
Missing metadata	Return messages without metadata	"unable to decode metadata section"
Invalid URL scheme	Use javascript:alert()	"Request url contains an invalid scheme"

---

SDK Network Behavior Summary

┌─────────────────────────────────────────────────────────────┐
│                    Request Flow                              │
├─────────────────────────────────────────────────────────────┤
│  Client Validation                                           │
│  └── Missing email/userId? → Log error, reject locally       │
│                                                              │
│  Network Request                                             │
│  └── Send to api.iterable.com                                │
│                                                              │
│  Response Handling                                           │
│  ├── 200 OK → Parse JSON → Success                          │
│  ├── 401 + JWT error → Refresh token → Retry                │
│  ├── 401 + BadApiKey → Fail immediately                     │
│  ├── 500+ → Retry up to 5x → Then fail                      │
│  └── Parse error → Log "Could not convert data"             │
│                                                              │
│  Retry Strategy (for 500+ errors)                           │
│  ├── Attempt 1: Immediate                                    │
│  ├── Attempt 2: Immediate                                    │
│  ├── Attempt 3: 2 second delay                              │
│  ├── Attempt 4: 2 second delay                              │
│  └── Attempt 5: 2 second delay                              │
└─────────────────────────────────────────────────────────────┘

---

Sample QA Log Delegate

class QALogDelegate: IterableLogDelegate {
    var capturedErrors: [(Date, String)] = []
    
    func log(level: LogLevel, message: String) {
        if level == .error {
            capturedErrors.append((Date(), message))
            print("🔴 SDK ERROR: \(message)")
        }
    }
    
    func assertErrorContains(_ substring: String) -> Bool {
        return capturedErrors.contains { $0.1.contains(substring) }
    }
    
    func dumpErrors() {
        capturedErrors.forEach { print("[\($0.0)] \($0.1)") }
    }
}

// Usage
let qaDelegate = QALogDelegate()
let config = IterableConfig()
config.logDelegate = qaDelegate
IterableAPI.initialize(apiKey: "your-key", config: config)

// After test scenario...
qaDelegate.dumpErrors()
assert(qaDelegate.assertErrorContains("Both email and userId are nil"))

---

QA Test Checklist

## Network Error Testing
- [ ] Block all Iterable traffic → verify offline queue works
- [ ] Return 500 for /events/track → verify 5 retries then failure logged
- [ ] Return 502 for /inApp/getMessages → verify graceful degradation
- [ ] Add 30s latency → verify timeout handling
- [ ] Return malformed JSON → verify parsing error logged

## JWT Error Testing  
- [ ] Return 401 + "JWT token is expired" → verify token refresh triggered
- [ ] Return 401 + "BadApiKey" → verify immediate failure, no retry
- [ ] Return 401 repeatedly → verify retry exhaustion + onAuthFailure called

## Client-Side Error Testing
- [ ] Call track() without email/userId set → verify "Both email and userId are nil"
- [ ] Click embedded message with invalid URL → verify URL error logged
- [ ] Open inbox without messages → verify graceful empty state

## Offline Mode Testing
- [ ] Enable airplane mode, perform actions → verify queued
- [ ] Re-enable network → verify queue processes
- [ ] Return 500 during queue flush → verify retry behavior

---

Log Level Distribution (for reference)

Level	Count	Purpose
ITBError	105	Actual error conditions
ITBInfo	296	Lifecycle events, flow tracking
ITBDebug	59	Detailed execution tracing

Recommendation: Use DefaultLogDelegate(minLogLevel: .info) for QA testing to capture both errors and lifecycle events.