App

Control core app behavior including navigation, UI chrome, domain routing, device info, and screen options.

Access: startiapp.App

Methods

`brandId(): Promise<string>`

Returns the brand identifier of the app. The result is cached after the first call.

Returns: Promise<string> —The brand ID string.

Example:

const brandId = await startiapp.App.brandId();
// "example-brand"

`deviceId(): Promise<string>`

Returns a unique identifier for the current app installation. The ID changes if the user uninstalls and reinstalls the app. The result is cached after the first call.

Returns: Promise<string> — The installation ID (UUID format).

Example:

const deviceId = await startiapp.App.deviceId();
// "00000000-0000-0000-0000-000000000000"

`version(): Promise<string>`

Returns the app version string. The version format is major.minor.patch:

Major — a counter that increases when the minor number reaches 1000.
Minor — represents a specific commit in the starti.app codebase.
Patch — the build number, typically used when configuration or build-related changes are made without code changes.

Returns: Promise<string> — The version string.

Example:

const version = await startiapp.App.version();
// "4.28.1"

`platform`

A read-only property that returns the platform the app is running on.

Returns: string — "android", "ios", or "web".

Example:

const platform = startiapp.App.platform;
// "android" | "ios" | "web"

`isStartiappLoaded(): boolean`

Returns whether the starti.app runtime has finished loading.

Returns: boolean —true if the SDK ready event has fired.

Example:

if (startiapp.App.isStartiappLoaded()) {
  console.log("SDK is ready");
}

`addInternalDomain(domain: string): Promise<void>`

For a practical guide to domain handling — including when to use handleAllDomainsInternally() and the difference between the in-app browser and the device's browser — see Handle Domains.

Registers a domain as internal. Internal domains are loaded inside the app's webview.

Parameters:

Parameter	Type	Required	Description
domain	`string`	Yes	The domain to register as internal

Returns: Promise<void>

Example:

await startiapp.App.addInternalDomain("example.com");

`removeInternalDomain(domain: string): Promise<void>`

Removes a domain from the internal domains list.

Parameters:

Parameter	Type	Required	Description
domain	`string`	Yes	The domain to remove

Returns: Promise<void>

Example:

await startiapp.App.removeInternalDomain("example.com");

`getInternalDomains(): Promise<string[]>`

Returns the list of registered internal domains.

Returns: Promise<string[]> —Array of internal domain strings.

Example:

const domains = await startiapp.App.getInternalDomains();
console.log(domains);
// ["example.com", "api.example.com"]

`addExternalDomains(...domains: RegExp[]): Promise<void>`

Registers domains as external using regex patterns. External domains open in the in-app browser.

Parameters:

Parameter	Type	Required	Description
...domains	`RegExp[]`	Yes	One or more regex patterns matching external domains

Returns: Promise<void>

Example:

await startiapp.App.addExternalDomains(/example\.com/, /other\.org/);

`removeExternalDomains(...domains: RegExp[]): Promise<void>`

Removes domains from the external domains list.

Parameters:

Parameter	Type	Required	Description
...domains	`RegExp[]`	Yes	The regex patterns to remove

Returns: Promise<void>

Example:

await startiapp.App.removeExternalDomains(/example\.com/);

`getExternalDomains(): Promise<RegexDto[]>`

Returns the list of registered external domain patterns.

Returns: Promise<RegexDto[]> —Array of regex pattern objects.

Example:

const externalDomains = await startiapp.App.getExternalDomains();
console.log(externalDomains);
// [{ pattern: "example\\.com", flags: "" }]

`handleAllDomainsInternally(): Promise<void>`

Treats all domains as internal, except those explicitly added as external. This is a session-only setting and resets on app restart.

Returns: Promise<void>

Example:

await startiapp.App.handleAllDomainsInternally();

`restoreDefaultDomainHandling(): Promise<void>`

Restores the default domain handling behavior where unknown domains are treated as external.

Returns: Promise<void>

Example:

await startiapp.App.restoreDefaultDomainHandling();

`openExternalBrowser(url: string): Promise<void>`

Opens a URL in the device's system browser.

Parameters:

Parameter	Type	Required	Description
url	`string`	Yes	The URL to open

Returns: Promise<void>

Example:

await startiapp.App.openExternalBrowser("https://example.com");

`setStatusBar(options: SetStatusBarOptions): void`

Configures the status bar appearance.

Parameters:

Parameter	Type	Required	Description
options	`SetStatusBarOptions`	Yes	Status bar configuration

Example:

startiapp.App.setStatusBar({
  hideText: false,
  darkContent: true,
  removeSafeArea: false,
  safeAreaBackgroundColor: "#ffffff",
});

`hideStatusBar(): Promise<void>`

Hides the device status bar.

Returns: Promise<void>

Example:

await startiapp.App.hideStatusBar();

`showStatusBar(): Promise<void>`

Shows the device status bar.

Returns: Promise<void>

Example:

await startiapp.App.showStatusBar();

`setSafeAreaBackgroundColor(color: string): Promise<void>`

Sets the background color of the safe area (notch / home indicator region).

Parameters:

Parameter	Type	Required	Description
color	`string`	Yes	CSS color value

Returns: Promise<void>

Example:

await startiapp.App.setSafeAreaBackgroundColor("#000000");

`setSpinner(options: SpinnerOptions): Promise<void>`

Configures the navigation loading spinner. This is particularly useful for traditional multi-page applications where clicking a link loads an entirely new HTML page. Since the app does not show a progress bar or other loading indicator during page navigation, the spinner makes it clear that new content is being loaded. By default, the spinner only appears after 250 milliseconds, so it stays hidden if the page loads quickly.

Parameters:

Parameter	Type	Required	Description
options	`SpinnerOptions`	Yes	Spinner configuration

Returns: Promise<void>

Example:

await startiapp.App.setSpinner({
  show: true,
  color: "#3498db",
  afterMilliseconds: 300,
  excludedDomains: ["cdn.example.com"],
});

`showSpinner(options?: SpinnerOptions): Promise<void>`

Shows the navigation loading spinner, optionally with configuration.

Parameters:

Parameter	Type	Required	Description
options	`SpinnerOptions`	No	Optional spinner configuration

Returns: Promise<void>

Example:

await startiapp.App.showSpinner();

// With options
await startiapp.App.showSpinner({
  show: true,
  color: "#e74c3c",
  afterMilliseconds: 500,
  excludedDomains: [],
});

`hideSpinner(): Promise<void>`

Hides the navigation loading spinner.

Returns: Promise<void>

Example:

await startiapp.App.hideSpinner();

`pushOptions(options: InitializeParams): void`

Pushes a set of UI options onto the options stack. This lets you temporarily override app options and restore them later with popOptions().

Parameters:

Parameter	Type	Required	Description
options	`InitializeParams`	Yes	The options to push

Example:

startiapp.App.pushOptions({
  allowZoom: false,
  allowRotation: false,
  statusBar: {
    hideText: true,
    darkContent: false,
    removeSafeArea: true,
  },
});

`popOptions(): void`

Pops the most recent options from the options stack, restoring the previous state.

Example:

startiapp.App.popOptions();

`enableScreenRotation(): Promise<void>`

Enables the device screen to rotate with the device orientation.

Returns: Promise<void>

Example:

await startiapp.App.enableScreenRotation();

`disableScreenRotation(): Promise<void>`

Locks the screen orientation, preventing rotation.

Returns: Promise<void>

Example:

await startiapp.App.disableScreenRotation();

`enableSwipeNavigation(): Promise<void>`

Enables swipe gestures for back/forward navigation.

Returns: Promise<void>

Example:

await startiapp.App.enableSwipeNavigation();

`disableSwipeNavigation(): Promise<void>`

Disables swipe gestures for navigation.

Returns: Promise<void>

Example:

await startiapp.App.disableSwipeNavigation();

`openSettings(): Promise<void>`

Opens the device settings page for the app.

Returns: Promise<void>

Example:

await startiapp.App.openSettings();

`setAppIcon(iconName: string): Promise<void>`

Changes the app's home screen icon to one of the alternate icons that are built into the app. The available icons are configured in the starti.app Manager and bundled when the app is built.

Adding new icons requires publishing a new version of the app through Apple and Google's review process — you cannot add icons dynamically at runtime.

Parameters:

Parameter	Type	Required	Description
iconName	`string`	Yes	Name of the alternate icon (must match one returned by `getAvailableIcons()`)

Returns: Promise<void>

Example:

const icons = await startiapp.App.getAvailableIcons();
// ["default", "dark-icon", "holiday-icon"]

await startiapp.App.setAppIcon("dark-icon");

`getCurrentIcon(): Promise<string>`

Returns the name of the currently active app icon.

Returns: Promise<string> —The current icon name.

Example:

const currentIcon = await startiapp.App.getCurrentIcon();
console.log(currentIcon);

`getAvailableIcons(): Promise<string[]>`

Returns the list of available alternate app icons.

Returns: Promise<string[]> —Array of icon names.

Example:

const icons = await startiapp.App.getAvailableIcons();
console.log(icons);
// ["default", "dark-icon", "holiday-icon"]

`getAppUrl(): Promise<string>`

Returns the currently configured app URL.

Returns: Promise<string> —The app URL.

Example:

const url = await startiapp.App.getAppUrl();

`setAppUrl(url: string): Promise<void>`

Sets the app's base URL. The app will load this URL on next launch.

Parameters:

Parameter	Type	Required	Description
url	`string`	Yes	The URL to set

Returns: Promise<void>

Example:

await startiapp.App.setAppUrl("https://example.com");

`resetAppUrl(): Promise<void>`

Resets the app URL to its default value.

Returns: Promise<void>

Example:

await startiapp.App.resetAppUrl();

`vibrate(intensity: VibrationIntensity): Promise<void>`

For a practical guide to vibration — including CSS classes that trigger vibration without JavaScript — see Vibration.

Triggers device vibration with the specified intensity.

Parameters:

Parameter	Type	Required	Description
intensity	`VibrationIntensity`	Yes	The vibration intensity level

Returns: Promise<void>

Example:

// VibrationIntensity values: 0 = Low, 1 = Medium, 2 = High, 3 = Intense
await startiapp.App.vibrate(1); // Medium

`requestReview(): Promise<void>`

Prompts the user to rate the app in the app store. The system controls when and whether the prompt is actually shown.

This only works in the production version of the app (downloaded from the App Store or Google Play). During development and testing, the review prompt will not appear.

Returns: Promise<void>

Example:

await startiapp.App.requestReview();

`requestAppTracking(): Promise<void>`

Prompts the user to allow app tracking (iOS App Tracking Transparency).

The easiest way to trigger this is by adding a terms-and-conditions step to the Intro Flow in the starti.app Manager. The tracking prompt is then shown automatically when the user accepts the terms — no custom JavaScript needed.

Returns: Promise<void>

Example:

await startiapp.App.requestAppTracking();

Events

`navigatingPage`

Fired when the app is navigating to a new page.

Event data: NavigatingPageEvent

Example:

startiapp.App.addEventListener("navigatingPage", (event) => {
  console.log("Navigating to:", event.detail.url);
  console.log("Opens external:", event.detail.opensExternalbrowser);
});

`appInForeground`

Fired when the app comes back to the foreground (e.g. user switches back to the app).

Event data: void

Example:

startiapp.App.addEventListener("appInForeground", () => {
  console.log("App is back in foreground");
  // Refresh data, reconnect sockets, etc.
});

Types

`NavigatingPageEvent`

interface NavigatingPageEvent {
  url: string;
  opensExternalbrowser: boolean;
}

`VibrationIntensity`

enum VibrationIntensity {
  Low = 0,
  Medium = 1,
  High = 2,
  Intense = 3,
}

`SetStatusBarOptions`

type SetStatusBarOptions = SafeAreaSideOptions & {
  hideText: boolean;
  darkContent: boolean;
  advancedSafeAreaOptions?: AdvancedSafeAreaOptions;
};

`SafeAreaSideOptions`

type SafeAreaSideOptions =
  | { removeSafeArea: false; safeAreaBackgroundColor: string }
  | { removeSafeArea: true };

`AdvancedSafeAreaOptions`

interface AdvancedSafeAreaOptions {
  top?: SafeAreaSideOptions;
  bottom?: SafeAreaSideOptions;
}

`SpinnerOptions`

interface SpinnerOptions {
  afterMilliseconds: number;
  show: boolean;
  color: string;
  excludedDomains: string[];
}

`InitializeParams`

interface InitializeParams {
  allowZoom?: boolean;
  allowRotation?: boolean;
  allowDrag?: boolean;
  allowScrollBounce?: boolean;
  allowHighligt?: boolean;
  allowSwipeNavigation?: boolean;
  spinner?: Partial<SpinnerOptions>;
  statusBar?: SetStatusBarOptions;
}

`RegexDto`

interface RegexDto {
  pattern: string;
  flags: string;
}

On this page