ECV Video Call Android SDK [EN]

ECV Video Call Android SDK

Introduction

Welcome to the ECV Video Call Android SDK! This SDK allows you to easily integrate real-time video call functionality into your Android applications. It handles the complexities of signaling, WebRTC peer connections, media streams, and call state management, letting you focus on your application's user interface and business logic.

This repository contains:

Key Features

Getting Started

Prerequisites

1. Add Required Libraries

Your application needs to include the ECV SDK library and its required dependencies: WebRTC and Autobahn. You will receive these as .aar files.

2. Explore the Demo Application

The included demo application (ecv175_android) provides a practical example of SDK integration.

3. Basic SDK Initialization (Conceptual)

// Somewhere in your Application class or a central management object
import group.ccr.ecv.sdk.ECVSdk
import group.ccr.ecv.sdk.ECVSdkConfiguration

// 1. Define the SDK Configuration (See Configuration.md for details)
val sdkConfig = ECVSdkConfiguration(
    serviceUrl = "YOUR_SERVICE_URL", // Replace with your actual service URL
    // Make sure useQueueSocket matches your backend version (true for 1.75+, false for 1.5)
    useQueueSocket = true // or false
    // Optionally override webrtcUrl, signalingUrl, etc.
)

// 2. Initialize the SDK Instance
// It's recommended to have a single instance managed centrally
val ecvSdk = ECVSdk(instanceName = "MyAppSdkInstance", config = sdkConfig)

// Store this instance for access throughout your app (e.g., in Application class, DI, Singleton)
// Example: MyApp.sdkInstance = ecvSdk

// Somewhere in your Application class or a central management object
import group.ccr.ecv.sdk.ECVSdk;
import group.ccr.ecv.sdk.ECVSdkConfiguration;

// 1. Define the SDK Configuration (See Configuration.md for details)
ECVSdkConfiguration sdkConfig = new ECVSdkConfiguration(
    /* serviceUrl */ "YOUR_SERVICE_URL", // Replace with your actual service URL
    // ... other optional parameters ...
    /* useQueueSocket */ true // or false, Make sure this matches your backend version (true for 1.75+, false for 1.5)
    // ... other optional parameters ...
);

// 2. Initialize the SDK Instance
// It's recommended to have a single instance managed centrally
ECVSdk ecvSdk = new ECVSdk("MyAppSdkInstance", sdkConfig);

// Store this instance for access throughout your app (e.g., in Application class, DI, Singleton)
// Example: MyApp.sdkInstance = ecvSdk;

Core Concepts

Demo Application Flow

The demo app follows this basic flow:

Documentation Structure

Next Steps

Usage Guide

This guide provides detailed information on using the core components of the ECV Android SDK.

1. Initialization (ECVSdk)

The ECVSdk class is the primary entry point for the SDK. You typically create a single instance for your application's lifecycle.

Creating an Instance:

import group.ccr.ecv.sdk.ECVSdk
import group.ccr.ecv.sdk.ECVSdkConfiguration

// Configuration (See Configuration.md for details)
val sdkConfig = ECVSdkConfiguration(
    serviceUrl = "YOUR_SERVICE_URL",
    useQueueSocket = true // Example: Set based on your backend version
    // ... other optional parameters
)

// Create SDK Instance
// Use a descriptive name for logging/debugging purposes
val sdkInstance = ECVSdk(instanceName = "MyAppSdkInstance", config = sdkConfig)

// --- Accessing the SDK Instance ---
// It's crucial to manage this instance appropriately. Common patterns:
// 1. Store in your Application subclass:
// class MyApp : Application() {
//     lateinit var sdkInstance: ECVSdk
//     override fun onCreate() {
//         super.onCreate()
//         sdkInstance = ECVSdk(...)
//     }
// }
// Access via: (applicationContext as MyApp).sdkInstance

// 2. Dependency Injection (Hilt, Koin, etc.): Provide ECVSdk as a singleton.

// 3. Simple Singleton Object (Kotlin):
// object SdkManager {
//     lateinit var instance: ECVSdk
//     fun initialize(config: ECVSdkConfiguration) {
//         instance = ECVSdk("MyAppSdkInstance", config)
//     }
// }
// Access via: SdkManager.instance

import group.ccr.ecv.sdk.ECVSdk;
import group.ccr.ecv.sdk.ECVSdkConfiguration;
import android.app.Application;

// Configuration (See Configuration.md for details)
ECVSdkConfiguration sdkConfig = new ECVSdkConfiguration(
    /* serviceUrl */ "YOUR_SERVICE_URL",
    // ... other parameters like webrtcUrl, signalingUrl ...
    /* useQueueSocket */ true // Example: Set based on your backend version
    // ... other parameters ...
);


// Create SDK Instance
// Use a descriptive name for logging/debugging purposes
ECVSdk sdkInstance = new ECVSdk("MyAppSdkInstance", sdkConfig);

// --- Accessing the SDK Instance ---
// It's crucial to manage this instance appropriately. Common patterns:
// 1. Store in your Application subclass:
// public class MyApp extends Application {
//     private ECVSdk sdkInstance;
//     @Override
//     public void onCreate() {
//         super.onCreate();
//         ECVSdkConfiguration config = new ECVSdkConfiguration(...);
//         sdkInstance = new ECVSdk("MyAppSdkInstance", config);
//     }
//     public ECVSdk getSdkInstance() {
//         return sdkInstance;
//     }
// }
// Access via: ((MyApp) getApplicationContext()).getSdkInstance();

// 2. Dependency Injection (Dagger, Hilt): Provide ECVSdk as a singleton.

// 3. Simple Singleton Class (Java):
// public class SdkManager {
//     private static ECVSdk instance;
//     public static void initialize(ECVSdkConfiguration config) {
//         if (instance == null) {
//             instance = new ECVSdk("MyAppSdkInstance", config);
//         }
//     }
//     public static ECVSdk getInstance() {
//         if (instance == null) {
//             throw new IllegalStateException("SdkManager not initialized");
//         }
//         return instance;
//     }
// }
// Access via: SdkManager.getInstance();

Key Components:

2. Managing Calls (VideoCall)

A VideoCall object represents a single call session from initiation to termination.

Creating a Call:

// Assumes sdkInstance is available
val videoCall: VideoCall = sdkInstance.createCall() // Generates rtcId via API call

// OR for testing/joining with a known rtcId:
// val testVideoCall: VideoCall = sdkInstance.createTestCall() // Doesn't generate rtcId automatically
// testVideoCall.setRtcId("EXISTING_RTC_ID")

// Assumes sdkInstance is available
VideoCall videoCall = sdkInstance.createCall(); // Generates rtcId via API call

// OR for testing/joining with a known rtcId:
// VideoCall testVideoCall = sdkInstance.createTestCall(); // Doesn't generate rtcId automatically
// testVideoCall.setRtcId("EXISTING_RTC_ID");

Call Lifecycle & Key Methods:

Finding an Existing Call:

If you navigate away from the call screen and need to retrieve the VideoCall instance later (e.g., in QueueScreen or CallScreen), use the rtcId:

val rtcId: String = // ... obtain the rtcId for the current call ...
val existingCall = sdkInstance.getVideoCall(rtcId)
if (existingCall != null) {
    // Use the call instance
} else {
    // Call not found, handle appropriately (e.g., navigate back)
}

String rtcId = // ... obtain the rtcId for the current call ...
VideoCall existingCall = sdkInstance.getVideoCall(rtcId);
if (existingCall != null) {
    // Use the call instance
} else {
    // Call not found, handle appropriately (e.g., navigate back)
}

Important: The SDK keeps a reference to VideoCall instances internally using the rtcId. Calling hangup() will eventually lead to the cleanup and potential removal of this reference.

3. WebRTC Connection (WebRtcConnection)

This class manages the low-level WebRTC details, including the PeerConnection, media tracks, and renderers. You obtain it via videoCall.connect().

Key Methods:

Renderer Lifecycle Management (Crucial):

SurfaceViewRenderer requires careful lifecycle management, especially in Jetpack Compose using AndroidView.

Refer to the CallScreen.kt -> VideoRenderer composable in the demo app for a concrete example.

// Simplified Example within an AndroidView block
import androidx.compose.runtime.*
import androidx.compose.ui.viewinterop.AndroidView
import org.webrtc.RendererCommon
import org.webrtc.SurfaceViewRenderer

// Assume webRtcConnection and isLocalView are available in the composable scope
@Composable
fun VideoDisplay(webRtcConnection: WebRtcConnection?, isLocalView: Boolean, modifier: Modifier = Modifier) {
    if (webRtcConnection == null) {
        // Handle case where connection is not ready
        Box(modifier.background(Color.Gray)) { Text("Connecting...") }
        return
    }

    AndroidView(
        modifier = modifier,
        factory = { ctx ->
            SurfaceViewRenderer(ctx).apply {
                init(webRtcConnection.eglBase.eglBaseContext, null)
                setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL)
                // Initial attach often done in update, but could be here if logic is simple
            }
        },
        update = { surfaceViewRenderer ->
            // Logic to decide whether to attach local or remote
            if (isLocalView) {
                webRtcConnection.detachRemoteView(surfaceViewRenderer) // Ensure cleanup
                webRtcConnection.attachLocalView(surfaceViewRenderer)
            } else {
                webRtcConnection.detachLocalView(surfaceViewRenderer) // Ensure cleanup
                webRtcConnection.attachRemoteView(surfaceViewRenderer)
            }
             surfaceViewRenderer.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL) // Re-apply if needed
        },
        onRelease = { surfaceViewRenderer ->
            // DETACH IS ESSENTIAL before release
            webRtcConnection.detachLocalView(surfaceViewRenderer)
            webRtcConnection.detachRemoteView(surfaceViewRenderer)
            surfaceViewRenderer.release() // Release resources
            Log.d("VideoRenderer", "SurfaceViewRenderer released (isLocal: $isLocalView)")
        }
    )
}

// Simplified Example within an Android Fragment or Activity
// Assume webRtcConnection and surfaceViewRenderer are member variables initialized appropriately

// In onCreateView or onViewCreated:
// SurfaceViewRenderer surfaceViewRenderer = binding.surfaceView; // From ViewBinding
// if (webRtcConnection != null) {
//     surfaceViewRenderer.init(webRtcConnection.getEglBase().getEglBaseContext(), null);
//     surfaceViewRenderer.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL);
//     if (isLocalView) { // isLocalView determined by UI logic
//          webRtcConnection.attachLocalView(surfaceViewRenderer);
//     } else {
//          webRtcConnection.attachRemoteView(surfaceViewRenderer);
//     }
// }

// In onDestroyView:
// if (webRtcConnection != null && surfaceViewRenderer != null) {
//     if (isLocalView) {
//          webRtcConnection.detachLocalView(surfaceViewRenderer);
//     } else {
//          webRtcConnection.detachRemoteView(surfaceViewRenderer);
//     }
//     surfaceViewRenderer.release();
// }

4. Handling Events

The SDK communicates state changes and occurrences asynchronously via events.

Subscribing to Events:

Key Event Types (CallEventTypes):

Refer to Events_and_State.md for a more comprehensive list, but some critical ones include:

5. Error Handling

Errors are typically reported via the Error event (CallEventTypes.Error). The VideoCallEvent object will contain:

Always check for Error events and handle them appropriately (e.g., show a message to the user, clean up the call, navigate back).

Configuration Guide

This guide explains the various configuration options available for the ECV SDK and individual calls.

1. SDK Initialization Configuration (ECVSdkConfiguration)

This configuration is provided when you create the main ECVSdk instance and defines the core connection parameters for the SDK to communicate with the backend infrastructure.

Class: group.ccr.ecv.sdk.ECVSdkConfiguration

Parameters:

Example Usage:

import group.ccr.ecv.sdk.ECVSdkConfiguration

// Configuration for ECV v1.75+ backend (using preferred WebSocket)
val configV175 = ECVSdkConfiguration(
    serviceUrl = "https://prod-v175.ecv.example.com",
    useQueueSocket = true // Default, but explicitly shown
)

// Configuration for ECV v1.5 backend (must use HTTP polling)
val configV15 = ECVSdkConfiguration(
    serviceUrl = "https://prod-v15.ecv.example.com",
    useQueueSocket = false // Required for v1.5
    // waitForRoomIntervalDelay and waitForRoomIntervalEndpoint use defaults unless overridden
)

// Configuration with separate WebRTC/Signaling URLs and disabled Queue Socket (e.g., for v1.5)
val configSeparateV15 = ECVSdkConfiguration(
    serviceUrl = "https://api.example.com",
    webrtcUrl = "https://webrtc-v15.example.com", // Separate endpoint for /join
    signalingUrl = "https://websocket-v15.example.com", // Separate WebSocket server (if applicable for v1.5 signaling)
    useQueueSocket = false, // Required for v1.5
    waitForRoomIntervalDelay = 5000, // Poll every 5 seconds
    waitForRoomIntervalEndpoint = "/custom/pollstatus?callid=" // Custom polling endpoint
)

import group.ccr.ecv.sdk.ECVSdkConfiguration;

// Configuration for ECV v1.75+ backend (using preferred WebSocket)
// Assumes constructor takes serviceUrl and other params are defaulted or set later.
ECVSdkConfiguration configV175 = new ECVSdkConfiguration(
    /* serviceUrl */ "https://prod-v175.ecv.example.com"
    // Assuming useQueueSocket defaults to true or can be set if needed via constructor/setter
);

// Configuration for ECV v1.5 backend (must use HTTP polling)
// Assumes a constructor or setters allow setting useQueueSocket.
ECVSdkConfiguration configV15 = new ECVSdkConfiguration(
    /* serviceUrl */ "https://prod-v15.ecv.example.com",
    /* webrtcUrl */ "https://prod-v15.ecv.example.com", // Example: same as serviceUrl
    /* signalingUrl */ "https://prod-v15.ecv.example.com", // Example: same as serviceUrl
    /* useQueueSocket */ false, // Required for v1.5
    /* waitForRoomIntervalDelay */ 3000, // Default
    /* waitForRoomIntervalEndpoint */ "/api/waitforroominterval?rtcId=" // Default
);

2. Call Initiation Parameters (DialCallParameters)

These parameters are provided when you call videoCall.start() to initiate a specific call session.

Class: group.ccr.ecv.sdk.videoCall.api.DialCallParameters

Parameters:

Example Usage:

import group.ccr.ecv.sdk.videoCall.api.DialCallParameters

val params = DialCallParameters(
    callerName = "Jane Doe",
    attributes = mapOf(
        "accountNumber" to "ACC9876",
        "lastInteraction" to "2023-10-26"
    ),
    queue = "SupportQueue",
    additionalHeaders = mapOf("X-Auth-Token" to "user_session_token")
)

// Assuming videoCall is an instance of VideoCall
videoCall.start(params)

import group.ccr.ecv.sdk.videoCall.api.DialCallParameters;
import java.util.HashMap;
import java.util.Map;

Map<String, String> attributes = new HashMap<>();
attributes.put("accountNumber", "ACC9876");
attributes.put("lastInteraction", "2023-10-26");

Map<String, String> headers = new HashMap<>();
headers.put("X-Auth-Token", "user_session_token");

DialCallParameters params = new DialCallParameters(
    /* callerName */ "Jane Doe",
    /* attributes */ attributes,
    /* acdAttributes */ new HashMap<>(), // Empty map
    /* queue */ "SupportQueue",
    /* customPayload */ new HashMap<>(), // Empty map
    /* additionalHeaders */ headers
);

// Assuming videoCall is an instance of VideoCall
videoCall.start(params);

3. WebRTC Connection Parameters (ConnectParameters)

These parameters are optionally provided when you call videoCall.connect() and fine-tune the WebRTC peer connection behavior. Most parameters have sensible defaults.

Class: group.ccr.ecv.sdk.webRtc.ConnectParameters

Key Parameters (Defaults shown):

Example Usage:

import group.ccr.ecv.sdk.webRtc.ConnectParameters
import group.ccr.ecv.sdk.webRtc.CandidateFilteringMode

// Most defaults are usually fine. Only override specific parameters.
val customConnectParams = ConnectParameters(
    videoWidth = 1280,
    videoHeight = 720,
    videoCodec = "H264",
    candidateFilteringMode = CandidateFilteringMode.RELAY, // Example: Only use TURN servers
    additionalHeaders = mapOf("X-WebRTC-Auth" to "webrtc_token")
)

// Get the WebRtcConnection using the custom parameters
val webRtcConnection = videoCall.connect(parameters = customConnectParams)
webRtcConnection.startRoom(context)

import group.ccr.ecv.sdk.webRtc.ConnectParameters;
import group.ccr.ecv.sdk.webRtc.CandidateFilteringMode;
import group.ccr.ecv.sdk.webRtc.DataChannelConfig; // Assuming this exists and is needed
import java.util.HashMap;
import java.util.Map;

// Create ConnectParameters using the constructor (assuming available) or defaults
ConnectParameters customConnectParams = new ConnectParameters(
    /* videoCallEnabled */ true,
    /* disableVideo */ false,
    /* disableAudio */ false,
    /* videoWidth */ 1280, // Custom width
    /* videoHeight

Demo Application Guide

Introduction

This guide walks you through the provided Android Demo Application (ecv175_android). Its primary purpose is to demonstrate how to integrate and utilize the ECV Video Call SDK in a functional, albeit simplified, application.

The demo uses Jetpack Compose for its UI and follows a common navigation pattern. While the UI itself might not be production-ready, the way it interacts with the SDK provides valuable examples. Java code snippets are provided conceptually to illustrate SDK usage, but UI implementation in a traditional Java/XML app will differ significantly.

We will examine the key screens and how they leverage the SDK's capabilities:

Prerequisites

1. Global State Management (AppState.kt)

In a real application, you need a way to manage the initialized ECVSdk instance and potentially the currently active VideoCall instance so they can be accessed from different screens (Activities/Fragments/Composables).

The demo application uses a simple Kotlin object named AppState.

Kotlin Example (AppState.kt concept):

// Simplified concept from AppState.kt
object AppState {
    var sdkInstance: ECVSdk? = null
    // ... other demo-specific state ...

    fun initializeSdk(context: Context, environment: Environment) {
        // ... (logic as shown before) ...
        sdkInstance = ECVSdk(instanceName = "DemoSdk-${environment.name}", config = sdkConfig)
        // ...
    }
}
// Access via: AppState.sdkInstance

Java Conceptual Equivalent (e.g., in Application class or Singleton):

import android.app.Application;
import android.content.Context;
// Import your Environment/Configuration classes if needed for init logic
import group.ccr.ecv.sdk.ECVSdk;
import group.ccr.ecv.sdk.ECVSdkConfiguration;

public class MyApp extends Application {
    private static ECVSdk sdkInstance;

    @Override
    public void onCreate() {
        super.onCreate();
        // Initialize SDK here or on demand
        // initializeSdk(this, /* Pass your configuration source */);
    }

    // Method to initialize SDK (example)
    public static synchronized void initializeSdk(Context context, ECVSdkConfiguration config) {
         if (sdkInstance == null) {
            try {
                sdkInstance = new ECVSdk("MyAppSdkInstance", config);
                Log.i("MyApp", "SDK Initialized");
            } catch (Exception e) {
                 Log.e("MyApp", "SDK Initialization failed", e);
            }
         }
    }

    // Static getter for easy access
    public static ECVSdk getSdkInstance() {
        if (sdkInstance == null) {
            // Optionally initialize here or throw an error
            throw new IllegalStateException("SDK not initialized. Call initializeSdk first.");
        }
        return sdkInstance;
    }
}
// Access via: MyApp.getSdkInstance()

Key Takeaways:

2. Environment Selection (EnvironmentSelectorScreen.kt)

Purpose: Demo-specific screen for testing different backend configurations.

SDK Interaction: Primarily involves selecting a configuration that is then used to initialize the ECVSdk instance (likely via AppState.initializeSdk or equivalent).

Production Relevance: Low. Your app will typically have a fixed or dynamically fetched configuration, not this UI.

(No specific SDK interaction code snippets here that need a direct Java equivalent, as the core logic is config management, not direct SDK calls.)

3. Call Initiation (MainScreen.kt / Equivalent Activity/Fragment)

Purpose: Handles permissions, gathers call data, and initiates the call process.

SDK Interaction & Code Highlights:

4. Waiting Queue (QueueScreen.kt / QueueActivity or QueueFragment)

Purpose: Displays a waiting indicator and handles navigation based on SDK events while in the queue.

SDK Interaction & Code Highlights:

5. Active Call (CallScreen.kt / CallActivity or CallFragment)

Purpose: Main call interface, managing renderers, controls, and call state.

SDK Interaction & Code Highlights:

Conclusion

The demo application provides a practical structure for using the ECV SDK. Key integration points involve:

Refer back to the demo code while reading the other documentation files (SDK_Usage.md, Configuration.md, Events_and_State.md) for a complete understanding. Adapt the concepts shown here to your application's specific architecture (Compose or View-based).

Events and State Management

Introduction

The ECV Android SDK operates asynchronously. It uses an event-driven architecture to communicate status changes, errors, and other important occurrences to your application. Understanding these events is crucial for building a responsive and robust UI.

This guide details the structure of SDK events, lists the key event types, and mentions relevant state properties.

Subscribing to Events

You listen for events on a VideoCall instance. The SDK provides two primary mechanisms:

Refer to the "Handling Events" section in SDK_Usage.md for detailed code examples of both subscription methods.

Event Structure (VideoCallEvent)

All SDK events are delivered as instances of the group.ccr.ecv.sdk.videoCall.events.VideoCallEvent data class.

Key Fields:

Event Type Reference (CallEventTypes)

Here's a breakdown of common event types, grouped by the typical phase of a call:

Phase 1: Initialization & Dialing

Phase 2: Queue & Agent Connection

Phase 3: WebRTC Connection Establishment

These events are typically handled internally by WebRtcConnection but can be observed for debugging or advanced use cases. The key event signaling success is WebRtcConnected.

Phase 4: Active Call & Media

Phase 5: Call Termination

State Properties

While events signal changes, you can also check some current state properties:

It's generally best practice to react to events to update your UI state rather than constantly polling these properties. Use the properties for initial state checks or decisions where needed (e.g., checking agentConnectedState before calling connect()).

Customization Guide

Introduction

The provided Demo Application (ecv175_android) showcases the core functionalities of the ECV SDK. However, your production application will undoubtedly have different UI/UX requirements, configuration methods, and data needs. This guide provides advice on adapting the SDK and demo concepts to your specific application.

1. UI Implementation

The demo uses Jetpack Compose, but the SDK itself is UI-agnostic. You can integrate it into applications built with:

Key Considerations for Your UI:

2. Configuration (ECVSdkConfiguration)

The demo's EnvironmentSelectorScreen is designed for easily testing different backend environments. You will likely not need this screen in your production application.

Production Configuration Strategies:

Important: Ensure the useQueueSocket parameter in your chosen ECVSdkConfiguration matches the capabilities of your target ECV backend (false for v1.5, true recommended for v1.75+).

3. Call Data (DialCallParameters)

The demo uses EnvironmentCallAttribute to dynamically add dropdowns for call data based on the selected environment. This is specific to the demo's multi-environment setup.

In your application, you should populate DialCallParameters with relevant contextual data just before calling videoCall.start().

Example:

// User profile data
val userId = "user123"
val accountType = "Premium"
val intent = "Billing Inquiry"

// Target queue/skill
val targetQueue = "BillingSupport"

// Get SDK instance and create call
val videoCall = sdkInstance.createCall()
// ... wait for GotRtcId ...

// Build parameters with app-specific data
val dialParams = DialCallParameters(
    callerName = "User $userId", // Or actual user name
    attributes = mapOf(
        "userId" to userId,
        "accountType" to accountType,
        "callIntent" to intent
    ),
    acdAttributes = mapOf(
        "skill" to "Billing" // Example ACD attribute
    ),
    queue = targetQueue, // Explicitly set the target queue
    additionalHeaders = mapOf("Authorization" to "Bearer ${getUserAuthToken()}") // Example auth
)

// Start the call
videoCall.start(dialParams)

// Navigate to Queue/Waiting screen

// User profile data
String userId = "user123";
String accountType = "Premium";
String intent = "Billing Inquiry";

// Target queue/skill
String targetQueue = "BillingSupport";

// Get SDK instance and create call
VideoCall videoCall = MyApp.getSdkInstance().createCall();
// ... Handle GotRtcId event using subscribe ...

// Assume GotRtcId event has fired and you are ready to dial:
// Build parameters with app-specific data
Map<String, String> attributes = new HashMap<>();
attributes.put("userId", userId);
attributes.put("accountType", accountType);
attributes.put("callIntent", intent);

Map<String, String> acdAttributes = new HashMap<>();
acdAttributes.put("skill", "Billing");

Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "Bearer " + getUserAuthToken()); // Example auth

DialCallParameters dialParams = new DialCallParameters(
    /* callerName */ "User " + userId, // Or actual user name
    /* attributes */ attributes,
    /* acdAttributes */ acdAttributes,
    /* queue */ targetQueue, // Explicitly set the target queue
    /* customPayload */ new HashMap<>(),
    /* additionalHeaders */ headers
);

// Start the call
videoCall.start(dialParams);

// Navigate to Queue/Waiting screen

4. Event Handling Logic

While the demo shows how to subscribe to events, what you do in response is application-specific. Ensure your implementation correctly handles key events for:

5. Advanced Customization (Optional)

6. Permissions

Always follow Android's best practices for requesting permissions:

7. Additional Modules

7.1 Call Transfer v1.0.18.45+

This module allows an active, ongoing call to be directed to a different agent/queue. The lifecycle of a transferred call is as follows:

• The source call is dialed (call creation).

• The source call waits in the queue.

• The source call is connected.

• The agent initiates the transfer.

• The transfer can be to a queue or directly to a different agent.

• A direct transfer to an agent can be canceled or rejected by the agent.

• A "TransferPending" event is received via videoCall.eventFlow.

  • When this event is received, a message such as "Please wait, your call will be transferred shortly" can be displayed to the user in the interface.

  • At any point after this event, a "TransferCanceled" event may arrive. When the cancel event is received, the displayed warning must be hidden. The call will continue as normal.

• The agent may have placed the call on HOLD before the transfer, so the transfer message must be displayed in front of the HOLD interface.

• When the transfer is complete, a "TransferCompleted" event will be received via eventFlow. The event.detail will contain the new RtcId value assigned to the transferred call.

• The current call view and all associated resources are destroyed.

• The user is sent back to the queue page, this time with the new RtcId.

• The user waits in the queue as if a new call was initiated and is connected via an "AgentConnected" event when an agent is ready.

An implementation example for this scenario is available in the demo application.

Troubleshooting Guide

This guide provides solutions and debugging steps for common issues encountered while integrating or using the ECV Android SDK.

Common Issues & Solutions

Build & Dependency Errors

Runtime Crashes

Media Quality Issues

Specific Feature Issues

General Debugging Steps

Contacting Support

If you continue to face issues after following these steps, please prepare the following information when contacting support: