apps-backend-api

Variables

StudioHost

const StudioHost: StudioBackendApi;

StudioHost singleton that provides methods for apps to use on the backend.

Interfaces

BackendApp

Entry point format for modular apps. Modular apps are meant to run in the context of a startup app. until 2026.09

Alpha

This API should not be used in production and may be trimmed from a public release.

Properties

Property	Type	Description
cleanup?	() => Promise<void>	Performs any necessary cleanup before consuming application deactivates. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
initialize?	() => Promise<void>	Performs any startup logic required by packages. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

---

StudioBackendApi

Extended by

• StartupAppsBackendApi

Methods

addUserPreferencesSchemaFile()

addUserPreferencesSchemaFile(schemaPath): Promise<void>;

Adds a schema json file to the user preferences.

Parameters

Parameter	Type	Description
schemaPath	string	Path to the schema json file.

Returns

Promise<void>

appChannel()

appChannel(channel): string;

Wraps given IPC channel name with a prefix matching the app name. Ensures IPC channel is unique among apps. Not using this wrapper might cause IPC channel name clashes among different apps. Use StudioApp.appChannel to wrap the IPC channel in the frontend.

Parameters

Parameter	Type	Description
channel	string	unique channel name within your app.

Returns

string

channel name that is unique among loaded apps.

attachRpcInterface()

attachRpcInterface<T>(definition): void;

Attach an RPC interface to the backend.

Deprecated

to be removed in 2027.03, use interfaces property of rpcManager option in startupOptions.

Type Parameters

Type Parameter
T extends RpcInterface

Parameters

Parameter	Type	Description
definition	RpcInterfaceDefinition<T>	RPC interface definition.

Returns

void

finalizeFrontendInitData()

finalizeFrontendInitData(jsonData): void;

Sets the initialization or configuration data for the app’s frontend. This function must be invoked before calling StudioApp.getFrontendInitData() in the frontend. If not invoked, the StudioApp.getFrontendInitData() function will time out. Ideally, finalizeFrontendInitData() should be called at the very beginning of activateBackend().

Parameters

Parameter	Type	Description
jsonData	Record<string, JSONSchemaType>	JSON object containing initialization data.

Returns

void

A Promise that resolves when the data is finalized.

getLocations()

getLocations(): Promise<StudioLocations>;

Returns the locations of folders used by iTwin Studio for storing application-specific files.

Returns

Promise<StudioLocations>

getUrlEnvironmentPrefix()

getUrlEnvironmentPrefix(): UrlEnvironmentPrefix;

Returns

UrlEnvironmentPrefix

the current environment prefix iTwinStudio is in.

Note

it returns url prefix like “dev-”, “qa-” or ""

getUserPreference()

getUserPreference(preferenceName): undefined | JSONSchemaType;

Gets a user preference from the user preferences.

Parameters

Parameter	Type	Description
preferenceName	string	Name of the preference.

Returns

undefined | JSONSchemaType

initializeTelemetry()

initializeTelemetry(
   instrumentalKey,
   enableAutoTracking?,
   recordExceptions?): void;

Initialize telemetry service

Parameters

Parameter	Type	Description
instrumentalKey	string	instrumental key for app insights
enableAutoTracking?	boolean	allow you to configure autoTracking for appInsights, false by default.
recordExceptions?	boolean	allow Studio to post unhandled exceptions for you, true by default.

Returns

void

Throws

if instrumental key is undefined or empty string then this method throws

logError()

logError(error, metaData?): void;

Logs an error, with the category being the app name.

Deprecated

to be removed in 2027.03, please use Logger.logError from @itwin/core-bentley

Parameters

Parameter	Type	Description
error	string	Error message.
metaData?	LoggingMetaData	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

logException()

logException(exception): void;

Logs an exception, with the category being the app name.

Deprecated

to be removed in 2027.03, please use Logger.logException from @itwin/core-bentley…

Parameters

Parameter	Type	Description
exception	unknown	Exception object.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

logInfo()

logInfo(info, metaData?): void;

Logs an info level message, with the category being the app name.

Deprecated

to be removed in 2027.03, please use Logger.logInfo from @itwin/core-bentley

Parameters

Parameter	Type	Description
info	string	Info message.
metaData?	LoggingMetaData	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

logTrace()

logTrace(trace, metaData?): void;

Logs a trace, with the category being the app name.

Deprecated

to be removed in 2027.03, please use Logger.logTrace from @itwin/core-bentley

Parameters

Parameter	Type	Description
trace	string	Trace message.
metaData?	LoggingMetaData	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

logWarning()

logWarning(warning, metaData?): void;

Logs a warning, with the category being the app name.

Deprecated

to be removed in 2027.03, please use Logger.logWarning from @itwin/core-bentley

Parameters

Parameter	Type	Description
warning	string	Warning message.
metaData?	LoggingMetaData	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

postTelemetry()

postTelemetry(telemetry): void;

Sends the telemetry to azure app insights Note: initializeTelemetry needs to be called first before using postTelemetry

Parameters

Parameter	Type	Description
telemetry	StudioTelemetry	telemetry data to send

Returns

void

resolveAssetPath()

resolveAssetPath(pathFromProjectRoot): string;

Resolves the path to the asset file.

Parameters

Parameter	Type	Description
pathFromProjectRoot	string	path to the asset file relative to the project root folder (where package.json is located).

Returns

string

path to the asset file.

Example

const path = StudioHost.resolveAssetPath("assets/my-asset.ext");
// path === "C:/path/to/app/install/dist/assets/my-asset.ext"
fs.readFileSync(path); // read the asset file

runtimeInfo()

runtimeInfo(): StudioHostRuntimeInfo;

runtime information like product flavor and version etc

Returns

StudioHostRuntimeInfo

saveUserPreferences()

saveUserPreferences(newUserPreferences): Promise<void>;

Saves the user preferences in the preferences property database.

Parameters

Parameter	Type	Description
newUserPreferences	UserPreferenceObject	user/overwrite preferences.

Returns

Promise<void>

showOpenDialog()

showOpenDialog(options): Promise<OpenDialogReturnValue>;

Shows a “open file” dialog.

Parameters

Parameter	Type	Description
options	OpenDialogOptions	Electron open dialog options

Returns

Promise<OpenDialogReturnValue>

A Promise that resolves to the open dialog return value

showSaveDialog()

showSaveDialog(options): Promise<SaveDialogReturnValue>;

Shows a “save file” dialog.

Parameters

Parameter	Type	Description
options	SaveDialogOptions	Electron save dialog options

Returns

Promise<SaveDialogReturnValue>

A Promise that resolves to the save dialog return value

Properties

Property	Type	Description
checkInternetConnectivity	() => Promise<InternetConnectivityStatus>	Performs an in-depth check to determine the current internet connectivity status. Recommended to use after http requests throw. until 2026.09 :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
getActiveBriefcase	() => undefined | BriefcaseDb	-
initializeSentry	(initializationOpts) => Promise<undefined | Scope>	Initializes Sentry with the provided options. Note Sentry is only initialized in standard flavors of iTwin Studio.

---

StudioHostRuntimeInfo

Properties

Property	Type
productFlavor	string
productVersion	string
startupApp	object
startupApp.config	Pick<AppConfigJsonSchema, "appId" | "gprId" | "displayNameEnglish" | "displayNameKey">
startupApp.version	string

---

StudioLocations

Locations of folders used by iTwin Studio for storing app-specific files. All paths are determined by the operating system on which the app is running.

Properties

Property	Type	Description
appInstallationDir	string	Directory where iTwin Studio app bundles are installed. App bundles are prefixed with the appId, e.g., appInstallationDir/appId.
appLoggingDir	string	Directory where iTwin Studio saves log files for the currently running app.
baseLoggingDir	string	Root directory where iTwin Studio creates folders for each app to store log files.

---

StudioTelemetry

Telemetry data about a custom event of interest to send to Azure App Insights

Extends

• StudioBaseTelemetry

Properties

Property	Type	Description	Inherited from
additionalProperties?	Record<string, any>	Custom properties	StudioBaseTelemetry.additionalProperties
changesetId?	string	-	StudioBaseTelemetry.changesetId
eventId?	string	Optional Guid that can be used to more accurately identify the telemetry event. This field is required when posting a telemetry event as feature usage to ULAS.	StudioBaseTelemetry.eventId
eventName	string	Human-readable name for the event being tracked	-
iModelId?	string	-	StudioBaseTelemetry.iModelId
iTwinId?	string	-	StudioBaseTelemetry.iTwinId
trackerStartTime?	Date	track time	StudioBaseTelemetry.trackerStartTime