0
# SDK Initialization
1

2
Core SDK setup and configuration management for browser environments. The Sentry Browser SDK provides comprehensive initialization options for error monitoring, performance tracking, and session management.
3

4
## Capabilities
5

6
### Main Initialization Function
7

8
Initialize the Sentry SDK with comprehensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Initialize the Sentry Browser SDK
13
 * @param options - Configuration options for the SDK
14
 * @returns Client instance or undefined if initialization fails
15
 */
16
function init(options?: BrowserOptions): Client | undefined;
17
```
18

19
**Usage Example:**
20

21
```typescript
22
import * as Sentry from "@sentry/browser";
23

24
Sentry.init({
25
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
26
  debug: true,
27
  environment: "production",
28
  release: "1.0.0",
29
  sampleRate: 1.0,
30
  tracesSampleRate: 0.1,
31
  integrations: [
32
    Sentry.browserTracingIntegration(),
33
    Sentry.replayIntegration({
34
      sessionSampleRate: 0.1,
35
      errorSampleRate: 1.0,
36
    }),
37
  ],
38
  beforeSend(event, hint) {
39
    // Filter out noisy errors
40
    if (event.exception) {
41
      const error = hint.originalException;
42
      if (error && error.message && error.message.includes("Script error")) {
43
        return null;
44
      }
45
    }
46
    return event;
47
  },
48
});
49
```
50

51
### Client Management
52

53
Manage the active Sentry client instance.
54

55
```typescript { .api }
56
/**
57
 * Get the current active client
58
 * @returns Current client instance or undefined
59
 */
60
function getClient(): Client | undefined;
61

62
/**
63
 * Set the current client
64
 * @param client - Client instance to set as current
65
 */
66
function setCurrentClient(client: Client): void;
67

68
/**
69
 * Check if the SDK has been initialized
70
 * @returns True if SDK is initialized
71
 */
72
function isInitialized(): boolean;
73

74
/**
75
 * Check if the SDK is enabled and will capture events
76
 * @returns True if SDK is enabled
77
 */
78
function isEnabled(): boolean;
79
```
80

81
### Compatibility Functions
82

83
API compatibility functions for loader integration.
84

85
```typescript { .api }
86
/**
87
 * Force load the SDK (no-op for browser)
88
 */
89
function forceLoad(): void;
90

91
/**
92
 * Execute callback when SDK is loaded
93
 * @param callback - Function to execute
94
 */
95
function onLoad(callback: () => void): void;
96
```
97

98
### Default Integrations
99

100
Get the default integrations for browser environments.
101

102
```typescript { .api }
103
/**
104
 * Get default integrations for the browser SDK
105
 * @param options - Configuration options
106
 * @returns Array of default integrations
107
 */
108
function getDefaultIntegrations(options: Options): Integration[];
109
```
110

111
## Configuration Types
112

113
### Browser Options
114

115
```typescript { .api }
116
interface BrowserOptions extends CoreOptions<BrowserTransportOptions> {
117
  /** Data Source Name - URL for sending events to Sentry */
118
  dsn?: string;
119
  
120
  /** Enable debug mode for detailed logging */
121
  debug?: boolean;
122
  
123
  /** Environment name (e.g., production, development) */
124
  environment?: string;
125
  
126
  /** Release version identifier */
127
  release?: string;
128
  
129
  /** Sample rate for error events (0.0 to 1.0) */
130
  sampleRate?: number;
131
  
132
  /** Sample rate for performance traces (0.0 to 1.0) */
133
  tracesSampleRate?: number;
134
  
135
  /** Sample rate for profiling (0.0 to 1.0) */
136
  profilesSampleRate?: number;
137
  
138
  /** Maximum number of breadcrumbs to keep */
139
  maxBreadcrumbs?: number;
140
  
141
  /** Attach stack traces to captured messages */
142
  attachStacktrace?: boolean;
143
  
144
  /** Send default PII (personally identifiable information) */
145
  sendDefaultPii?: boolean;
146
  
147
  /** Skip browser extension detection check */
148
  skipBrowserExtensionCheck?: boolean;
149
  
150
  /** Propagate W3C traceparent header in addition to sentry-trace */
151
  propagateTraceparent?: boolean;
152
  
153
  /** Base URL for lazy loading integrations */
154
  cdnBaseUrl?: string;
155
  
156
  /** Array of integrations to install */
157
  integrations?: Integration[];
158
  
159
  /** Default integrations (null to disable all) */
160
  defaultIntegrations?: Integration[] | null;
161
  
162
  /** Event filtering function called before sending */
163
  beforeSend?: (event: Event, hint: EventHint) => Event | null | PromiseLike<Event | null>;
164
  
165
  /** Breadcrumb filtering function */
166
  beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null;
167
  
168
  /** Custom transport function */
169
  transport?: (options: BrowserTransportOptions) => Transport;
170
  
171
  /** Stack parser for processing error stack traces */
172
  stackParser?: StackParser;
173
  
174
  /** Tags to be applied to all events */
175
  initialScope?: {
176
    tags?: { [key: string]: Primitive };
177
    user?: User;
178
    level?: SeverityLevel;
179
    fingerprint?: string[];
180
  };
181
}
182
```
183

184
### Browser Client
185

186
```typescript { .api }
187
/**
188
 * The Sentry Browser SDK Client class
189
 */
190
class BrowserClient extends Client<BrowserClientOptions> {
191
  /**
192
   * Creates a new Browser SDK client instance
193
   * @param options - Configuration options for this client
194
   */
195
  constructor(options: BrowserClientOptions);
196
  
197
  /**
198
   * Create an event from an exception
199
   * @param exception - The exception to convert
200
   * @param hint - Additional event hint information
201
   * @returns Promise resolving to the created event
202
   */
203
  eventFromException(exception: unknown, hint?: EventHint): PromiseLike<Event>;
204
  
205
  /**
206
   * Create an event from a message
207
   * @param message - The message to convert
208
   * @param level - Severity level
209
   * @param hint - Additional event hint information
210
   * @returns Promise resolving to the created event
211
   */
212
  eventFromMessage(
213
    message: ParameterizedString,
214
    level?: SeverityLevel,
215
    hint?: EventHint
216
  ): PromiseLike<Event>;
217
}
218
```
219

220
### Transport Options
221

222
```typescript { .api }
223
interface BrowserTransportOptions extends BaseTransportOptions {
224
  /** Fetch API init parameters */
225
  fetchOptions?: RequestInit;
226
  
227
  /** Custom headers for the transport */
228
  headers?: { [key: string]: string };
229
}
230
```
231

232
## Default Integration List
233

234
The browser SDK includes these integrations by default:
235

236
- **inboundFiltersIntegration** - Filters unwanted events and exceptions
237
- **functionToStringIntegration** - Preserves function names in stack traces
238
- **browserApiErrorsIntegration** - Captures browser API errors
239
- **breadcrumbsIntegration** - Automatic breadcrumb collection
240
- **globalHandlersIntegration** - Global error and unhandled promise handlers
241
- **linkedErrorsIntegration** - Captures linked/caused-by errors
242
- **dedupeIntegration** - Prevents duplicate events
243
- **httpContextIntegration** - Adds HTTP request context
244
- **browserSessionIntegration** - Session tracking
245

246
## Environment Detection
247

248
The SDK automatically detects browser extension environments and warns against improper usage. Use `skipBrowserExtensionCheck: true` to bypass this check if it incorrectly flags your setup.
249

250
## Error Handling
251

252
If initialization fails due to invalid configuration or browser extension detection, the function returns `undefined` and logs appropriate warnings to the console.