BandwidthSession & BandwidthUA Integration

This guide will assist developers in integrating the BandwidthSession and BandwidthUA from Bandwidth services into Android applications.

Table of Contents

• Prerequisites
• Configuration
• Getting Started
  • Dependencies
  • Initialization
• Usage
  • Making a Call
  • Terminating a Call
• Listeners and Implementation
• Configuring the User Agent
• Error Handling

Prerequisites

• Experience with Kotlin and Android development.
• Android Studio with the latest SDK & NDK.
• The Bandwidth SDK integrated into your project.
• Apache Maven to generate the pom file, if you don't have installed Maven in your system then download and install before generating the pom file

Configuration

The primary source for configurations in the Bandwidth integration is the assets > config.properties file. Ensure this file is populated with the necessary values before integrating.

Following this template:

account.username=...
account.display-name=...
account.password=...
connection.domain=...
connection.port=...
connection.token=...
connection.header.user=...
connection.header.pass=...

Getting Started

Dependencies

Ensure that the Bandwidth libraries are part of your project's build.gradle file.

Generate a POM file for webrtc-legacy as dependency like following:

mvn install:install-file \
-Dfile="./webrtc-legacy/webrtcsdk-release.aar" \
-DgroupId="webrtc" \
-DartifactId="webrtc-legacy" \
-Dversion="unspecified" \
-Dpackaging="aar" \
-DgeneratePom="true"

This will allow us to use dependency from mavenlocal.

Initialization

Main components:

• BandwidthSession: Using lateinit ensures the variable is initialized before use.
• BandwidthUA: The instance is available from the outset.

Usage

Making a Call

Making a call using the Bandwidth services involves a series of steps to ensure the call's proper initiation and management.

1. Configuration: Before making the call, extract and apply the necessary configurations from config.properties. This ensures that the application interacts correctly with the Bandwidth servers.

2. Authentication: Authenticate your application with the Bandwidth service. This is achieved by logging in using the bandwidthUA instance:

   bandwidthUA.login(this)

3. Setting the Remote Contact: Define the remote contact you intend to call. For this, use the RemoteContact class, and assign the desired number:

   val remoteContact = RemoteContact()

4. Call Initiation: Start the call by invoking the call method on the bandwidthUA instance:

   bandwidthSession = bandwidthUA.call(remoteContact)

5. Error Handling: Implementing try-catch blocks is essential to capture and handle any exceptions that might arise during the call initiation process, providing feedback to the user as necessary.

Terminating a Call

To end an active call, you need to invoke the terminate() method on the BandwidthSession instance:

bandwidthSession.terminate()

This method is responsible for correctly signaling the termination of the call session. After invoking this method, it's a good practice to handle UI transitions and take any other post-call actions that may be necessary in your application's context.

Listeners and Implementation

Listeners are pivotal in monitoring and responding to real-time events during the call.

In the provided code, the BandwidthSessionEventListener is used. This listener has multiple callback methods:

• callTerminated: Invoked when a call is terminated.
• callProgress: Triggered when there's a progress update in the call.

Implementation:

To use the listener, you implement it as an anonymous class and provide logic inside each method:

bandwidthSession.addSessionEventListener(object : BandwidthSessionEventListener {
    override fun callTerminated(session: BandwidthSession?, info: TerminationInfo?) {
        // Handle call termination
    }

    override fun callProgress(session: BandwidthSession?) {
        // Handle call progress
    }

    override fun incomingNotify(event: NotifyEvent?, dtmfValue: String?) {
        // Handle other events
    }
})

Sample configuration

connection.header.pass                # Password for fetching token
connection.header.user                # Username for fetching token
connection.token                      # URL of customer webserver to fetch token
connection.port                       # 5061
connection.domain                     # sbc.webrtc-app.bandwidth.com (for Global) or gw.webrtc-app.bandwidth.com (for US portal)
account.password                      # use some password or leave it empty
account.display-name                  # Put from number/display name here
account.username                      # put from number here

Configuring the User Agent

setUserAgentConfig is a critical method that establishes the settings for the user agent, ensuring correct communication with Bandwidth services.

The method requires:

• Server Configurations:

  • proxyAddress: The address of the proxy.
  • port: The port number.
  • domain: The domain name.
  • transport: Type of transport (e.g., Transport.TLS).
  • oAuthTokenUrl: URL for token authentication.
  • authHeaderUser: User header for authentication.
  • authHeaderPassword: Password header for authentication.

• Account Details:

  • username: Account's username.
  • displayName: Display name associated with the account.
  • password: Account's password.

These values should be fetched from the config.properties file, ensuring sensitive information isn't hard-coded.

Error Handling

Errors, especially in networked operations, are inevitable. Ensure you catch, manage, and inform users about these, fostering a seamless experience.