> For the complete documentation index, see [llms.txt](https://huddle01-2.gitbook.io/huddle01/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://huddle01-2.gitbook.io/huddle01/android-native/untitled.md).

# Client

The documentation for Huddle01 Android SDK to connect your Android App to Huddle01 servers.

## Getting Started

1. **Add Jitpack**

Add Jitpack in the repositories block inside allprojects block in your project-level build.gradle file.

```
allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}
```

   **2. Add Huddle01 Android SDK Dependency**

Add the dependency in your app-level build.gradle file inside the dependency block. Also, replace the version number with the latest one. 

```bash
dependencies {
    ...
    implementation 'com.github.Huddle-01:huddle01-android-sdk:v1.0.1'
}
```

  **3. Initialize HuddleClient**

To initialize the HuddleClient, call the initApp function inside the onCreate of your Application class.

```bash
public class Application extends android.app.Application {
    @Override
    public void onCreate() {
        super.onCreate();
        HuddleClient.initApp(this);
    }
}
```

{% hint style="info" %}
You will need to create your own class extending the Android Application class and make necessary changes in your AndroidManifest.xml file.
{% endhint %}

## Creating and Joining Room

To create a new Room, you will need to create a new object of *HuddleClient* type.

```bash
HuddleClient huddleClient = new HuddleClient.Builder(getApplicationContext(), apiKey)
                .setPeerId(mPeerId)
                .setRoomId(mRoomId)
                .setDisplayName(mDisplayName)
                .setCanConsume(true)
                .setCanProduce(true)
                .setCanUseDataChannel(true)
                .setRoomEventListener(roomEventListener)
                .setMeListener(meListener)
                .setFrontCamEnabledOnInit(true)
                .build();
```

{% hint style="info" %}
Here, some mandatory things to do are are:

* Passing context in Builder()
* Passing an API key inside the Builder()
* Setting event listener of type *RoomEventListener* in setRoomEventListener()
* Setting event listener of type *MeListener* in setMeListener()

The defaults for rest of the fields are:

* peerId - A random string of size 8
* roomId - A random string of size 8
* displayName - A random string of size 6
* canConsume - true
* canProduce - true
* canUseDataChannel - true
* frontCamEnabledOnInit - true (false means that the session will start with a rear camera)

build() function will terminate the object creation process and create a room with the provided parameters.
{% endhint %}

{% hint style="info" %}
You may use this sample API Key: `i4pzqbpxza8vpijQMwZsP1H7nZZEH0TN3vR4NdNS`
{% endhint %}

To join room, once the room is created, call the joinRoom() function. Do check for RECORD\_AUDIO, INTERNET, CAMERA permissions before joining the room.

```bash
if(permissionGranted){
    huddleClient.joinRoom();
}
```

## Event Listeners

When you create a room, you need to supply two Event Listeners: 

* RoomEventListener
* MeListener

#### RoomEventListener

{% tabs %}
{% tab title="onRoomUrlGenerated" %}
**Trigger:** on Room URL generation complete in the SDK.

**Returns:** A string *roomUrl* corresponding to the *roomId*

```bash
public void onRoomUrlGenerated(String roomId, String roomUrl) {
    //set the room URL in your viewmodel/store
}
```

{% endtab %}

{% tab title="onRoomStateChanged" %}
**Trigger:** when Room state changes due to some event in the SDK. 

**Returns:** state of type *ConnectionState.* 

```bash
public void onRoomStateChanged(ConnectionState state) {
    //perform action
}
```

{% hint style="info" %}
ConnectionState can contain 4 possible values:

* **ConnectionState.NEW**: when a new room is created.
* **ConnectionState.CONNECTING:** when a join request is sent to the huddle servers and you're not connected to the room. 
* **ConnectionState.CONNECTED:** when huddle servers grant you the connection to the room. Now, you're inside the room.
* **ConnectionState.CLOSED:** when you terminate the session by calling close() or the maximum number of retries to join the room have been reached.  
  {% endhint %}
  {% endtab %}

{% tab title="onError" %}
**Trigger:** when SDK encounters an error.

**Returns:** an error message in the String format.

```bash
public void onError(String message) {
    //perform action
}
```

{% endtab %}

{% tab title="onPeerChanged" %}
**Trigger:** any change in Peers like new peer joined, peer left, and peer changed display name.

**Returns:** a String named actionType denoting which action has occurred, a String named peerId denoting the peerId on which the action has occurred, a Nullable JSONObject named info, which is NonNull when new peer is added. 

```bash
public void onPeerChanged(String actionType, String peerId, @Nullable JSONObject info, @Nullable String displayName) {
    //ideally switch between actionType and perform actions
}
```

{% hint style="info" %}
There are 3 possible actionTypes:

* **Constants.ACTION\_ADDED**: when a new peer arrives
* **Constants.ACTION\_DISPLAY\_NAME\_CHANGED:** when a peer changes its display name.
* **Constants.ACTION\_REMOVED:** when a peer terminates its session or is removed somehow. 
  {% endhint %}
  {% endtab %}

{% tab title="onProducersChanged" %}
**Trigger:** when a new producer is added, a producer is paused/resumed, or a producer is removed.

**Returns:** a String named actionType denoting the action that has taken place, a producer of type HuddleProducer on which the action has taken place.

```bash
public void onProducersChanged(String actionType, HuddleProducer producer) {
    //ideally switch between actionTypes and perform actions
}
```

{% hint style="info" %}
There are 4 possible actionTypes:

* **Constants.ACTION\_ADDED**: when a new producer is added
* **Constants.ACTION\_PAUSED:** when a producer (mic/camera) pauses its stream.
* **Constants.ACTION\_RESUMED:**  when a producer (mic/camera) pauses its stream.
* **Constants.ACTION\_REMOVED:** when a producer is removed like a camera is disabled or peer leaves the session.
  {% endhint %}
  {% endtab %}

{% tab title="onConsumerAdded" %}
**Trigger:** when a new consumer is added.

**Returns:** String peerId denoting the peerId on which the consumer is added, String consumerType denoting mic/camera type consumers, a consumer of type HuddleConsumer, a boolean remotelyPaused denoting if the consumer is already paused from the peer side when joining. 

```bash
public void onConsumerAdded(String peerId, String consumerType, HuddleConsumer consumer, boolean remotelyPaused) {
    //perform action
}
```

{% endtab %}

{% tab title="onConsumerRemoved" %}
**Trigger:** when a consumer is removed due to some reason.

**Returns:** peerId denoting which peer the consumer is associated with, consumerId denoting the consumer which is removed.

```bash
public void onConsumerRemoved(String peerId, String consumerId) {
    //perform action
}
```

{% endtab %}

{% tab title="onConsumerStateChanged" %}
**Trigger:** when a consumer is paused/resumed.

**Returns:** A string actionType denoting type of action taken place, string consumerId, and string originator ("local"/"remote"). 

```bash
public void onConsumerStateChanged(String actionType, String consumerId, String originator) {
    //ideally switch between actionTypes and perform actions.
}
```

{% hint style="info" %}
There are 2 supported actionTypes:

* **Constants.ACTION\_PAUSED**
* **Constants.ACTION\_RESUMED**
  {% endhint %}
  {% endtab %}

{% tab title="onDataProducerChanged" %}
**Trigger:** when a DataProducer is added/removed.

**Returns:** String actionType denoting type of action, a dataProducer of type HuddleDataProducer.

```bash
public void onDataProducerChanged(String actionType, HuddleDataProducer dataProducer) {
    //do something
}
```

{% hint style="info" %}
There are 2 supported actionTypes:

* **Constants.ACTION\_ADDED**
* **Constants.ACTION\_REMOVED**
  {% endhint %}
  {% endtab %}

{% tab title="onDataConsumerChanged" %}
**Trigger:** when a DataConsumer is added/removed. 

**Returns:** String actionType denoting type of action, string peerId denoting which peer the data consumer is associated with, and a dataConsumer of type HuddleDataConsumer.

```bash
public void onDataConsumerChanged(String actionType, String peerId, HuddleDataConsumer dataConsumer) {
    // do something
}
```

{% hint style="info" %}
There are 2 supported actionTypes:

* **Constants.ACTION\_ADDED**
* **Constants.ACTION\_REMOVED**
  {% endhint %}
  {% endtab %}

{% tab title="onReactionRecieved" %}
**Trigger:** when a reaction arrives from some peer.

**Returns:** a peer of type Peer and a string reaction denoting reaction in the string unicode format.

```bash
public void onReactionReceived(Peer peer, String reaction) {
    //do something
}
```

{% endtab %}

{% tab title="onChatReceived" %}
**Trigger:** when a chat message is recieved from some peer.

**Returns:** a peer of type Peer and a string message denoting the text message.

```bash
public void onChatReceived(Peer peer, String message) {
    //do something
}
```

{% endtab %}

{% tab title="onNotification" %}
**Trigger:** when SDK broadcasts a notification message related to some event.

**Returns:** notification of type Notify.

```
public void onNotification(Notify notify) {
    //do something
}
```

{% endtab %}
{% endtabs %}

#### MeListener

{% tabs %}
{% tab title="onMeReceived" %}
**Trigger**: when SDK registers your information while creating the room. 

**Returns:** String peerId denoting your peerId, string displayName denoting your display name, deviceInfo of type DeviceInfo denoting your device information.

```
public void onMeReceived(String peerId, String displayName, DeviceInfo deviceInfo) {
    //do something
}
```

{% endtab %}

{% tab title="onMediaCapabilitiesReceived" %}
**Triggers:** reports the capabilities of your device, if can send/receive audio and video.

**Returns:** boolean canSendMic denoting audio capability, boolean canSendCam denoting video capability.

```
public void onMediaCapabilitiesReceived(boolean canSendMic, boolean canSendCam) {
    //do something
}
```

{% endtab %}

{% tab title="onNewDisplayName" %}
**Trigger:** when SDK registers a new display name for you.

**Returns:** String displayName denoting changed display name.

```
public void onNewDisplayName(String displayName) {
    //do something
}
```

{% endtab %}
{% endtabs %}

## Available Methods

The following methods solve complex video conferencing tasks in a single line:

| Function                            | Purpose                                                                                                 | Remarks                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **joinRoom()**                      | joins the room when the room is created                                                                 | Use only when permissions are granted and room is created.       |
| **closeRoom()**                     | leaves the room, if there are no remaining participants then disposes the room                          | To be called after the joinRoom() function.                      |
| **sendChatMessage(String message)** | sends chat message to all other peers via data channels                                                 | make sure useDataChannel is set to true while creating the room. |
| **sendReaction(String reaction)**   | sends a reaction via data channels. The reaction should be a unicode of the emoji in the String format. | make sure useDataChannel is set to true while creating the room. |
| **changeCam()**                     | toggles between front and back cameras if available.                                                    | --                                                               |
| **enableCam()**                     | enables camera and related producers.                                                                   | Preferably used when the camera is already disabled.             |
| **disableCam()**                    | disables camera and related producers.                                                                  | Preferably used when the camera is already enabled.              |
| **muteMic()**                       | mutes the audio and pauses the related producers.                                                       | Preferably used when the mic is already unmuted.                 |
| **unmuteMic()**                     | unmutes the audio and resumes the related producers.                                                    | Preferably used when the mic is already muted.                   |
| **changeDisplayName()**             | changes the device's display name.                                                                      | --                                                               |

## Introduced Data Types

The Huddle01 Android SDK offers you flexibility to perform state management according to the design pattern that is being used in your app (MVVM, MVI, etc.). However, we also expose certain data types that may definitely come handy while performing state management as these data types are capable of internal state management. 

### State Data Types

#### Peers

Maintains info related to all the peers.

| Function           | Parameters                                                                 | Return Type |
| ------------------ | -------------------------------------------------------------------------- | ----------- |
| addPeer            | <p></p><ul><li>String peerId</li><li>JSONObject peerInfo</li></ul>         | void        |
| removePeer         | String peerId                                                              | void        |
| setPeerDisplayName | <p></p><ul><li>String peerId</li><li>String displayName</li></ul>          | void        |
| addConsumer        | <p></p><ul><li>String peerId</li><li>HuddleConsumer consumer</li></ul>     | void        |
| removeConsumer     | <p></p><ul><li>String peerId</li><li>String consumerId</li></ul>           | void        |
| addDataConsumer    | <p></p><ul><li>String peerId</li><li>HuddleDataConsumer consumer</li></ul> | void        |
| removeDataConsumer | <p></p><ul><li>String peerId</li><li>String consumerId</li></ul>           | void        |
| getPeer            | String peerId                                                              | Peer        |
| getAllPeers        | --                                                                         | List\<Peer> |
| clear              | --                                                                         | void        |

#### Consumers

Maintains info related to all the consumers in the session.

| Function           | Parameters                                                                                          | Return Type |
| ------------------ | --------------------------------------------------------------------------------------------------- | ----------- |
| addConsumer        | <p></p><ul><li>String type</li><li>HuddleConsumer consumer</li><li>boolean remotelyPaused</li></ul> | void        |
| removeConsumer     | <p></p><ul><li>String consumerId</li></ul>                                                          | void        |
| setConsumerPaused  | <p></p><ul><li>String consumerId</li><li>String originator</li></ul>                                | void        |
| setConsumerResumed | <p></p><ul><li>String consumerId</li><li>String originator</li></ul>                                | void        |
| clear              | --                                                                                                  | void        |

#### Producers

Maintains info related to all the producers in the session.

| Function           | Parameters                   | Return Type      |
| ------------------ | ---------------------------- | ---------------- |
| addProducer        | HuddleProducer producer      | void             |
| removeProducer     | String producerId            | void             |
| setProducerPaused  | String producerId            | void             |
| setProducerResumed | String producerId            | void             |
| filter             | String kind("audio"/"video") | ProducersWrapper |
| clear              | --                           | void             |

#### DataProducers

Maintains info related to all data producers in the session.

| Function           | Parameters                  | Return Type |
| ------------------ | --------------------------- | ----------- |
| addDataProducer    | HuddleDataProducer producer | void        |
| removeDataProducer | String producerId           | void        |
| clear              | --                          | void        |

#### DataConsumers

Maintains info related to all data consumers in the session.

| Function           | Parameters                  | Return Type |
| ------------------ | --------------------------- | ----------- |
| addDataConsumer    | HuddleDataConsumer consumer | void        |
| removeDataConsumer | String consumerId           | void        |
| clear              | --                          | void        |

### Other Data Types

Huddle01 Android SDK also exposes some other data types which are used internally as well as exposed to the app.&#x20;

#### Peer

| Field         | Getter               | Setter                     | DataType     |
| ------------- | -------------------- | -------------------------- | ------------ |
| id            | :heavy\_check\_mark: | :heavy\_multiplication\_x: | String       |
| displayName   | :heavy\_check\_mark: | :heavy\_check\_mark:       | String       |
| deviceInfo    | :heavy\_check\_mark: | :heavy\_check\_mark:       | DeviceInfo   |
| consumers     | :heavy\_check\_mark: | :heavy\_multiplication\_x: | Set\<String> |
| dataConsumers | :heavy\_check\_mark: | :heavy\_multiplication\_x: | Set\<String> |

#### DeviceInfo

| Field   | Getter               | Setter               | DataType |
| ------- | -------------------- | -------------------- | -------- |
| flag    | :heavy\_check\_mark: | :heavy\_check\_mark: | String   |
| name    | :heavy\_check\_mark: | :heavy\_check\_mark: | String   |
| version | :heavy\_check\_mark: | :heavy\_check\_mark: | String   |

#### HuddleConsumer

| Function           | Return Type                 |
| ------------------ | --------------------------- |
| getId()            | String                      |
| getRtpParameters() | String                      |
| getKind()          | String                      |
| resume()           | void                        |
| close()            | void                        |
| dispose()          | void                        |
| pause()            | void                        |
| getTrack()         | org.webrtc.MediaStreamTrack |
| getPaused()        | boolean                     |
| getClosed()        | boolean                     |

#### HuddleProducer

| Function         | Return Type                 |
| ---------------- | --------------------------- |
| getId()          | String                      |
| getRtpParameters | String                      |
| getKind()        | String                      |
| resume()         | void                        |
| close()          | void                        |
| dispose()        | void                        |
| pause()          | void                        |
| getTrack()       | org.webrtc.MediaStreamTrack |
| getPaused()      | boolean                     |
| getClosed()      | boolean                     |

#### HuddleDataConsumer

| Function                  | Return Type |
| ------------------------- | ----------- |
| getId()                   | String      |
| getLabel()                | String      |
| getSctpStreamParameters() | String      |
| getProtocol()             | String      |
| getDataProducerId()       | String      |
| getClosed()               | boolean     |
| close()                   | void        |
| dispose()                 | void        |

#### HuddleDataProducer

| Function                  | Return Type |
| ------------------------- | ----------- |
| getId()                   | String      |
| getLabel()                | String      |
| getSctpStreamParameters() | String      |
| getProtocol()             | String      |
| getClosed()               | boolean     |

#### Notify

| Function   | Return Type |
| ---------- | ----------- |
| getId()    | String      |
| getType()  | String      |
| getText()  | String      |
| getTimeout | int         |

For any help, reach out to us on Slack. We are available 24\*7 at: [Huddle01 Community](https://bit.ly/3AsIsT7).