Acrobits IPC SDK

Acrobits IPC SDK is intended to be used by any web based application that is running inside a WebView of an Acrobits Cloudsoftphone native app, to communicate with that native app.

Installation

To get started, run:

## npm
npm install @acrobits/ipc-sdk

## pnpm (recommended)
pnpm add @acrobits/ipc-sdk

## yarn
yarn add @acrobits/ipc-sdk
Copy

Usage

The SDK is built using TypeScript so you should have detailed type information for all available methods and properties.

// import the IPCManager
import { IPCManager } from '@acrobits/ipc-sdk';

// create an instance of IPCManager
const manager = new IPCManager();

// check if we're not running under a host context
if ((await manager.determineContext()) !== 'host') {
  // we are running in standalone mode or the context couldn't be determined
  // handle any cleanup
  return;
}

// setup listeners for the badge query and lifecycle events
manager.onBadgeQueryRequest(() => {
  // determine the updated badge count
  const count = getLatestCountForBadgeFromSomewhere();

  // send the badge update to the host
  manager.badgeUpdate(count);
});

manager.onLifecycleEvent((eventName: string, payload: <string, unknown>) => {
  // do something to handle the lifecycle event
});

// initialize the IPC connection
await manager.initiateConnection();

// update badge count
await manager.badgeUpdate(12);

// match contacts
const matches = await manager.matchContacts([
  {
    type: 'cloudUsername',
    cloudId: 'MY_CLOUD_ID',
    cloudUsername: 'myUsername'
  },
  {
    type: 'uri',
    cloudId: 'MY_CLOUD_ID',
    uri: 'sip:any-sip-uri'
  },
  {
    type: 'uri',
    cloudId: 'MY_CLOUD_ID',
    uri: 'tel:+1234567890'
  }
]);

for (const detailedContact of matches) {
  console.log({
    cloudId: detailedContact.cloudId,
    cloudUsername: detailedContact.cloudUsername,
    displayName: detailedContact.displayName,
    contactLabel: detailedContact.contactLabel,
    type: detailedContact.type,
    uri: detailedContact.uri,
    profilePictureUrl: detailedContact.profilePictureUrl
  });
}
Copy

Translations

Hosts that negotiate IPC wire protocol version 2.5 or higher (shown by manager.negotiatedVersion, independent of this package's npm version) can translate strings with their own translation framework. On older hosts, translate and onTranslationsChanged throw an UnsupportedVersionError, so call them after initiateConnection and catch the error.

// a translation ID, a translation ID with parameters, or a raw literal that is not translated
const title = await manager.translate('app_name');
const missedCalls = await manager.translate({ key: 'missed_calls', count: 2, args: [2] });
const literal = await manager.translate({ raw: 'Acrobits' });

// `null` means the host could not resolve the request
render(title ?? 'Fallback title');

// the host notifies when its translations change; translate the displayed strings again
const unsubscribe = manager.onTranslationsChanged(async () => {
  render((await manager.translate('app_name')) ?? 'Fallback title');
});
Copy

For more details on the available SDK methods and properties, refer to the documentation.