Remote SDK Configuration

Configure the BugSnag tvOS SDK to receive server-managed configuration updates without requiring an app update.

Overview

Remote SDK Configuration allows the BugSnag iOS SDK to receive configuration updates from the BugSnag server without requiring an app update or redeployment. This helps your team dynamically manage error event delivery, for example by discarding specific error events directly from the BugSnag dashboard.

When Remote SDK Configuration is enabled, the SDK fetches configuration only when an error requires it. Downloaded configuration is cached locally and applied to subsequent events.

Supported platforms: iOS, macOS, tvOS, and watchOS.

How it works

When Remote SDK Configuration is enabled, the SDK:

Does not fetch configuration on app startup.
Does not periodically fetch configuration while the app is running.
Loads a valid cached configuration, if available, and applies its discard rules immediately.
Starts a background configuration fetch after an error needs configuration and no valid cached configuration is available.
Never delays the current error while waiting for a configuration response.
Caches successfully downloaded configuration locally for use across future app launches.
Applies discard rules to subsequent error events before they are delivered.

If Remote Configuration is missing, expired, unavailable, or invalid, the SDK uses safe-default behavior: it does not apply Remote Config discard rules and delivers the error normally.

A configuration fetched because of an error does not retroactively affect that error. It can affect later error events once the configuration has been received and activated.

Configuration

Remote SDK Configuration is enabled by default when you use the standard BugsnagEndpointConfiguration initializer.

Default setup

BugsnagConfiguration *config = [[BugsnagConfiguration alloc] initWithApiKey:@"YOUR_API_KEY"];
// Remote configuration is enabled by default — no additional setup needed
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration("YOUR-API-KEY")
// Remote configuration is enabled by default — no additional setup needed
Bugsnag.start(with: config)

Custom endpoints

If you use custom endpoints, include the configuration parameter:

BugsnagConfiguration *config = [[BugsnagConfiguration alloc] initWithApiKey:@"YOUR_API_KEY"];
config.endpoints = [[BugsnagEndpointConfiguration alloc]
    initWithNotify:@"https://notify.example.com"
          sessions:@"https://sessions.example.com"
     configuration:@"https://config.bugsnag.com/error-config"];
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration("YOUR-API-KEY")
config.endpoints = BugsnagEndpointConfiguration(
    notify: "https://notify.example.com",
    sessions: "https://sessions.example.com",
    configuration: "https://config.bugsnag.com/error-config"
)
Bugsnag.start(with: config)

Disable Remote Configuration

To opt out of Remote Configuration entirely, set the configuration endpoint to nil:

BugsnagConfiguration *config = [[BugsnagConfiguration alloc] initWithApiKey:@"YOUR_API_KEY"];
config.endpoints = [[BugsnagEndpointConfiguration alloc]
    initWithNotify:@"https://notify.bugsnag.com"
          sessions:@"https://sessions.bugsnag.com"
     configuration:nil];
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration("YOUR-API-KEY")
config.endpoints = BugsnagEndpointConfiguration(
    notify: "https://notify.bugsnag.com",
    sessions: "https://sessions.bugsnag.com",
    configuration: nil
)
Bugsnag.start(with: config)

When Remote Configuration is disabled:

usage.remoteConfig is sent as false.
Cached Remote Configuration is not used.
Remote Config discard rules are not applied.
The SDK does not request Remote Configuration.

Disabling Remote Configuration clears the SDK’s persisted Remote Configuration cache.

Fetch and cache behavior

Behavior	Description
Error-first fetch	The SDK only considers a configuration request after an error requires Remote Configuration and there is no valid cached configuration.
No startup fetch	Starting the SDK does not request Remote Configuration.
No periodic fetch	The SDK does not use a periodic background timer to refresh Remote Configuration.
Non-blocking delivery	The error that triggers a fetch is not delayed while the request is in progress. Without a valid cached configuration, that error is delivered using safe defaults.
Cached configuration	A valid cached configuration is used immediately and can discard matching events without a network request.
Expiry	The SDK uses the response `Cache-Control: max-age` value when it is greater than zero. If no usable `max-age` value is supplied, the configuration uses the SDK’s default expiry of 26 hours.
ETag support	The SDK sends `If-None-Match` when it has a cached ETag. A `304 Not Modified` response retains cached discard rules and refreshes the expiry.
Version scoped	The Remote Configuration cache is scoped to the current app version. Rules cached for a previous app version are not applied after an app update.
In-memory fallback	If a valid configuration is received but cannot be written to disk, it remains active for the current app process only.
Safe default	Missing, expired, invalid, or unavailable Remote Configuration never causes events to be discarded.

Request protection

The SDK protects the Remote Configuration endpoint from repeated requests.

Cooldown

Before starting a request, the SDK persists a cooldown timestamp in UserDefaults.

The cooldown duration is randomized between approximately 22 and 26 hours:

24 hours ± 2 hours

The timestamp survives application and device restarts. While the cooldown is active, ordinary cache-miss requests are not started.

Expired-cache refresh

A newly expired cached configuration is allowed one refresh attempt even when a cooldown is active. This allows the SDK to revalidate an expired cache without waiting for the full cooldown period.

To prevent repeated requests if that refresh fails, the SDK stores an expired-cache refresh marker containing the cached configuration’s ETag and expiry timestamp.

The marker is retained when the request:

fails;
returns an invalid configuration;
returns a 304 response that cannot be persisted; or
returns a valid replacement configuration that cannot be saved to disk.

The marker is cleared only after a replacement configuration or refreshed expiry is saved durably. This prevents the same expired cached configuration from bypassing cooldown repeatedly across app relaunches.

Discard rules

Remote SDK Configuration supports dashboard-managed discard rules that prevent matching error events from being delivered to BugSnag.

Rules are evaluated in the event delivery pipeline after OnSendError callbacks have run.

Supported discard rule types:

Rule type	Effect
Discard by error class	Discards events whose error class matches a configured error class.
Discard by app version	Discards events for configured app versions.
Discard specific errors	Discards future occurrences of an error selected in the dashboard.
Discard handled events	Discards handled events for a configured period.

Remote Config discard rules affect only error-event delivery. They do not affect session tracking or breadcrumb recording.

For more information about managing errors in the dashboard, see Error status and actions and Event usage.

On-premise and self-hosted deployments

Remote SDK Configuration is not available for on-premise and self-hosted deployments. This feature requires connectivity to BugSnag’s managed configuration service.

FAQs

Does Remote Configuration affect app startup time?

No. The SDK does not fetch Remote Configuration during app startup. It loads a valid cached configuration in the background without blocking startup.

What happens on the first error after enabling Remote Configuration?

If no valid cached configuration exists, the SDK uses safe-default behavior for that error and may start a background configuration request. The fetched configuration can apply to later events.

What happens if the device is offline?

The SDK uses a valid locally cached configuration, if available. If no valid cache is available, all errors are delivered normally.

What happens if the first error is a crash?

If no valid cached configuration is available, the crash uses safe-default behavior. The SDK cannot wait for a newly requested configuration before the process terminates.

On the next app launch, the stored crash report is processed normally. If a valid cached Remote Configuration is available at that time, its discard rules can be evaluated before the crash report is delivered.

Do discard rules apply to crashes?

It depends on the rule. The “Discard handled events” rule applies only to handled errors. Other matching rules, such as error-class, app-version, and specific-error rules, can apply to both handled and unhandled errors.

Will a new app version inherit the previous version’s Remote Configuration?

No. Remote Configuration is scoped to the app version that downloaded it. A new app version does not use rules cached for a previous app version.

What happens when a Remote Configuration request returns `304 Not Modified`?

The SDK retains the existing cached rules and updates the configuration expiry. The configuration body is not downloaded again.

What happens if a Remote Configuration request fails?

The SDK continues using a valid cached configuration if one exists. Otherwise, it uses safe-default behavior and delivers errors normally. Request cooldown and expired-cache refresh protection prevent repeated requests.