Initialise SDK and Start Recording

Follow the four mini-steps below and you’ll have your first test session on the UXCam Dashboard in minutes.

1 Add the UXCam dependency

Add UXCam’s Maven repo and dependency in your module-level Gradle file.

repositories {
    maven { url 'https://sdk.uxcam.com/android/' }
}

dependencies {
    implementation 'com.uxcam:uxcam:3.+'
}

repositories {
    maven { url 'https://sdk.uxcam.com/android/' }
}

dependencies {
    implementation 'com.uxcam:uxcam:3.+'
}

2 Find & store your UXCAM_KEY safely

2.1 Grab the key in App Settings → App Key on the UXCam Dashboard.

Tip ✏️ Create separate keys for debug and production to keep data clean.

2.2 Add the key to`local.properties` (already in the default `.gitignore`):

# local.properties
UXCAM_KEY=your_app_key

2.3 Expose the key via`BuildConfig` so you never hard-code secrets.

// app/build.gradle.kts
val uxcamKey: String = project.findProperty("UXCAM_KEY") as? String ?: ""

android {
    defaultConfig {
        buildConfigField("String", "UXCAM_KEY", "\"$uxcamKey\"")
    }
}

// app/build.gradle
def uxcamKey = project.findProperty("UXCAM_KEY") ?: ""

android {
    defaultConfig {
        buildConfigField "String", "UXCAM_KEY", "\"${uxcamKey}\""
    }
}

3 Configure and initialise the SDK

3.1 Pick the right spot

Rule of thumb: Start the SDK** once**, at the earliestContext that lives for the whole app.

If you …	Call`UXCam.startWithConfiguration()` in …	Why this spot?
Have (or can add) an `Application`class	`MyApp : Application → onCreate()`	Earliest lifecycle hook → captures the first screen & crashes. (Recommended.)
Don’t have an `Application` class	Launcher`Activity` → onCreate() before `setContentView`	Still early enough for the first screen; zero extra classes.
Use single-Activity / Jetpack Compose	Either of the above or the first `@Composable` rendered	Compose is launched from the activity’s `onCreate()`.
Rely on MultiDex	`Application.onCreate()` after `MultiDex.install(this)`	Ensures secondary DEX files are loaded before UXCam.

❌ Never call it from multiple places—this triggers “SDK already started” warnings and may break uploads.

3.2 Sample Kotlin setup (inside `Application`)

// app/src/main/java/com/example/MyApp.kt
package com.example

import android.app.Application
import com.uxcam.UXCam
import com.uxcam.datamodel.UXConfig

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()

        val config = UXConfig.Builder(BuildConfig.UXCAM_KEY)
            .enableAutomaticScreenNameTagging(true)   // remove if you tag screens manually
            .apply {
                // Verbose integration logs only in debug builds
                if (BuildConfig.DEBUG) enableIntegrationLogging(true)
            }
            .build()

        UXCam.startWithConfiguration(config)
    }
}

Add the class reference to AndroidManifest.xml (skip if already present):

<application
    android:name=".MyApp"
    … >

3.3 Java fallback (launcher `Activity`)

public class MainActivity extends AppCompatActivity {

    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        UXConfig config = new UXConfig.Builder(BuildConfig.UXCAM_KEY).build();

        // Must be *before* setContentView
        UXCam.startWithConfiguration(config);

        setContentView(R.layout.activity_main);
    }
}

4 Verify the integration

4.1 Run the app on a device/emulator, explore it for ~20 s and open Logcat (filter by `UXCam tag`).

You should see:

Session Verification for [your appKey] succeeded
Session and Screen Recording has started

4.2 Background the app (don’t terminate the process).\

You should see upload logs:

Started uploading session file
video.zip upload has succeeded.
data.zip upload has succeeded.
UXCam [version] : session data sent successfully

4.3 Within 1–2 minutes the recording appears on your UXCam Dashboard. 🎉

➡️ Next steps

Great job—your first sessions are flowing!
Now learn how to occlude sensitive data and refine screen names to unlock the full power of UXCam analytics.