Android SDK

The Encatch Android SDK lets you collect in-app feedback and surveys in native Android apps. Display forms as a modal WebView overlay or inline in your layout, identify users, track screens and events, and submit responses to the Encatch backend.

Overview

• Package: com.encatch:android (Maven Central)
• Version: 0.1.0
• Platforms: Android (minSdk 24+)
• Repository: github.com/get-encatch/encatch-android

Installation

// build.gradle.kts
dependencies {
    implementation("com.encatch:android:0.1.0")
}

// build.gradle
dependencies {
    implementation 'com.encatch:android:0.1.0'
}

The com.encatch:android artifact pulls in com.encatch:core (the platform-agnostic business logic — networking, storage, session management) automatically and adds the classic-Views UI: the modal form overlay and the WebView bridge wiring.

Quick Start

1. Initialization

import android.app.Application
import com.encatch.android.EncatchFormHost

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        EncatchFormHost.install(this)
    }
}

import androidx.lifecycle.lifecycleScope
import com.encatch.core.Encatch
import kotlinx.coroutines.launch

lifecycleScope.launch {
    Encatch.init("your-api-key")
}

import com.encatch.core.Encatch
import com.encatch.core.EncatchConfig
import com.encatch.core.Theme

lifecycleScope.launch {
    Encatch.init(
        "your-api-key",
        EncatchConfig(
            theme = Theme.SYSTEM,
            debugMode = true,
            isFullScreen = false,
            apiBaseUrl = "https://api.encatch.com",
            appVersion = "1.2.3",
            onBeforeShowForm = { payload ->
                // Return false to prevent the form from showing
                true
            },
        ),
    )
}

2. Identify users

Identify the current user. The userName is required (can be a username, email, or unique identifier). Traits and options are optional.

lifecycleScope.launch {
    Encatch.identifyUser("user@example.com")
}

import com.encatch.core.UserTraits
import kotlinx.serialization.json.JsonPrimitive

lifecycleScope.launch {
    Encatch.identifyUser(
        "user@example.com",
        traits = UserTraits(
            set = mapOf(
                "name" to JsonPrimitive("Alice"),
                "plan" to JsonPrimitive("team"),
            ),
        ),
    )
}

import com.encatch.core.UserTraits
import kotlinx.serialization.json.JsonPrimitive

lifecycleScope.launch {
    Encatch.identifyUser(
        "user@example.com",
        traits = UserTraits(
            set = mapOf(
                "name" to JsonPrimitive("Alice"),
                "plan" to JsonPrimitive("team"),
            ),
            setOnce = mapOf(
                "firstSeen" to JsonPrimitive("2026-08-05T12:00:00Z"),
            ),
            increment = mapOf("loginCount" to 1.0),
            decrement = mapOf("credits" to 5.0),
            unset = listOf("trialEndDate"),
        ),
    )
}

import com.encatch.core.IdentifyOptions
import com.encatch.core.SecureOptions

lifecycleScope.launch {
    Encatch.identifyUser(
        "user@example.com",
        options = IdentifyOptions(
            secure = SecureOptions(
                signature = "your-hmac-signature",
                generatedDateTimeInUtc = "1741867200000", // ms since epoch (2025-03-13T12:00:00Z)
            ),
        ),
    )
}

3. Show a form manually

Show a specific form by slug or ID.

import com.encatch.core.ResetMode
import com.encatch.core.ShowFormOptions

lifecycleScope.launch {
    Encatch.showForm("feedback-form")
    Encatch.showForm("feedback-form", ShowFormOptions(
        reset = ResetMode.ALWAYS,
    ))
}

import com.encatch.core.ContextValue

lifecycleScope.launch {
    Encatch.showForm("feedback-form", ShowFormOptions(
        reset = ResetMode.ALWAYS,
        context = mapOf(
            "plan" to ContextValue.StringValue("team"),
            "feature" to ContextValue.StringValue("checkout"),
            "seats" to ContextValue.NumberValue(12.0),
            "trial" to ContextValue.BooleanValue(false),
            "signedUpAt" to ContextValue.DateValue(System.currentTimeMillis()),
        ),
    ))
}

Other actions

Inline Forms

Inline forms are a way to show Encatch in-app feedback without a modal — the survey renders directly in your layout instead of as a full-screen overlay.

Build Your Own Form UX & UI

If your feedback flow uses a fixed, predictable question set — the same fields and workflow every time — you can build the form with your own Android views or composables and submit responses through the SDK. That keeps typography, spacing, colors, and interaction patterns aligned with the rest of your app, so the survey feels like a native screen rather than an embedded web page.

The flow has three parts: intercept the form, render your own UI, then submit through the SDK.

1. Intercept the form. Set onBeforeShowForm in EncatchConfig and return false to suppress the SDK's WebView. The payload carries everything you need to render natively — payload.formConfig.feedbackConfigurationId (required for submission) and payload.formConfig.questionnaireFields (the question definitions):

import com.encatch.core.ShowFormResponse

var pendingNativeForm: ShowFormResponse? = null

lifecycleScope.launch {
    Encatch.init(
        "your-api-key",
        EncatchConfig(
            onBeforeShowForm = { payload ->
                pendingNativeForm = payload.formConfig
                // Hand off to your own UI (e.g. post to a StateFlow your screen observes)
                false // Suppress the SDK's WebView form
            },
        ),
    )
}

2. Emit lifecycle events (optional). The WebView normally reports lifecycle events; with a native UI you emit them yourself so dashboards and Encatch.on listeners stay accurate:

import com.encatch.core.EventPayload
import com.encatch.core.EventType

val configId = formConfig.feedbackConfigurationId
Encatch.emitEvent(EventType.FORM_SHOW, EventPayload(formId = configId, timestamp = 0))
// ... later, as the user interacts:
Encatch.emitEvent(EventType.FORM_STARTED, EventPayload(formId = configId, timestamp = 0))

(emitEvent stamps the current timestamp for you.)

3. Build and submit the response. Collect answers from your UI as NativeFormResponse entries (questionId, question type wire value, and the value), then convert them with buildSubmitRequest and send with Encatch.submitForm:

import com.encatch.core.BuildSubmitRequestOptions
import com.encatch.core.NativeFormResponse
import com.encatch.core.buildSubmitRequest

lifecycleScope.launch {
    val responses = listOf(
        NativeFormResponse("q1", "rating", 5),
        NativeFormResponse("q2", "short_answer", "Great product!"),
        NativeFormResponse("q3", "multiple_choice_multiple", listOf("option-a", "option-b")),
        NativeFormResponse("q4", "yes_no", true),
    )

    val request = buildSubmitRequest(
        BuildSubmitRequestOptions(
            formConfigurationId = formConfig.feedbackConfigurationId,
            completionTimeInSeconds = 42,
        ),
        responses,
    )
    Encatch.submitForm(request)

    Encatch.emitEvent(
        EventType.FORM_COMPLETE,
        EventPayload(formId = formConfig.feedbackConfigurationId, timestamp = 0),
    )
}

buildSubmitRequest maps every supported question type (rating, NPS, CSAT, opinion scale, text types, choice types, ranking, yes/no, consent, date, matrix types, and structured types like signature, file upload, phone number, address, video/audio, scheduler, QnA with AI, and UPI payments) to the wire format the backend expects. Numeric scale values are rounded to integers; unknown types fall back to short_answer for forward-compatibility.

Support

• Maven Central: com.encatch:android
• Issues: github.com/get-encatch/encatch-android/issues