Sync Audio SDK for Web: Quickstart

The Aircore Sync Audio SDK for Web allows you to add high-quality, real-time voice chat to your web app quickly and easily without the need to understand the complexities of building a real-time system on your own.

Apps that use the Aircore Sync Audio SDK for Web automatically take advantage of Aircore's advanced media optimization and adaptation framework and leverage Aircore's world-wide media distribution system.

Sync Web

Installation

The recommended way of installing is using NPM Package Manager.

Install the Sync Audio SDK using the following command

npm install @aircore/aircore-panel-core @aircore/aircore-media-panel

Alternatively, you can install the standalone Sync Audio SDK using the CDN

<script type="importmap">
  {
    "imports": {
      "@aircore/aircore-panel-core": "https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"
    }
  }
</script>
<script src="https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"></script>
<script src="https://unpkg.com/@aircore/aircore-media-panel/dist/index.js"></script>

or via

<script type="importmap">
  {
    "imports": {
      "@aircore/aircore-panel-core": "https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"
    }
  }
</script>
<script type="module">
  import { createClientWithPublishableKey } from 'https://unpkg.com/@aircore/aircore-panel-core/dist/index.js';
  import { MediaPanel } from 'https://unpkg.com/@aircore/aircore-media-panel/dist/index.js';
</script>

API keys

To start using the Sync Audio SDK you will need to create an app in the Developer Console and choose between one of the two different API Keys provided to you. To learn more about the two different API Keys so that you can choose the right one based on your needs, please refer to Authentication

Copying a publishable API key from the console.

Client initialization with Publishable API Key

import { createClientWithPublishableKey } from '@aircore/aircore-panel-core';
import { MediaPanel } from '@aircore/aircore-media-panel';

// Create a Sdk client passing the publishable key and the current client id
const client = createClientWithPublishableKey(
  'INSERT_PUBLISHABLE_KEY_HERE',
  'INSERT_USER_ID_HERE'
);

// Set current user name and avatar
client.setUserDisplayName('John Doe');
client.setUserAvatarUrl('https://avatar.com/40');

// Connect to the desired channel
client.connect('INSERT_CHANNEL_ID_HERE');

// Render the panel
const MyPanel = MediaPanel(
  '#myMediaPanel', // Selector DOM target
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
  }
);

Client initialization with Secret API Key/Session Auth token

import { createClientWithSessionAuthToken } from '@aircore/aircore-panel-core';
import { MediaPanel } from '@aircore/aircore-media-panel';

// Create a Sdk client passing the session authorization token and the current client id
const client = createClientWithSessionAuthToken(
  'INSERT_SESSION_AUTHORIZATION_TOKEN_HERE',
  'INSERT_USER_ID_HERE'
);

// Set current user name and avatar
client.setUserDisplayName('John Doe');
client.setUserAvatarUrl('https://avatar.com/40');

// Connect to the desired channel
client.connect('INSERT_CHANNEL_ID_HERE');

// Register to token is about to expire event
client.on('sessionAuthTokenNearingExpiry', function () {
  // Call you backend and get a new Session authorization token
  // Once you have the token, update it on the client
  client.updateAuthToken(newToken);
});

// Render the panel passing a selector, the client and the channel id you want to be connected to
const myPanel = MediaPanel(
  '#myMediaPanel', // A string containing one or more selectors to match or an Element
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
  }
);

Configuration

Configuration of the panel is separated into 2 distinct objects: panelconfiguration: Include all specific Sync panel related configuration (Title, shareLink, Strings (text), etc...) theme: The theme object include all visual configuration of the panels (fonts, colors, etc...)

Here is an example of how you can pass the theme and panelconfiguration object when rendering the Sync panel:

// Render the panel passing a selector, the client and the channel id you want to be connected to
// Selector target needs to be rendered on the page prior to this
const targetElement = document.querySelector('#myMediaPanel');

const myPanel = MediaPanel(
  targetElement,
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
    theme: {
      // You can specify a base theme to start from
      base: 'light',
    }
    config: {
      // You can specify a title for you panel
      title: 'John and Leila call',
    }
  }
);

The Sync panel is composed of 2 distinct states - collapsed and expanded. Here is an example of configuration you can make on the panel:

const myPanelConfiguration = {
  title: 'John and Leila call', // Custom title to your panel
  subtitle: 'Talking about adding a Sync panel', // Custom subtitle
  shareLinkUrl: 'http://yourDomain.com/call/1234', // Custom link to this call in your app

  string: {
    startConversation: "Start", // You can overrides string displayed like this
    ...
  }

  collapseStateOptions: {
    maxAvatars: 5, // Max numbers avatars to show before showing +10 users
    ...
  }

  expandedStateOptions: {
    placement: 'top-left', // The expanded view will be placed relative to your collapse view
    ...
  }
}

It is also possible to launch a panel in collapsed mode only by disabling the expanded state.

const myPanelConfiguration = {
  ...
  expandedStateOptions: {
    enabled: false, // Disabling the expanded view
  }
}

Similarly, you can also disable the collapsed state and only display the expanded state.

const myPanelConfiguration = {
  ...
  collapseStateOptions: {
    enabled: false, // Disabling the expanded view
  }
}

Full Sync panel configuration reference can be found here

User experience

To customize the user experience, you can choose which users can publish audio.

The panel shows all users as they join. By default, users start with a muted microphone. To start publishing audio, users tap the microphone button on the panel.

Create an audience

You can change the panel options and permissions to build an app in which some users speak and others just listen.

To create an audience, you can stop users from unmuting. To hide the microphone button, set showMicrophoneButton to false.

It's best to also keep the audience muted by using permissions. To do this, use a secret API key. You can't use a publishable API key because it lets all users publish audio.

To mute certain users, request and send out session auth tokens that don't allow publishing audio.

Token permissions don't affect the showMicrophoneButton setting. If the setting is true, users that can't publish audio can still see and press the button, but it doesn't do anything.

Automatically publish audio

To have users publish automatically, set autoPublishMicOnJoin to true.

Theming

The Theme configuration is composed by using a base theme and then overriding variables over it to customize the look and feel of your panel.

You can choose either light or dark as a base for your theme:

const myCustomTheme = {
  base: 'dark',
  overrides: {
    // You can override any of the values to your own colors
    primaryColor: '#228B22', // Your Brand color
    textColor: '#FFFFFF',
    backgroundColor: '#000000',
    borderRadius: '20px',
    font: 'Arial', // Or Your custom font face name
    ...
    icons: {
      join: '/assets/join.svg', // Local path to your icon
      ...
  }
}

Theme can be reused across multiple panels as needed. Just defined it somewhere in your app and re-use it every time you render a new panel.

Full theme configuration reference can be found here

Events

The client object provides events you can hook to in order to react to something that is happening on the panel.

For example, you might want to call your backend when a user join a call in order to trigger notification to other users that might want to join the same call.

Here is how an example of how you can subscribe and unsubscribe to events:

function onEventTriggeredCallback() {
  // Your business logic here
}

// Subscribe to an event
client.on('EVENT_NAME', onEventTriggeredCallback);

// and when you done, you can unsubscribe
client.off('EVENT_NAME', onEventTriggeredCallback);

Full events reference can be found here

Teardown and cleanup

When you are done with the panel, you can teardown the client and the panel as follow

// Disconnecting a specific channel id
client.disconnect('YOUR_CHANNEL_ID');

// Tear down of the panel
myPanel.destroy();

// Tear down of the client.
// It will disconnect automatically from all connected channels
client.destroy();

Full reference documentation

Reference documentation can be found here

Supported browser and devices

Chrome / Firefox / Safari / Edge (Desktop)
Safari iOS, Chrome iOS