​

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.

Try it now

There are multiple ways to try out the SDK before you start integrating.

Live apps

  • Go to air.live to see this SDK in action in a production app. You can instantly start an audio chat and invite anyone using a link.

  • Use our Chrome extension as a no-code solution to try out this SDK on your own site.

Code pens

Play with interactive examples in different frameworks in your browser.

Mock app

You can use the mock app below to play with the style and other options. To keep your customization, click Copy As Json and paste the config directly into the Aircore config in your app.

Before starting

Supported browsers and devices

  • Desktop: Chrome, Edge, Firefox, and Safari
  • iOS: Chrome and Safari

Installation

The recommended way of installing is using NPM Package Manager.

  1. 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 async src="https://ga.jspm.io/npm:es-module-shims@1.7.0/dist/es-module-shims.js"></script>
<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 client by passing the publishable key and the current user ID.
const client = createClientWithPublishableKey(
  'INSERT_PUBLISHABLE_KEY_HERE',
  'INSERT_USER_ID_HERE'
);

// Set the 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 client by passing the session authorization token and the current
// user ID.
const client = createClientWithSessionAuthToken(
  'INSERT_SESSION_AUTHORIZATION_TOKEN_HERE',
  'INSERT_USER_ID_HERE'
);

// Set the 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 for the event for tokens that are about to expire.
client.on('sessionAuthTokenNearingExpiry', function () {
  // Call your backend and get a new session authorization token.
  // Once you have the token, update it on the client.
  client.updateAuthToken(newToken);
});

// Then render the panel by passing a selector, the client, and the channel ID
// that you want to connect 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

You configure the panel with two distinct objects:

  • MediaPanelConfiguration includes all audio panel-specific configuration, such as the title, share link, and other text.

  • Theme includes all visual configuration of the panel, such as fonts and colors.

Here is an example of how you can pass these two objects when rendering the panel:

// Render the selector target on the page first.
// Then render the panel by passing a selector, the client, and the channel ID
// that you want to connect to.
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 the panel.
      panelTitle: 'John and Leila call',
    }
  }
);

The chat panel has two distinct states: collapsed and expanded. Here is an example configuration for the panel:

const myPanelConfiguration = {
  panelTitle: 'John and Leila call', // Custom title for your panel.
  panelSubtitle: '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 override the strings displayed.
    // Add other strings that you want to customize.
  },

  collapsedStateOptions: {
    maxAvatars: 5, // Maximum number of avatars to show. The rest are shown as
                   // "+99 others".
    // Add other collapsed state options that you want to customize.
  },

  expandedStateOptions: {
    placement: 'topLeft', // The expanded view is placed relative to the
                          // collapsed view.
    // Add other expanded state options that you want to customize.
  }
};

You can launch the panel in collapsed mode only by disabling the expanded state:

const myPanelConfiguration = {
  expandedStateOptions: null,
  // Add other properties that you want to customize.
};

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

const myPanelConfiguration = {
  collapsedStateOptions: null,
  // Add other properties that you want to customize.
};

User experience

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

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

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.

Enable push-to-talk

With push-to-talk, users publish audio only while pushing a button. To enable this, set pushToTalkMode to true.

On mobile, users tap and hold the microphone button to talk. When they release the button, the stream is muted again.

On desktop, users push and hold the spacebar to talk. To use a different key, update the value of pushToTalkKey.

Theming

The Theme object has a base theme with overriding variables that you can use to customize the look and feel of your panel.

The default base theme is light. You can also choose dark or another base theme:

const myCustomTheme = {
  base: 'dark',
  overrides: {
    // You can override any of the values using your own colors.
    primaryColor: '#228B22', // Your brand color.
    textColor: '#FFFFFF',
    backgroundColor: '#000000',
    borderRadius: '20px',
    font: 'Arial', // Name of your custom font.
    // Add other values that you want to override.
    icons: {
      join: '/assets/join.svg', // Local path to your icon.
      // Add other icons that you want to customize.
    }
  }
};

You can reuse the theme across multiple panels as needed. Just define it somewhere in your app and reuse it every time you render a new panel.

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);

// Unsubscribe from the same event.
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

// Disconnect from a specific channel ID.
client.disconnect('YOUR_CHANNEL_ID');

// Teardown of the panel.
myPanel.destroy();

// Teardown of the client.
// It disconnects automatically from all connected channels.
client.destroy();

Full reference documentation

Reference documentation can be found here