Data flushing for iOS SDK

Data flushing

The SDK caches data (sessions, events, customer properties, etc.) in an internal database and periodically sends it to the Marketing API. After the data has been uploaded, the values in the Marketing web app are updated, and the cached data is removed from the SDK's internal database. This process is called data flushing.

By default, the SDK automatically flushes the data as soon as it is tracked or when the application is backgrounded. You can configure the flushing mode to customize this behavior to suit your needs.

You can also turn off automatic flushing completely. In this case, you must manually flush every time there is data to flush.

The SDK will only flush data when the device has a stable network connection. If a connection error occurs while flushing, it will keep the data cached until the connection is stable and the data is flushed successfully.

Flushing modes

The SDK supports the following 4 flushing modes to specify how often or if data is flushed automatically.

To set the flushing mode, initialize the SDK first, then set flushingMode directly on the Exponea singleton:

Exponea.shared.flushingMode = .periodic(10)

Manual flushing

To manually trigger a data flush to the API, use the following method:

Exponea.shared.flushData()

Use the completion-bearing overload when you need to know the SDK has finished trying to upload pending events—for example, to resolve a Promise in a wrapper SDK or to chain the next operation after the flush settles:

Exponea.shared.flushData { result in
    switch result {
    case .success(let count):
        // count is the number of successfully uploaded objects
        break
    case .flushAlreadyInProgress, .noInternetConnection:
        // The next automatic cycle will retry the flush
        break
    case .error(let error):
        // Inspect the error for the failure cause
        break
    }
}

Completion guarantee

When the SDK is configured and no stop is in progress, flushData(completion:) invokes its callback on the main thread on successful completion and on every documented short-circuit path. The SDK queues any call made before Exponea.shared.configure(...) finishes. If the deferred call succeeds, the callback is invoked once configuration completes.

Exponea.logger logs deferred failures (insufficient authorization, a prior internal exception, or an NSException during deferred execution) and these won't surface in the callback—the deferred-execution path has no error handler wired back to the original caller. If you resolve a Promise/Future inside the iOS callback, call flushData(completion:) only after Exponea.shared.configure(...) returns to avoid a callback that never fires.

The short-circuit paths are:

Flutter, React Native, and similar wrapper SDKs that resolve a Promise or Future inside the iOS callback can rely on this contract for post-configure paths: the callback is delivered exactly once, on the main thread.

Stream mode flushing behavior

When the SDK is configured with Stream/Data hub integration, the flushing behavior has the following differences:

• All flush requests use JWT authentication (Bearer token provided via setSdkAuthToken). The SDK attaches the current JWT to each outgoing request.
• If a flush request receives a 401 Unauthorized response, the SDK invokes the JWT error handler and retries the request once after a ~1-second delay. If the retry also fails, the event remains in the local cache for the next flush cycle.
• Both anonymize() and stopIntegration() flush all pending events before clearing the JWT and customer identity. This ensures tracked data is uploaded while the current token is still available.
• Use anonymize(completion:) or stopIntegration(completion:) to be notified on the main thread when the flush and teardown are complete.

If no JWT is set when a flush is attempted in Stream mode, the SDK will invoke the error handler with .notProvided and defer the flush until a token is available.