SDK Lifecycle

Hold & Resume SDK Operations

Advanced Feature: For most applications, the standard Netmera.initialize() is sufficient. Use this feature only if your project specifically requires manual control over the SDK lifecycle.

This section covers the advanced lifecycle controls that let you decide exactly when the SDK becomes active, when it pauses, and when it shuts down entirely.

SDK States

The SDK always operates within one of the following four states:

State	Description
operating	Normal state. Events are tracked, and requests are sent immediately.
holdRequested	Transitional state. holdOperation() was called; the request pipeline is still draining. No new work is accepted, but pending requests flush to the network before the SDK fully pauses.
onHold	Paused state. Events and requests are gated. Call startOperation() to resume normal activity.
killed	Terminated state. Terminated via kill(). The SDK cannot be restarted without a full re-initialization on the next app launch.

Method References

1. initializeWithHoldingOperations

Netmera.initializeWithHoldingOperations()

Initializes the SDK in a paused state (onHold). The SDK loads its configuration and sets itself up internally, but it does not process events, send requests, or react to app lifecycle changes until startOperation() is explicitly called.

If your use case requires holding SDK operations until a specific condition is met, use Netmera.initializeWithHoldingOperations() instead of Netmera.initialize().

When to use:

• You need the SDK ready as early as possible (e.g., in AppDelegate.application(_:didFinishLaunchingWithOptions:)) but cannot begin data collection yet (e.g., waiting for user GDPR/KVKK consent).

• You want to control the exact moment Netmera becomes active.

If you initialize the SDK with initializeWithHoldingOperations and never call startOperation(), Netmera will not send any data for the entire lifecycle of the app. Ensure you always invoke startOperation() at the appropriate moment.

2. startOperation

Netmera.startOperation()

Tells the SDK to resume (or begin) processing events and sending network requests. Call this after initializeWithHoldingOperations, or after a previous holdOperation() call.

Behavior:

• If the SDK is onHold: Fully restarts— fires app lifecycle callbacks, and flushes any queued events.

• If the SDK is holdRequested (mid-drain window): Cancels the pending hold and returns to operating immediately, without requiring re-initialization.

• If the SDK is operating or killed: Does nothing (No-op).

3. holdOperation

Netmera.holdOperation()

Tells the SDK to pause all activity. The SDK transitions to holdRequested immediately and then moves to onHold once the current request pipeline drains.

Behavior:

• Any events or requests recorded before the call are allowed to finish flushing to the network, so no data is lost. Callback-based APIs are the exception — they return immediately with a NetmeraNotOperatingError.

• New events are gated (not processed/sent) from the exact moment holdOperation() is called.

• Geofence monitoring and internal configuration are preserved (unlike kill()), meaning that resuming with startOperation() does not require re-initialization.

• If the SDK is onHold, holdRequested, or killed: Does nothing (No-op).

Hold behaves similarly to the app moving to the background: the SDK preserves all its state/configuration and resumes exactly where it left off when startOperation() is called.

4. kill

Netmera.kill()

Shuts down the SDK completely, as if it was never initialized. All internal state, configuration, and queued data are discarded.

Unlike holdOperation(), this action is irreversible within the current app session. Calling startOperation() after kill() does nothing. The SDK can restart only after initialize() or initializeWithHoldingOperations() runs again on the next app launch.

When to use:

• The user has permanently revoked consent and you need to guarantee that no further data is collected or sent for the rest of the session.

Do not use kill() for temporary pausing. Use holdOperation() instead. It preserves all SDK state and configuration, and the SDK resumes exactly where it left off when startOperation() is called.

Checking SDK State

You can programmatically check whether the SDK is actively processing data using the isOperating property:

if Netmera.isOperating {
    // SDK is in the `operating` state
}

Netmera.isOperating returns true only when the SDK is in the operating state. It returns false for onHold, holdRequested, and killed.

Error Handling

When the SDK is not in an operating state, callback-based APIs will return a .notOperating failure:

Netmera.getEmailPermission { result in
      switch result {
      case .success(let isAllowed):
          // handle permission  
      case .failure(let error):
          if error is NetmeraNotOperatingError {
              // SDK is on hold or killed — call startOperation() if appropriate
          }
      }
  }

Domain-specific error types (e.g., NetmeraFetchCouponError, NetmeraInboxError, UserCategoryPreferenceError) each expose a .notOperating case that wraps this error.

Human-readable message:

"Netmera is not in operating state. Call Netmera.startOperation() to resume."