Get App Identity

Use getCurrentApp() to discover the identity of the app that your code runs in. The SDK resolves the running app’s namespace, name, and an addressable qualified name, so you can scope requests and target features to the current app. For example, use the app identity in these cases:

Scope a call to your app, such as when you run a CMS search
Pass the qualified name of your app as an addressable app name

Import getCurrentApp from the @salesforce/platform-sdk package.

1import { getCurrentApp } from "@salesforce/platform-sdk";
2
3const app = await getCurrentApp();
4const identity = app.identity;

getCurrentApp(options?)

Resolves the identity of the running app.

1async function getCurrentApp(options?: CurrentAppOptions): Promise<CurrentApp>;

Parameters

Parameter	Type	Description
`options?`	`CurrentAppOptions`	Optional configuration. Extends `SDKOptions` with a `surface` override.

Returns

1Promise<CurrentApp>

getCurrentApp() resolves to a CurrentApp object. If you use getCurrentApp() outside of a web app or micro-frontend, such as in local development, CurrentApp is returned without the identity object.

CurrentApp Interface

Describes the running app. The identity object is present only when the runtime provides app identity. identity can be undefined, such as when it’s called in local development, or if appName is missing.

1interface CurrentApp {
2  readonly identity?: AppIdentity;
3}

AppIdentity Interface

Describes the identity of the running app.

1interface AppIdentity {
2  namespace: string;
3  appName: string;
4  qualifiedName: string;
5  bundleId?: string;
6}

The AppIdentity interface has these properties.

Property	Type	Description
`namespace`	`string`	The app’s namespace, which defaults to `c` when the org doesn’t use a registered namespace.
`appName`	`string`	The developer name of the UI bundle.
`qualifiedName`	`string`	The addressable app name in the format `namespace__appName`, for example, `MyNs__MyBundle`.
`bundleId?`	`string`	The record ID of the UI bundle, provided by the runtime. Defaults to `undefined` in local development.

Usage

Check that identity is defined before you use it. If an app identity isn’t available, the SDK resolves to a CurrentApp without an identity object instead of throwing, so your app keeps rendering.

1import { getCurrentApp } from "@salesforce/platform-sdk";
2
3const app = await getCurrentApp();
4
5if (app.identity) {
6  const targetIds = [app.identity.qualifiedName]; // ["MyNs__MyBundle"]
7}

To use bundleId, read it with a fallback and validate it before you use it. bundleId defaults to undefined in local development.

1export async function getBundleId(): Promise<string> {
2  const app = await getCurrentApp();
3  return app.identity?.bundleId ?? "";
4}

Since getCurrentApp() never rejects, you don’t need a .catch() block. Handle the absence of identity in your code by checking that identity is defined, read bundleId with a fallback, and provide your default behavior when either is missing.

Example: Use App Identity in a React Component

Resolve the app identity inside an effect, and guard the asynchronous result against a component that unmounts before the promise settles. It’s recommended to gate your logic on the value as identity can be undefined, such as in local development or when appName is missing.

1import { useEffect, useState } from "react";
2import { getCurrentApp } from "@salesforce/platform-sdk";
3
4function useBundleId(): string | undefined {
5  const [bundleId, setBundleId] = useState<string>();
6
7  useEffect(() => {
8    let cancelled = false;
9
10    // getCurrentApp() resolves without rejecting, so you don't need a .catch().
11    // Handle the realistic case instead: the app resolves, but identity
12    // (and bundleId) can be undefined on surfaces that don't provide it.
13    getCurrentApp().then((app) => {
14      if (cancelled) return;
15
16      if (!app.identity?.bundleId) {
17        // No bundleId on this surface. Fall back to your default behavior.
18        setBundleId(undefined);
19        return;
20      }
21
22      setBundleId(app.identity.bundleId);
23    });
24
25    return () => {
26      cancelled = true;
27    };
28  }, []);
29
30  return bundleId;
31}

Call getCurrentApp() where you need the identity. The SDK resolves the ambient app each time, so you don’t cache the result in an app context or provider.