@benzinga/benzinga-squawk-sdk

Squawk JavaScript SDK

Squawk JavaScript SDK for consumer and broadcaster service

Installation

Using NPM
- Install the library
  - npm i @benzinga/benzinga-squawk-sdk --save

Using in typescript

Import the library

import SquawkSDK from "@benzinga/benzinga-squawk-sdk"

Using from private CDN

Add the script

<script src="/your_cdn/path/to/squawkjs.min.js"> </script>

Using in react native

The SDK also support react native. In order to use the SDK in our react native application we need to

Add react native WebRTC module in our codebase ( The SDK itself is light and depends on the host application to add react native WebRTC SDK )
```
  npm install react-native-webrtc --save
```
Must call registerGlobals, before initialize the SDK, so that WebRTC specific methods are available to global namespaces for the SDK to use
- registerGlobals - API Doc Reference for more details explanation
Make sure you have necessary application permissions provided for WebRTC from both Android and iOS

API

Create a squawk instance of SquawkJS by calling SquawkSDK with TransportConfig and SDKCallback.

Create a Squawk consumer instance

  // if we want to use session based authentication
  new SquawkSDK.Builder(transportConfig: TransportConfig, callback?: SDKCallback)
      .withDebug() // enabling debug will add verbosity in the application. It is suggested not to use debug in production
      .withSession()
      .asListener()
      .build()

  // if we want to use api key based authentication
  new SquawkSDK.Builder(transportConfig: TransportConfig, callback?: SDKCallback)
      .withDebug() // enabling debug will add verbosity in the application. It is suggested not to use debug in production
      .withApiKey()
      .asListener()
      .build()

  // if we want to use JWT based authentication
  new SquawkSDK.Builder(transportConfig: TransportConfig, callback?: SDKCallback)
      .withDebug() // enabling debug will add verbosity in the application. It is suggested not to use debug in production
      .withJWT()
      .asListener()
      .build()

Create a Squawk broadcaster instance

// if we want to use session based authentication
new SquawkSDK.Builder(transportConfig: TransportConfig, callback?: SDKCallback)
    .withDebug() // enabling debug will add verbosity in the application. It is suggested not to use debug in production
    .withSession()
    .asBroadcaster()
    .build()

// if we want to use api key based authentication
new SquawkSDK.Builder(transportConfig: TransportConfig, callback?: SDKCallback)
    .withDebug() // enabling debug will add verbosity in the application. It is suggested not to use debug in production
    .withApiKey()
    .asBroadcaster()
    .build()

// if we want to use JWT based authentication
new SquawkSDK.Builder(transportConfig: TransportConfig, callback?: SDKCallback)
    .withDebug() // enabling debug will add verbosity in the application. It is suggested not to use debug in production
    .withJWT()
    .asBroadcaster()
    .build()

Initialize the transport and establish a connection with API token, and username.
- It is an async function. It will return success or throw exception upon successfully connected, or failed with the Server
```
async initialize(apiKey: string): Promise<any>
```

Subscriber specific API

As a consumer you can use following SDK methods

  - subscribeChannel
  - unsubscribeChannel
  - getTransportState
  - getChannelState
  - getAvailableChannels
  - getExistingPresenters
  - muteChannel
  - unMuteChannel
  - stop

Subscribe to a channel
- It is an async function. Subscribe to a channel with a channel id and audio element. It will return success or throw exception if failed to subscribe the given channel.
```
async subscribeChannel(channelId: number): Promise<void>
```
Unsubscribe from a channel
- It is an async function. Unsubscribe from a channel with a channel id. It will return success or throw exception if failed to un-subscribe from a channel
```
async unsubscribeChannel(channelId: number): Promise<void>
```
Query current SDK transport state
- Calling this function will provide current TransportState of the SDK.
```
getTransportState(): TransportState
```
Get a channel state
- It is an async function. Get a channel state. It will return success with RTCState type or throw exception if failed to fetch channel state
```
async getChannelState(channelId: number): Promise<RTCState>
```
Get a list of available channels
- It is an async function. Get a list of currently available channel. It takes auth key as string and it will return success or throw exception if failed to fetch available channel
```
async getAvailableChannels(key: string): Promise<GetStreamResponse>
```
Get a list of existing presenters
- Get a list of existing presenters. It will return an array of Presenter
```
getExistingPresenters(): Presenter[]
```
Mute channel subscriber
- Mute a subscriber audio. Will throw exception if subscriber with given channel id is not present
```
muteChannel(channelId: number)
```
Unmute channel subscriber. Will throw exception if subscriber with given channel id is not present
- Mute a subscriber audio
```
unMuteChannel(channelId: number)
```
Stop and disconnect client and release resource
- It is an async function. It disconnects transport and client related resource. It will return success or throw exception if failed release transport and client resource
```
async stop(): Promise<any>
```

Broadcaster specific API

As a broadcaster you can use following SDK methods

  - startBroadcasting
  - stopBroadcasting
  - getTransportState
  - getChannelState
  - getAvailableChannels
  - getExistingPresenters
  - muteChannel
  - unMuteChannel
  - stop

Start broadcasting to a channel
- It is an async function. Calling this method will start broadcasting to given channel or if throw error if failed.
```
async startBroadcasting(channelId: number): Promise<void>
```
Stop broadcasting to a channel
- It is an async function. Calling this method will stop broadcasting to the given channel or if throw error if failed.
```
async stopBroadcasting(channelId: number): Promise<void>
```
Query current SDK transport state
- Calling this function will provide current TransportState of the SDK.
```
getTransportState(): TransportState
```
Get a channel state
- It is an async function. Get a channel state. It will return success with RTCState type or throw exception if failed to fetch channel state
```
async getChannelState(channelId: number): Promise<RTCState>
```
Mute channel broadcaster
- Mute a broadcaster audio. Will throw exception if subscriber with given channel id is not present
```
muteChannel(channelId: number)
```
Unmute channel broadcaster. Will throw exception if subscriber with given channel id is not present
- Mute a broadcaster audio
```
unMuteChannel(channelId: number)
```
Get a list of available channel
- It is an async function. Get a list of currently available channel. It takes auth key as string and it will return success or throw exception if failed to fetch available channel
```
async getAvailableChannels(key: string): Promise<GetStreamResponse>
```
Get a list of existing presenters
- Get a list of existing presenters. It will return an array of Presenter
```
getExistingPresenters(): Presenter[]
```
Stop and disconnect client and release resource
- It is an async function. It disconnects transport and client related resource. It will return success or throw exception if failed release transport and client resource
```
async stop(): Promise<any>
```

Example codebase

Please keep request timeout( requestTimeoutInMs ) less than or equal to connection timeout ( connectionTimeoutInMs ) in order to keep the application behaviour consistent

// create a transport config object
const transportConfig = {
  serverAddress: 'wss://squawk-lb.zingbot.bz/ws/v4/squawk',
  connectionTimeoutInMs: 5000 + 10000, // 15 second
  requestTimeoutInMs: 10000, // 10 second
  maxRetry: 5,
} as TransportConfig
 

// Create a listener or broadcaster specific callback
// SDK callback object is used to listen squawk RTC realted service related callback

// Listener callback if you are using listener 
const sdkCallBack = {
    onMediaOverride(channelId: number): void {
      // implementation here
    },
    onPresenterStateChange(presenterState: PresenterState, channelId: number): void {
      // implementation here
    },
    onRTCStateChange(rtcState: RTCState, channelId: number): void {
      // implementation here
    },
    onRemoteStream(e: MediaStream | undefined, channelId: number): void {
      // implementation here
    },
    onTransportStateChange(transportState: TransportState): void {
      // implementation here
    }
} as ListenerCallback

// Broadcaster callback if you are using broadcaster
const sdkCallBack = {
    onBroadcastOverride(): void {
      // implementation here
    },
    onBroadcasterLeft(name: string, streamId: number, userId: string): void {
      // implementation here
    },
    onLocalStream(e: MediaStream | undefined): void {
      // implementation here
    },
    onNewBroadcaster(name: string, streamId: number, userId: string): void {
      // implementation here
    },
    onRTCStateChange(rtcState: RTCState, channelId: number): void {
      // implementation here
    },
    onTransportStateChange(transportState: TransportState): void {
      // implementation here
    }
} as PublisherCallback

// Create a squawkJs instance

// Create a squawkJs listener instance based on session key
const squawkClient = new SquawkSDK.Builder(transportConfig, sdkCallBack).asListener().withSession().build()
// Or create a squawkJs broadcaster instance based on session key
const squawkClient = new SquawkSDK.Builder(transportConfig, sdkCallBack).asBroadcaster().withSession().build()
      
// initialize client
await squawkClient.initialize('your-api.key')

Listener specific examples

// subscribe to channel
await squawkClient.subscribeChannel(1)
// when using in react native
await squawkClient.subscribeChannel(1)

// unsubscribe from channel
await squawkClient.unsubscribeChannel(1)

// get available channel
const availableChannel = await squawkClient.getAvailableChannels("my test auth key")

// get channel status
const channelState = await squawkClient.getChannelState(1)

// stop and release client
await squawkClient.stop()

Publisher specific examples

// broadcast to channel
await squawkClient.startBroadcasting(1)
// when using in react native
await squawkClient.startBroadcasting(1)

// stop broadcasting to a channel
await squawkClient.stopBroadcasting(1)

// get available channel
const availableChannel = await squawkClient.getAvailableChannels("my test auth key")

// get channel status
const channelState = await squawkClient.getChannelState(1)

// stop and release client
await squawkClient.stop()

Squawk SDK Error Code

Squawk SDK throws an error which is an instance of SquawkError when some error occured during async SDK calls. SquawkError has an error message ( msg ), and error coded ( code ) that you can use in your application to write your SDK error handling logic. Scope of error message are quite broad. So, using error code is encouraged for logic handling.

Error code is a type of Squawk `ErrorType` which is an enum of type(s)

INITIALIZING_SDK
- If there is an error happened during initialization
NOT_ALLOWED
- If a listener or broadcasted is not allowed listen or broadcast to a channel
ALREADY_SUBSCRIBED
- If a listener is already subscribed to the given channel
ALREADY_BROADCASTING
- If a broadcaster is already broadcasting to the given channel
SUBSCRIBING_CHANNEL
- If some other generic error occurred while subscribing to the given channel
BROADCASTING_CHANNEL
- If some other generic error occured while broadcasting to the given channel
CHANNEL_NOT_FOUND
- If given channel is not accociated to the listener or publisher
UNSUBSCRIBING_CHANNEL
- If error occurred during unsubscribe to the channel
STOPPING_BROADCAST
- If error occurred while stopping a broadcaster
FETCHING_CHANNELS
- If error occurred while querying available channel list

Useful public interface, type and values

maxRetry in TransportConfig
- Application has a default max and min retry policy. Values greater than 30 and less than 5 will be ignored
onRemoteStream callback from ListenerCallback
- We have to attach the Media stream with an HTML audio element, so that the audio can be played by the browser(s).
  - Note - Some browser(s) can have default audio playout restriction that required a user interaction to play audio.

interface TransportConfig {
  connectionTimeoutInMs: number
  requestTimeoutInMs: number
  maxRetry: number
  serverAddress: string
}

interface ClientCallback {
    onTransportStateChange(transportState: TransportState): void;
    onRTCStateChange(rtcState: RTCState, channelId: number): void;
}

interface ListenerCallback extends ClientCallback {
    onRemoteStream(e: MediaStream | undefined, channelId: number): void;
    onPresenterStateChange(presenterState: PresenterState, channelId: number): void;
    onMediaOverride(channelId: number): void;
}

interface PublisherCallback extends ClientCallback {
    onLocalStream(e: MediaStream | undefined): void;
    onBroadcastOverride(): void;
    onNewBroadcaster(name: string, streamId: number, userId: string): void;
    onBroadcasterLeft(name: string, streamId: number, userId: string): void;
}
  
enum TransportState {
  connected = 'CONNECTED',
  disconnected = 'DISCONNECTED',
  neutral = 'NEUTRAL',
}

enum RTCState {
  connected = 'CONNECTED',
  closed = 'CLOSED',
  failed = 'FAILED',
  neutral = 'NEUTRAL',
}

enum PresenterState {
  streaming = 'STREAMING',
  neutral = 'NEUTRAL',
}

type Stream = {
  id: number
  type: string
  description: string
  allowedBroadcasting: boolean
  allowedListening: boolean
  metadata: string
}

type GetStreamResponse = {
  streams: Stream[]
  id: number
  type: 'getAvailableStreamsResponse'
}