--- title: "APIs" description: "Learn more about APIs of the SDK." url: https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis/ --- # APIs for Cordova This page shows all available top-level APIs of the SDK. You can use these APIs as the primary way to: * Configure the SDK after initialization * Manually capture different types of events * Enrich events with additional data * ... and more! These APIs are functions that you can use as follows - they are all available on the top-level `Sentry` object: ```javascript import * as Sentry from "sentry-cordova"; Sentry.setTag("tag", "value"); ``` ## [Available APIs](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#available-apis) ## [Core APIs](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#core-apis) ### [init](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#init) ``` function init(options: InitOptions): Client | undefined ``` Initialize the SDK with the given options. See [Options](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/options.md) for the options you can pass to `init`. ### [addEventProcessor](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#addEventProcessor) ``` function addEventProcessor(processor: EventProcessor): void ``` Parameters processor ``` (event: Event, hint: EventHint) => Event | null | Promise ``` Adds an event processor to the SDK. An event processor receives every event before it is sent to Sentry. It can either mutate the event (and return it) or return `null` to discard the event. Event processors can also return a promise, but it is recommended to use this only when necessary as it slows down event processing. Event processors added via `Sentry.addEventProcessor()` will be applied to all events in your application. If you want to add an event processor that only applies to certain events, you can also add one to a scope as follows: ```javascript Sentry.withScope((scope) => { scope.addEventProcessor((event) => { // this will only be applied to events captured within this scope return event; }); Sentry.captureException(new Error("test")); }); ``` What is the difference to \`beforeSend\`? `beforeSend` runs after all event processors and receives the final error or message event before it is sent. Event processors added with `addEventProcessor` run in an undetermined order, so another processor may still change the event afterward. You can configure one `beforeSend` callback and add multiple event processors with `addEventProcessor()`. Event processors also run on transaction events, followed by `beforeSendTransaction`. You can configure one `beforeSendTransaction` callback. ### [nativeCrash](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#nativeCrash) ``` function nativeCrash(): void ``` Crashes the app on the native layer, if the native SDK is enabled. Only use this to test that native crashes are reported to Sentry. ## [Capturing Events](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#capturing-events) ### [captureException](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#captureException) ``` function captureException( exception: unknown, captureContext?: CaptureContext ): EventId ``` Parameters exception\* ``` unknown ``` The exception to capture. For best results, pass an \`Error\` object but it accepts any kind of value. captureContext ``` CaptureContext { user?: User { id?: string | number, email?: string, ip_address?: string, username?: string, } level?: "fatal" | "error" | "warning" | "log" | "info" | "debug", // Additional data that should be sent with the exception. extra?: Record, // Additional tags that should be sent with the exception. tags?: Record, contexts?: Record>, fingerprint?: string[], } ``` Optional additional data to attach to the Sentry event. Capture an exception event and send it to Sentry. Note that you can pass not only `Error` objects, but also other objects as `exception` - in that case, the SDK will attempt to serialize the object for you, and the stack trace will be generated by the SDK and may be less accurate. ### [captureMessage](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#captureMessage) ``` function captureMessage( message: string, captureContext?: CaptureContext | SeverityLevel ): EventId ``` Parameters message\* ``` string ``` The message to capture. captureContext ``` CaptureContext { user?: User { id?: string | number, email?: string, ip_address?: string, username?: string, } level?: "fatal" | "error" | "warning" | "log" | "info" | "debug", // Additional data that should be sent with the exception. extra?: Record, // Additional tags that should be sent with the exception. tags?: Record, contexts?: Record>, fingerprint?: string[], } ``` Optional additional data to attach to the Sentry event. Capture a message event and send it to Sentry. Optionally, instead of a `CaptureContext`, you can also pass a `SeverityLevel` as second argument, e.g. `"error"` or `"warning"`. Messages show up as issues on your issue stream, with the message as the issue name. ## [Enriching Telemetry](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#enriching-telemetry) ### [setTag](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setTag) ``` function setTag(key: string, value: string): void ``` Set a tag to be sent with Sentry events. * Tag keys have a maximum length of 200 characters and can contain only letters (`a-zA-Z`), numbers (`0-9`), underscores (`_`), periods (`.`), colons (`:`), and dashes (`-`). * Tag values have a maximum length of 200 characters and they cannot contain the newline (`\n`) character. ### [setTags](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setTags) ``` function setTags(tags: Record): void ``` Set multiple tags to be sent with Sentry events. ### [setContext](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setContext) ``` function setContext(name: string, context: Record): void ``` Set a context to be sent with Sentry events. Custom contexts allow you to attach arbitrary data to an event. You cannot search these, but they are viewable on the issue page - if you need to be able to filter for certain data, use [tags](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setTag) instead. Pass `null` as the context value to clear a previously set context. There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. By default, Sentry SDKs normalize nested structured context data up to three levels deep. Any data beyond this depth will be trimmed and marked using its type instead. To adjust this default, use the [`normalizeDepth`](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/options.md#normalize-depth) SDK option. Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts/). Example Context data is structured and can contain any data you want: ```javascript Sentry.setContext("character", { name: "Mighty Fighter", age: 19, attack_type: "melee", }); ``` ### [setExtra](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setExtra) ``` function setExtra(name: string, extra: unknown): void ``` Set additional data to be sent with Sentry events. ### [setExtras](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setExtras) ``` function setExtras(extras: Record): void ``` Set multiple additional data entries to be sent with Sentry events. ### [setUser](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#setUser) ``` function setUser(user: User | null): void ``` Parameters user ``` User { // Your internal identifier for the user id?: string | number, // Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities email?: string, // Typically used as a better label than the internal id username?: string, // The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user ip_address?: string, } ``` Set a user to be sent with Sentry events. Set to `null` to unset the user. In addition to the specified properties of the `User` object, you can also add additional arbitrary key/value pairs. Capturing User IP-Addresses If the users' `ip_address` is set to `"{{ auto }}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. To ensure your users' IP addresses are never stored in your event data, you can go to your project settings, click on ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/), and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data scrubbing](https://docs.sentry.io/security-legal-pii/scrubbing.md) to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. ### [addBreadcrumb](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#addBreadcrumb) ``` function addBreadcrumb(breadcrumb: Breadcrumb, hint?: Hint): void ``` Parameters breadcrumb\* ``` Breadcrumb { // If a message is provided, it is rendered as text with all whitespace preserved. message?: string, // The type influences how a breadcrumb is rendered in Sentry. When in doubt, leave it at `default`. type?: "default" | "debug" | "error" | "info" | "navigation" | "http" | "query" | "ui" | "user", // The level is used in the UI to emphasize or deemphasize the breadcrumb. level?: "fatal" | "error" | "warning" | "log" | "info" | "debug", // Typically it is a module name or a descriptive string. For instance, `ui.click` could be used to indicate that a click happened category?: string, // Additional data that should be sent with the breadcrumb. data?: Record, } ``` hint ``` Record ``` A hint object containing additional information about the breadcrumb. You can manually add breadcrumbs whenever something interesting happens. For example, you might manually record a breadcrumb if the user authenticates or another state change occurs. ## [Tracing](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#tracing) ### [startSpan](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#startSpan) ``` function startSpan(options: StartSpanOptions, callback: (span: Span) => T): T ``` Parameters options\* ``` StartSpanOptions { name: string, // Attributes to add to the span. attributes?: Record, // The timestamp to use for the span start. If not provided, the current time will be used. startTime?: number, // The operation name for the span. This is used to group spans in the UI op?: string, // If true, the span will be forced to be sent as a transaction, even if it is not the root span. forceTransaction?: boolean, // The scope to start the span on. If not provided, the current scope will be used. scope?: Scope, // If true, the span will only be created if there is an active span. onlyIfParent?: boolean, } ``` callback\* ``` (span: Span) => T ``` Starts a new span, that is active in the provided callback. This span will be a child of the currently active span, if there is one. Any spans created inside of the callback will be children of this span. The started span will automatically be ended when the callback returns, and will thus measure the duration of the callback. The callback can also be an async function. Examples ```javascript // Synchronous example Sentry.startSpan({ name: "my-span" }, (span) => { measureThis(); }); // Asynchronous example const status = await Sentry.startSpan( { name: "my-span" }, async (span) => { const status = await doSomething(); return status; }, ); ``` See [Tracing Instrumentation](https://docs.sentry.io/platforms/javascript/guides/cordova/tracing/instrumentation.md) for more information on how to work with spans. ### [startInactiveSpan](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#startInactiveSpan) ``` function startInactiveSpan(options: StartSpanOptions): Span ``` Parameters options\* ``` StartSpanOptions { name: string, // Attributes to add to the span. attributes?: Record, // The timestamp to use for the span start. If not provided, the current time will be used. startTime?: number, // The operation name for the span. This is used to group spans in the UI op?: string, // If true, the span will be forced to be sent as a transaction, even if it is not the root span. forceTransaction?: boolean, // The scope to start the span on. If not provided, the current scope will be used. scope?: Scope, // If true, the span will only be created if there is an active span. onlyIfParent?: boolean, } ``` Starts a new span. This span will be a child of the currently active span, if there is one. The returned span has to be ended manually via `span.end()` when the span is done. Examples ```javascript const span = Sentry.startInactiveSpan({ name: "my-span" }); doSomething(); span.end(); ``` See [Tracing Instrumentation](https://docs.sentry.io/platforms/javascript/guides/cordova/tracing/instrumentation.md) for more information on how to work with spans. ### [startSpanManual](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#startSpanManual) ``` function startSpanManual(options: StartSpanOptions, callback: (span: Span) => T): T ``` Parameters options\* ``` StartSpanOptions { name: string, // Attributes to add to the span. attributes?: Record, // The timestamp to use for the span start. If not provided, the current time will be used. startTime?: number, // The operation name for the span. This is used to group spans in the UI op?: string, // If true, the span will be forced to be sent as a transaction, even if it is not the root span. forceTransaction?: boolean, // The scope to start the span on. If not provided, the current scope will be used. scope?: Scope, // If true, the span will only be created if there is an active span. onlyIfParent?: boolean, } ``` callback\* ``` (span: Span) => T ``` Starts a new span, that is active in the provided callback. This span will be a child of the currently active span, if there is one. Any spans created inside of the callback will be children of this span. The started span will *not* automatically end - you have to call `span.end()` when the span is done. Please note that the span will still only be the parent span of spans created inside of the callback, while the callback is active. In most cases, you will want to use `startSpan` or `startInactiveSpan` instead. Examples ```javascript const status = await Sentry.startSpanManual( { name: "my-span" }, async (span) => { const status = await doSomething(); span.end(); return status; }, ); ``` See [Tracing Instrumentation](https://docs.sentry.io/platforms/javascript/guides/cordova/tracing/instrumentation.md) for more information on how to work with spans. ## [Scopes](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#scopes) See [Scopes](https://docs.sentry.io/platforms/javascript/guides/cordova/enriching-events/scopes.md) for more information on how to use scopes. ### [withScope](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#withScope) ``` function withScope(callback: (scope: Scope) => void): void ``` Forks the current scope and calls the callback with the forked scope. ### [getCurrentScope](https://docs.sentry.io/platforms/javascript/guides/cordova/configuration/apis.md#getCurrentScope) ``` function getCurrentScope(): Scope ``` Returns the [current scope](https://docs.sentry.io/platforms/javascript/guides/cordova/enriching-events/scopes.md#current-scope). Note that in most cases you should not use this API, but instead use `withScope` to generate and access a local scope. There are no guarantees about the consistency of `getCurrentScope` across different parts of your application, as scope forking may happen under the hood at various points.