Function initSession

initSession(options?: InitOptions): void
Initialize the SDK and begin detecting a transfer client. This function returns immediately — lifecycle status is communicated asynchronously via registerStatusCallback.

The SDK supports three transfer clients. By default, IBM Aspera for desktop is used. Set connectSettings.useConnect to use IBM Aspera Connect instead. Desktop and Connect are mutually exclusive — one or the other is detected, not both.

HTTP Gateway

HTTP Gateway is a server-side component that enables browser-based transfers without a desktop application. It can be used in two modes:
- Sole transport (forceGateway: true): HTTP Gateway is the only transport. No Desktop or Connect detection occurs. Status transitions to RUNNING when the gateway responds successfully, or FAILED if it does not.
- Supplementary transport (forceGateway: false): HTTP Gateway is set up first as an additional transport for browser-based uploads and downloads. The primary transfer client (Desktop or Connect) is then detected separately. If HTTP Gateway setup fails, the primary client is still detected. Features that require a desktop application (native file dialogs, drag and drop, etc.) are only available when the primary client is running.
Status lifecycle

Use registerStatusCallback to receive status updates. Use getStatus to read the current status synchronously at any time.

Desktop path: INITIALIZING → RUNNING (app detected), DEGRADED (timeout but HTTP Gateway is available as a supplementary transport), or FAILED (timeout, no fallback). Detection continues in the background after DEGRADED or FAILED — if the user launches the app later, the status transitions to RUNNING.

Connect path: INITIALIZING → RUNNING, FAILED, OUTDATED, or EXTENSION_INSTALL depending on the state of the Connect browser extension and application.

HTTP Gateway path (forceGateway: true): INITIALIZING → RUNNING or FAILED.
Parameters
- Optionaloptions: InitOptions
  Initialization options. See InitOptions.
Returns void
Example
```
// Use IBM Aspera for desktop (default)
registerStatusCallback(status => {
  if (status === 'RUNNING') {
    // Transfer client is ready — enable UI
  } else if (status === 'FAILED') {
    // Not detected — prompt user to install or launch
  }
});

initSession({ appId: 'my-app' });
```
Example
```
// Use IBM Aspera Connect
initSession({
  appId: 'my-app',
  connectSettings: {
    useConnect: true,
  },
});

*
```
Example
```
// Use HTTP Gateway only
initSession({
  appId: 'my-app',
  httpGatewaySettings: {
    url: 'https://example.com/aspera/http-gwy',
    forceGateway: true,
  },
});

*
```
Example
```
// Use IBM Aspera for desktop with automatic fallback to IBM Aspera Connect
initSession({
  appId: 'my-app',
  connectSettings: {
    fallback: true,
  },
});
```
Example
```
// Use IBM Aspera for desktop with automatic fallback to HTTP Gateway
initSession({
  appId: 'my-app',
  httpGatewaySettings: {
    url: 'https://example.com/aspera/http-gwy',
  },
});

*
```
Example
```
// Use IBM Aspera for desktop or IBM Aspera Connect with automatic fallback to HTTP Gateway
initSession({
  appId: 'my-app',
  connectSettings: {
    fallback: true,
  },
  httpGatewaySettings: {
    url: 'https://example.com/aspera/http-gwy',
  },
});
```
- Defined in app/core.ts:310

Function initSession

HTTP Gateway

Status lifecycle

Parameters

Returns void

Example

Example

Example

Example

Example

Example

Settings

On This Page