Migration Guide: Connect SDK to Unified SDK

March 25, 2026 · View on GitHub

This guide helps developers migrate from the deprecated @ibm-aspera/connect-sdk-js package to the new unified @ibm-aspera/sdk package.

Overview

The new IBM Aspera JavaScript SDK is a unified SDK that supports all Aspera transfer clients:

IBM Aspera Connect - Browser plugin/extension (what you're using today)
IBM Aspera for desktop - The modern desktop application (recommended for new development)
IBM Aspera HTTP Gateway - Browser-only transfers without a desktop client

The unified SDK provides a single, consistent API regardless of which transfer client is used.

Migration Strategy

We recommend a two-phase approach:

Phase 1: Migrate to the unified SDK using Connect mode - Minimum changes to keep using Connect
Phase 2: Migrate from Connect to IBM Aspera for desktop - When you're ready to switch

Phase 1: Migrate to the Unified SDK (Connect Mode)

This phase involves the minimum changes needed to migrate to the new SDK while continuing to use IBM Aspera Connect as your transfer client.

This can also be used by a web application to support both IBM Aspera Connect and IBM Aspera for desktop simultaneously.

The following guide assumes you were previously using the @ibm-aspera/connect-sdk-js npm package. If instead your application included the Connect SDK via script tag, then update the script tag as follows:

<!-- Before -->
<script src="https://d3gcli72yxqn2z.cloudfront.net/@ibm-aspera/connect-sdk-js/latest/connect-sdk.js"></script>

<!-- After -->
<script src="https://cdn.jsdelivr.net/npm/@ibm-aspera/sdk@0.2.30/dist/js/aspera-sdk.js"></script>

Check npmjs.com for the latest version (https://www.npmjs.com/package/@ibm-aspera/sdk).

Step 1: Update the Package

npm uninstall @ibm-aspera/connect-sdk-js
npm install @ibm-aspera/sdk

Step 2: Update Initialization

Before

import { Connect, ConnectInstaller } from '@ibm-aspera/connect-sdk-js';

const connect = new Connect();
const installer = new ConnectInstaller();

connect.addEventListener(Connect.EVENT.STATUS, (event, status) => {
  if (event === 'status') {
      if (status === 'RUNNING') {
        installer.connected();
      } else if (status === 'FAILED') {
        installer.showDownload();
      } else {
        // Handle other status events
      }
  }
});

connect.initSession('my-app-id');

After

import { initSession } from '@ibm-aspera/sdk';
initSession({
  appId: 'my-app-id',
  connectSettings: {
    useConnect: true,  // This keeps you on Connect
  }
});

When useConnect is set to true the initSession function will handle initializing ConnectInstaller and showing the default Aspera-provided installer modal.

If you have your own custom installer UI or status event handling logic for your web application, you can turn off the default behavior and receive status events yourself. For example:

import { initSession, registerStatusCallback } from '@ibm-aspera/sdk';

// Register a callback for Connect status events
registerStatusCallback(status => {
  if (status === 'RUNNING') {
    // Connect is running
  } else {
    // Handle other status events
  }
});

initSession({
  appId: 'my-app-id',
  connectSettings: {
    useConnect: true,
    hideIncludedInstaller: true, // This disables the default installer modal
  }
});

Supporting Both Clients During Transition

The unified SDK allows you to support both IBM Aspera Connect and IBM Aspera for desktop simultaneously. This is useful for gradual rollouts or when different users have different requirements.

useConnect: true — Forces the SDK to use IBM Aspera Connect
useConnect: false or omitted — Uses IBM Aspera for desktop

You can dynamically choose which client to use based on user preferences, feature flags, or application settings:

import { initSession } from '@ibm-aspera/sdk';

// Example: Allow users to choose their preferred client
const shouldUseConnect = getUserPreference('useConnect'); // Your app's logic

initSession({
  appId: 'my-app-id',
  connectSettings: {
    useConnect: shouldUseConnect,
  }
});

This approach lets you migrate users incrementally while maintaining a single code path.

Step 3: Update Transfer Calls

Before

connect.startTransferPromise(transferSpec, connectSpec)
  .then((result) => {
    console.log('Transfer started', result.transfer_specs[0]);
  });

After

import { startTransfer } from '@ibm-aspera/sdk';

startTransfer(transferSpec, asperaSpec)
  .then((transfer) => {
    console.log('Transfer started', transfer);
  });

Step 4: Update Transfer Monitoring

Before

connect.addEventListener('transfer', (event, data) => {
  if (event === 'transfer') {
    console.log('Transfer updated', data.transfers[0]);
  }
});

After

import { registerActivityCallback } from '@ibm-aspera/sdk';

registerActivityCallback(data => {
  console.log('Transfer updated', data.transfers[0]);
});

Step 5: Update Drag and Drop

Before

connect.setDragDropTargets('body', { drop: true }, result => {
  console.log('Files dropped', result.files);
});

After

import { createDropzone } from '@ibm-aspera/sdk';

createDropzone(
  result => {
    console.log('Files dropped', result.files);
  },
  'body'
);

Step 6: Update Remaining API Calls

Most of the SDK calls available in @ibm-aspera/connect-sdk-js have equivalents in @ibm-aspera/sdk. Most also have similar or identical function signatures to make migration easier.

Note: Most callback-based functions have been migrated to promises-based functions.

`@ibm-aspera/connect-sdk-js`	`@ibm-aspera/sdk`	Notes
`new Connect()` + `initSession()`	`initSession()`
`new ConnectInstaller()`	`initSession()` with `connectSettings`	Installer handling is built into `initSession()`
`addEventListener(Connect.EVENT.STATUS, ...)`	`registerStatusCallback()`
`addEventListener(Connect.EVENT.TRANSFER, ...)`	`registerActivityCallback()`
`removeEventListener()`	`deregisterStatusCallback()` / `deregisterActivityCallback()`
`startTransfer()` `startTransferPromise()` `startTransfers()`	`startTransfer()`
`stopTransfer()`	`stopTransfer()`
`resumeTransfer()`	`resumeTransfer()`
`removeTransfer()`	`removeTransfer()`
`getAllTransfers()`	`getAllTransfers()`
`getTransfer()`	`getTransfer()`
`modifyTransfer()`	`modifyTransfer()`
`showSelectFileDialog()` `showSelectFileDialogPromise()`	`showSelectFileDialog()`
`showSelectFolderDialog()` `showSelectFolderDialogPromise()`	`showSelectFolderDialog()`
`showDirectory()`	`showDirectory()`
`showPreferences()`	`showPreferences()`
`setDragDropTargets()`	`createDropzone()`	See example above
`readAsArrayBuffer()`	`readAsArrayBuffer()`
`readChunkAsArrayBuffer()`	`readChunkAsArrayBuffer()`
`version()`	`getInfo()`	Returns SDK and client info
`getStatus()`	`getStatus()`
`showAbout()`	`showAbout()`
`showPreferencesPage()`	`showPreferencesPage()`
`showSaveFileDialog()`	`showSaveFileDialog()`
`showTransferManager()`	`showTransferManager()`
`showTransferMonitor()`	`showTransferMonitor()`
`authenticate()`	`authenticate()`
`getChecksum()`	`getChecksum()`
`testSshPorts()`	`testSshPorts()`
`start()` / `stop()`	—	Not available

Phase 2: Migrate from Connect to IBM Aspera for Desktop

Note: This section is for when you're ready to move away from Connect to the modern IBM Aspera for desktop application. This is optional but recommended for new web applications.

IBM Aspera for desktop is the recommended transfer client going forward. It offers:

Better performance and reliability
Modern user interface
Active development and support
No browser plugin/extension dependencies

Step 1: Update Initialization

Remove connectSettings from your initSession() call:

import { initSession } from '@ibm-aspera/sdk';

// Before (Connect mode)
initSession({
  appId: 'my-app-id',
  connectSettings: {
    useConnect: true,
    // ... other Connect settings
  },
});

// After (Desktop mode)
initSession({
  appId: 'my-app-id',
});

That's it! All other SDK calls (startTransfer, registerActivityCallback, etc.) remain exactly the same.