Skip to main content

Configure the SDK

Initialize Clerk once at app launch in your Application class before accessing any Clerk features.

Basic configuration

app/src/main/java/com/example/myclerkapp/MyClerkApp.kt
  package com.example.myclerkapp

  import android.app.Application
  import com.clerk.api.Clerk

  class MyClerkApp: Application() {
      override fun onCreate() {
        super.onCreate()
        Clerk.initialize(
            this,
            publishableKey = "YOUR_PUBLISHABLE_KEY"
        )
      }
  }

Register your Application class in AndroidManifest.xml:

<application android:name=".MyClerkApp">
    ...
</application>

Configuration options

Use ClerkConfigurationOptions to customize debug logging, telemetry, proxying, and shared session sync. Pass it to Clerk.initialize():

import com.clerk.api.Clerk
import com.clerk.api.ClerkConfigurationOptions
import com.clerk.api.SharedSessionSyncConfig

Clerk.initialize(
  context = this,
  publishableKey = "YOUR_PUBLISHABLE_KEY",
  options = ClerkConfigurationOptions(
    enableDebugMode = true,
    proxyUrl = "https://proxy.example.com/__clerk",
    telemetryEnabled = true,
    sharedSessionSync = SharedSessionSyncConfig.enabled,
  ),
)
  • Name
    customHeaders
    Type
    Map<String, String>
    Description

    Additional headers to append to outgoing Clerk API requests. Set with withCustomHeaders() rather than the constructor. Defaults to empty.

  • Name
    enableDebugMode
    Type
    Boolean
    Description

    Enables verbose logging for SDK operations and API calls. Defaults to false.

  • Name
    proxyUrl
    Type
    String?
    Description

    Proxy URL for apps behind a reverse proxy, e.g. https://proxy.example.com/__clerk. Defaults to null.

  • Name
    sharedSessionSync
    Type
    SharedSessionSyncConfig?
    Description

    Enables shared session sync between sibling apps that use the same Clerk and are signed with the same certificate. Defaults to null. See Share sessions across apps.

  • Name
    telemetryEnabled
    Type
    Boolean
    Description

    Enables telemetry collection for this SDK instance. Defaults to true.

  • Name
    updateRequiredViewEnabled
    Type
    Boolean
    Description

    Automatically shows an update screen over your app on Android when its versionCode is below the minimum set in the Clerk Dashboard. Users can't dismiss the screen until they update. If your app doesn't include com.clerk:clerk-android-ui, no screen appears. To show your own screen, call withUpdateRequiredViewDisabled() and use Clerk.appVersionSupportStatus. Defaults to true. See Require a minimum app version.

  • Name
    SharedSessionSyncConfig.enabled
    Type
    SharedSessionSyncConfig
    Description

    Turns on shared session sync between sibling apps. See Share sessions across apps.

Wait for initialization

The Clerk SDK initialization is non-blocking. Listen for the SDK to be ready before using Clerk features:

import com.clerk.api.Clerk
import kotlinx.coroutines.flow.first

// Wait for initialization
Clerk.isInitialized.first { it }

// Now safe to use Clerk
val user = Clerk.userFlow.value

Note

When Clerk rejects your app's version at launch because it's older than the minimum app version, Clerk.isInitialized stays false while the version is unsupported, unless the app has saved state from an earlier launch. Check Clerk.appVersionSupportStatus before you wait on initialization.

Clerk

Learn how to access Clerk in your app.

Android Quickstart

Follow the end-to-end setup guide for a Clerk-powered Android app.

Feedback

What did you think of this content?

Last updated on