MCPFeedback Android SDKv2.1.0

Prerequisites

• JDK 17 installed and active (java -version reports 17).
• Android Studio Ladybug (2024.2) or newer, with AGP 8.7.3+.
• An Android app module with minSdk ≥ 24.
• An apiKey and siteKey pair from your MCPFeedback dashboard → Sites.
• A terminal with curl and shasum (or equivalent) for checksum verification.

Step-by-step integration

Six steps, roughly ten minutes end-to-end. Every snippet below is copy-pasteable and verified against the v2.1.0 BCV-frozen public API.

# 1. Download the bundle and its checksum sidecar
curl -L -O https://staging.mcpfeedback.com/downloads/mcpfeedback-android-sdk-2.1.0-repo.zip
curl -L -O https://staging.mcpfeedback.com/downloads/mcpfeedback-android-sdk-2.1.0-repo.zip.sha256

# 2. Verify the checksum (expect: "mcpfeedback-android-sdk-2.1.0-repo.zip: OK")
shasum -a 256 -c mcpfeedback-android-sdk-2.1.0-repo.zip.sha256

# 3. Extract into your app module
mkdir -p app/libs-mcpfeedback
unzip -q mcpfeedback-android-sdk-2.1.0-repo.zip -d app/libs-mcpfeedback

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("app/libs-mcpfeedback") }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.mcpfeedback:sdk:2.1.0")
}

<manifest>
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- Optional — only for MediaProjection screen recording (v2.2) -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />

    <application ...>
        <!-- your activities -->
    </application>
</manifest>

import com.mcpfeedback.sdk.MCPFeedback

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        MCPFeedback.initialize(
            apiKey = "YOUR_API_KEY",
            siteKey = "YOUR_SITE_KEY",
            shakeEnabled = true,
            // baseUrl = null  // optional self-hosted override
        )
    }
}

// From an Activity:
helpButton.setOnClickListener {
    MCPFeedback.show(this@MainActivity)
}

// From a Fragment:
MCPFeedback.show(requireActivity())

Invocation methods

v2.1.0 ships two invocation entry points as real public API. Four additional methods appear in the sample app as placeholders marked [coming-soon v2.2] and will ship in the next minor release.

Configuration reference

The v2.1.0 public API exposes four initialization parameters. The extended configuration surface (screenshot detection, floating button, session replay, network logging, privacy tiers) is deferred to v2.2.

Observing upload state

Collect MCPFeedback.observeUpload(uploadId) inside a lifecycle-aware coroutine scope to react to progress, success, or failure.

import com.mcpfeedback.sdk.MCPFeedback
import com.mcpfeedback.sdk.repo.UploadState

lifecycleScope.launch {
    MCPFeedback.observeUpload(uploadId).collect { state ->
        when (state) {
            is UploadState.InProgress -> progress.isVisible = true
            is UploadState.Succeeded  -> toast("Feedback sent")
            is UploadState.Failed     -> toast("Failed: ${state.error.message}")
        }
    }
}

Suspend submission

Submit feedback without presenting the UI — useful for custom bug-report forms or programmatic error reporting. Every thrown error is mapped to a typed FeedbackError before crossing the SDK boundary.

import com.mcpfeedback.sdk.MCPFeedback
import com.mcpfeedback.sdk.repo.FeedbackRequest

lifecycleScope.launch {
    val request = FeedbackRequest(
        message = "Tapping the cart icon in the XL layout dismisses the drawer.",
        metadata = mapOf("screen" to "checkout", "build" to BuildConfig.VERSION_NAME),
        screenshotPngBytes = null,
    )
    MCPFeedback.submitFeedback(request)
        .onSuccess { receipt -> /* receipt.id */ }
        .onFailure { err -> /* err: FeedbackError */ }
}

Theming

The SDK resolves your host theme at invocation time via a three-tier bridge — no configuration needed for the common case:

1. Explicit override — values passed via a future themeColors surface win.
2. Host theme attributes — ?attr/colorPrimary, ?attr/colorSurface, and ?attr/colorOnSurface on the launching Activity (Material 3, Material 2, and AppCompat all supported).
3. Neutral default — sensible hard-coded colors if no host theme is resolvable.

Auto dark mode is wired via Configuration.uiMode. See the sample app's M2 / M3 / AppCompat runtime toggle for a live demonstration.

Error handling

Every public API returns a typed FeedbackError sealed class — your app never catches a raw SDK exception. Each error carries code, message, and suggestedAction.

import com.mcpfeedback.sdk.repo.FeedbackError

when (val err = result.exceptionOrNull() as? FeedbackError) {
    is FeedbackError.NetworkUnavailable   -> showOfflineBanner()
    is FeedbackError.PermissionDenied     -> promptForPermission(err.permission)
    is FeedbackError.InvalidConfiguration -> Log.e("App", err.suggestedAction)
    null                                  -> Unit
    else                                  -> Log.e("App", err.message)
}

Compatibility matrix

Tested in CI on API 30 / 33 / 34 / 35 with R8 enabled. Source: mcpfeedback-android/docs/COMPATIBILITY-MATRIX.md.

Troubleshooting

Sample app

A reference integration exercising the v2.1.0 invocation methods across Compose and XML hosts, with a runtime Material 3 / Material 2 / AppCompat theme toggle. Two product flavors: compose and xml.

Version history

API reference