Android

The Help Lightning Android SDK is a Java/Kotlin SDK that embeds Help Lightning calls in an Android application. This guide documents Android SDK 4.0.1.

Plan the 4.x upgrade as a coordinated migration. Android SDK 4.x uses Zoom for video calls and is not interoperable with Android SDK versions earlier than 4.0.0. An Android participant using a pre-4.0.0 SDK cannot communicate with an Android participant using SDK 4.x.

Before rollout, confirm mutually compatible current releases for every Web, Android, and iOS application that may join the same call. This Android guide does not establish cross-platform compatibility by itself.

Before using the SDK, you need a Help Lightning API key, which requires a Help Lightning site with an Enterprise Tier.

The host application must also use:

• Android 9/API 28 or newer
• Compile SDK 36
• Android Gradle Plugin 8.9.1 or newer

The host application’s target SDK does not need to change solely because the Help Lightning SDK is built with target SDK 36.

Before changing the dependency:

1. Coordinate the migration of every Android application that can participate in the same call. Mixed pre-4.0.0 and 4.x Android clients cannot communicate.
2. Raise minSdk to at least 28 and compileSdk to 36, and use Android Gradle Plugin 8.9.1 or newer.
3. Remove theme customization calls that use these removed constants: HLTheme.IMAGE_CALL_QUALITY_HD, HLTheme.IMAGE_CALL_QUALITY_SD, and HLTheme.IMAGE_CALL_QUALITY_AUDIO_PLUS.
4. Stop setting HLCall.autoEnableAudioPlusMode or calling the corresponding builder method. They are deprecated compatibility no-ops.
5. Return quick-overlay selections through HLClient.selectQuickKnowledgeOverlay(uri).
6. If a custom service overrides InCallService.onCallEnded(...), ensure it calls super.onCallEnded(...).
7. Explicitly opt into embedded chat if the application requires in-call chat. SDK 4.x does not fall back to legacy in-call chat.

The SDK is available from Help Lightning’s Maven repository. Add the repository and dependency to the appropriate Gradle files for your project:

repositories {
    maven { url "https://maven.helplightning.net" }
    google()
    mavenCentral()
}

dependencies {
    implementation 'com.vipaar.lime:hlsdk-light:4.0.1'
}

Normal Gradle/Maven consumers receive the SDK’s transitive dependencies from the published POM. Do not add Zoom or PDF dependencies manually to a standard Android integration.

Initialize the SDK once from Application.onCreate() using the application context.

Java:

public final class SampleApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        HLClient.INSTANCE.init(getApplicationContext());
    }
}

Kotlin:

class SampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        HLClient.init(applicationContext)
    }
}

Applications that need custom callbacks should subclass the abstract InCallService service class. Register the service as the HLClientDelegate, usually from onStartCommand, pass the service class to startCall, and register it in AndroidManifest.xml.

import android.content.Intent;
import android.graphics.Bitmap;
import android.util.Log;

import com.vipaar.lime.hlsdk.client.HLCall;
import com.vipaar.lime.hlsdk.client.HLClient;
import com.vipaar.lime.hlsdk.services.InCallService;

public final class SampleInCallService extends InCallService {
    private static final String TAG = "SampleInCallService";

    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        HLClient.INSTANCE.setHLClientDelegate(this);
        return super.onStartCommand(intent, flags, startId);
    }

    @Override
    public void onCallEnded(HLCall call, String reason) {
        super.onCallEnded(call, reason);
        Log.d(TAG, "Call ended: " + reason);
    }

    @Override
    public void onScreenCaptured(HLCall call, Bitmap image) {
        // Store, share, or upload the captured image.
    }

    @Override
    public void onInviteThirdParticipant() {
        // Open the host application's participant invitation flow.
    }

    @Override
    public boolean isShareKnowledgeEnabled() {
        return false;
    }

    @Override
    public void onShareKnowledge() {
        // Open the host application's knowledge picker.
    }

    @Override
    public boolean isShareQuickKnowledgeEnabled() {
        return false;
    }

    @Override
    public void onSelectKnowledgeQuickOverlay() {
        // Open the host application's image picker.
    }

    @Override
    public boolean isMinimizeCallEnabled() {
        return true;
    }
}

The host application’s responsibilities are:

InCallService.onCallEnded(...) releases call resources and stops the service. A subclass may omit this override. If it does override the method, it must call super.onCallEnded(call, reason).

Applications that do not need custom behavior can call the startCall overload without a custom service class and use the SDK’s default service behavior.

After onShareKnowledge() opens the host picker, return the selected content with its Uri and KnowledgeType:

HLClient.INSTANCE.onKnowledgeSelected(uri, KnowledgeType.IMAGE);

After onSelectKnowledgeQuickOverlay() opens the image picker, use the Maven- and binding-safe static entry point:

HLClient.selectQuickKnowledgeOverlay(uri);

HLClient.selectQuickKnowledgeOverlay(uri)

Do not call onQuickKnowledgeOverlaySelected(Uri) directly.

The Report a Bug action is optional and hidden by default. Override both methods to display it and open the host application’s bug-report UI:

@Override
public boolean isReportBugEnabled() {
    return true;
}

@Override
public void onReportBugSelected() {
    // Open the host application's bug-report UI.
}

Embedded chat is opt-in and hidden by default. Return true from isEmbeddedChatEnabled() and resolve host-owned content, such as a Help Thread Fragment, from requestEmbeddedChatContent(...):

@Override
public boolean isEmbeddedChatEnabled() {
    return true;
}

@Override
public void requestEmbeddedChatContent(
        String callId,
        EmbeddedContentCallback callback) {
    // Resolve host-owned content, then invoke exactly one callback method.
}

Invoke exactly one callback method: onContentReady(descriptor) when content is available or onContentUnavailable() when it is not. The callback may be invoked from any thread; the SDK dispatches its UI work. The EmbeddedContentDescriptor.fragmentClass must identify a Fragment with a public no-argument constructor. Put initialization data in the descriptor’s arguments Bundle.

There is no fallback to legacy in-call chat. If embedded chat is disabled or content is unavailable, the chat UI is not shown.

The host owns unread state and must push every updated count to the SDK. Pass 0 when no unread messages remain:

HLClient.INSTANCE.setEmbeddedChatUnreadCount(unreadCount);

HLClient.setEmbeddedChatUnreadCount(unreadCount)

Opening the embedded sheet temporarily hides the badge but does not mark messages as read. If the host leaves a positive count, the badge reappears when the sheet closes. The SDK resets the count to 0 when the call ends. The host may also call clearEmbeddedChatUnreadCount() explicitly. The badge has no legacy-chat-count fallback.

Implement requestEmbeddedInviteContent(String callId, EmbeddedContentCallback callback) to provide a participant-invite Fragment that the SDK hosts inside the call UI. The descriptor, constructor, Bundle, and callback rules are the same as for embedded chat. If the host reports that content is unavailable, the SDK falls back to onInviteThirdParticipant().

Create an HLCall with the tokens and server URL returned by your integration server. The integration server must also identify whether the session belongs to the US or EU data center. The session tokens, call-service URL, API key, and selected data center must all refer to the same environment.

Select Environment.DataCenter.US for a US session or Environment.DataCenter.EU for an EU session. Do not select a different region or infer one by falling back to the SDK default.

The following excerpt assumes those values have already been obtained:

HLCall call = new HLCall.Builder()
        .sessionId(sessionId)
        .sessionToken(sessionToken)
        .userToken(userToken)
        .gssUrl(url)
        .helplightningAPIKey(apiKey)
        .localUserDisplayName(displayName)
        .autoEnableCamera(autoEnableCamera)
        .autoEnableMicrophone(autoEnableMic)
        .startInMiniView(startInMiniView)
        .build();

Environment.DataCenter dataCenter = sessionUsesEuDataCenter
        ? Environment.DataCenter.EU
        : Environment.DataCenter.US;

HLClient.INSTANCE.startCall(
        call,
        context,
        SampleInCallService.class,
        dataCenter)
        .then(callId -> {
            Log.d(TAG, "Call ID: " + callId);
        }, error -> {
            Log.e(TAG, "Error starting call", error);
        });

The startCall overloads that omit the data center use the US data center by default. Use those overloads only when the session is known to belong to the US data center. For an EU session without a custom service, pass null for the service class and explicitly pass Environment.DataCenter.EU.

Pass a custom InCallService class only when the application needs that custom service.

Register the custom service in AndroidManifest.xml. The mediaProjection foreground service type is required for screen sharing.

<service
    android:name=".SampleInCallService"
    android:exported="false"
    android:foregroundServiceType="camera|microphone|mediaProjection" />

If the application does not use a custom InCallService, it does not need to declare the sample service.

The Android sample contains a complete integration, including its sample integration server. Confirm that the sample branch and SDK dependency match 4.x before using it as release validation.