Skip to main content

API Reference

Complete API reference for the Toggly Android SDK.

Toggly​

The main singleton entry point for the SDK.

Properties​

object Toggly {
    val shared: TogglyClient         // The shared client instance
    val isConfigured: Boolean        // Whether configure() has been called
}

Methods​

configure​

Configure the SDK with settings and storage.

fun configure(
    config: TogglyConfig,
    storage: TogglyStorage
)

Parameters:

  • config - Configuration options
  • storage - Storage implementation for persistence

Example:

Toggly.configure(
    config = TogglyConfig(appKey = "your-app-key"),
    storage = SharedPreferencesStorage(context)
)

TogglyClient​

The main client interface for feature flag operations.

Properties​

interface TogglyClient {
    val isInitialized: Boolean       // Whether init() has completed
    val identity: String?            // Current user identity
    val events: Flow<TogglyEvent>    // Event stream
    val allFlagsFlow: Flow<Map<String, Boolean>>  // All flags as Flow
}

Methods​

init​

Initialize the client and fetch feature flags.

suspend fun init(): InitResult

Returns: InitResult with status and flag count

Example:

lifecycleScope.launch {
    val result = Toggly.shared.init()
    Log.d("Toggly", "Initialized with ${result.flagCount} flags")
}

isFeatureOn​

Check if a feature flag is enabled.

suspend fun isFeatureOn(featureKey: String): Boolean

Parameters:

  • featureKey - The feature flag key

Returns: true if enabled, false otherwise

Example:

if (Toggly.shared.isFeatureOn("new-dashboard")) {
    showNewDashboard()
}

isFeatureOff​

Check if a feature flag is disabled.

suspend fun isFeatureOff(featureKey: String): Boolean

Parameters:

  • featureKey - The feature flag key

Returns: true if disabled, false otherwise

featureFlagFlow​

Get a Flow that emits when a feature flag changes.

fun featureFlagFlow(featureKey: String): Flow<Boolean>

Parameters:

  • featureKey - The feature flag key

Returns: Flow emitting the current and future values

Example:

viewModelScope.launch {
    Toggly.shared.featureFlagFlow("my-feature").collect { isEnabled ->
        _uiState.update { it.copy(featureEnabled = isEnabled) }
    }
}

evaluateFeatureGate​

Evaluate multiple features as a gate.

suspend fun evaluateFeatureGate(
    featureKeys: List<String>,
    requirement: FeatureRequirement = FeatureRequirement.ALL
): Boolean

Parameters:

  • featureKeys - List of feature keys to evaluate
  • requirement - ALL or ANY

Returns: true if gate passes

Example:

val hasAccess = Toggly.shared.evaluateFeatureGate(
    featureKeys = listOf("premium", "beta"),
    requirement = FeatureRequirement.ALL
)

setIdentity​

Set the current user identity.

suspend fun setIdentity(identity: String?)
suspend fun setIdentity(identity: String?, properties: Map<String, String>?)

Parameters:

  • identity - User identifier or null to clear
  • properties - Optional user properties for targeting

Example:

Toggly.shared.setIdentity("user-123", mapOf("plan" to "premium"))

refresh​

Refresh feature flags from the server.

suspend fun refresh(): RefreshResult

Returns: RefreshResult with status and updated flags

getDebugInfo​

Get debug information about the SDK state.

fun getDebugInfo(): DebugInfo

Returns: DebugInfo with current state

setOverride​

Set a local override for a feature flag.

fun setOverride(featureKey: String, value: Boolean)

removeOverride​

Remove a local override.

fun removeOverride(featureKey: String)

clearOverrides​

Clear all local overrides.

fun clearOverrides()

close​

Release SDK resources.

fun close()

TogglyConfig​

Configuration options for the SDK.

data class TogglyConfig(
    val appKey: String? = null,
    val environment: String = "Production",
    val baseUri: String = "https://definitions.toggly.io",
    val identity: String? = null,
    val featureDefaults: Map<String, Boolean> = emptyMap(),
    val showFeatureDuringEvaluation: Boolean = false,
    val refreshInterval: Long = 180_000L,
    val useSignedDefinitions: Boolean = false,
    val verifySignatures: Boolean = false,
    val maxSignatureAgeSeconds: Long? = null,
    val connectTimeout: Long = 10_000L,
    val requestTimeout: Long = 30_000L,
    val storage: TogglyStorage? = null,
    val enableLiveUpdates: Boolean = true
)

See Signed definitions for useSignedDefinitions, verifySignatures, JWKS, and cold-start behavior.

TogglyStorage​

Interface for storage implementations.

interface TogglyStorage {
    suspend fun get(key: String): String?
    suspend fun set(key: String, value: String)
    suspend fun delete(key: String)
    suspend fun clear()
}

Built-in Implementations​

ClassModuleDescription
MemoryStoragecoreIn-memory, no persistence
SharedPreferencesStoragecoreSharedPreferences-based
RoomStoragetoggly-roomRoom database
DataStoreStoragetoggly-datastoreAndroidX DataStore

Compose Module​

rememberFeatureFlag​

Composable function to observe a feature flag.

@Composable
fun rememberFeatureFlag(
    featureKey: String,
    default: Boolean = false
): State<Boolean>

Example:

@Composable
fun MyScreen() {
    val isEnabled by rememberFeatureFlag("new-feature")
    if (isEnabled) {
        NewFeature()
    }
}

Feature​

Composable for conditional rendering. Set negate = true to render when the feature is off.

@Composable
fun Feature(
    featureKey: String,
    negate: Boolean = false,
    loading: @Composable (() -> Unit)? = null,
    content: @Composable () -> Unit
)

Example:

Feature("beta-feature") {
    BetaContent()
}
Feature("beta-feature", negate = true) {
    StableContent()
}

FeatureGate​

Composable for multi-feature gates.

@Composable
fun FeatureGate(
    featureKeys: List<String>,
    requirement: FeatureRequirement = FeatureRequirement.ALL,
    negate: Boolean = false,
    content: @Composable () -> Unit
)
FeatureGate(
    featureKeys = listOf("admin-access", "premium-tier"),
    requirement = FeatureRequirement.ALL
) {
    AdminPanel()
}
FeatureGate(
    featureKeys = listOf("admin-access", "premium-tier"),
    requirement = FeatureRequirement.ALL,
    negate = true
) {
    UpgradePrompt()
}

LocalTogglyClient​

CompositionLocal for accessing the client.

val LocalTogglyClient = staticCompositionLocalOf<TogglyClient?> { null }

Views Module​

View Extensions​

bindToFeatureFlag​

Bind view visibility to a feature flag.

fun View.bindToFeatureFlag(
    featureKey: String,
    lifecycleOwner: LifecycleOwner,
    visibilityWhenEnabled: Int = View.VISIBLE,
    visibilityWhenDisabled: Int = View.GONE
)

toggleViews​

Toggle between two views based on a feature flag.

fun toggleViews(
    featureKey: String,
    lifecycleOwner: LifecycleOwner,
    enabledView: View,
    disabledView: View
)

FeatureFlagViewModel​

ViewModel for feature flag observation.

class FeatureFlagViewModel : ViewModel() {
    fun featureFlagLiveData(featureKey: String): LiveData<Boolean>
    fun featureGateLiveData(
        featureKeys: List<String>,
        requirement: FeatureRequirement = FeatureRequirement.ALL
    ): LiveData<Boolean>
}

Events​

TogglyEvent​

Sealed class for SDK events.

sealed class TogglyEvent {
    data class Initialized(val flagCount: Int) : TogglyEvent()
    data class Refreshed(val flagCount: Int) : TogglyEvent()
    data class Error(val error: Throwable) : TogglyEvent()
    data class FeatureChanged(
        val featureKey: String,
        val oldValue: Boolean,
        val newValue: Boolean
    ) : TogglyEvent()
    data class IdentityChanged(val identity: String?) : TogglyEvent()
    data class NetworkStatusChanged(val isConnected: Boolean) : TogglyEvent()
}

Enums​

FeatureRequirement​

enum class FeatureRequirement {
    ALL,  // All features must be enabled
    ANY   // At least one feature must be enabled
}

Data Classes​

InitResult​

data class InitResult(
    val status: InitStatus,
    val flagCount: Int,
    val error: Throwable? = null
)

enum class InitStatus {
    SUCCESS,
    CACHED,
    ERROR
}

RefreshResult​

data class RefreshResult(
    val status: RefreshStatus,
    val flagCount: Int,
    val changedFlags: List<String>,
    val error: Throwable? = null
)

enum class RefreshStatus {
    SUCCESS,
    NO_CHANGES,
    ERROR
}

DebugInfo​

data class DebugInfo(
    val appKey: String,
    val environment: String,
    val identity: String?,
    val isInitialized: Boolean,
    val featureFlagCount: Int,
    val lastRefreshTime: Long?,
    val lastError: String?,
    val isUsingCachedData: Boolean
)

Exceptions​

TogglyException​

Base exception class.

open class TogglyException(
    message: String,
    cause: Throwable? = null
) : Exception(message, cause)

TogglyNetworkException​

Network-related errors.

class TogglyNetworkException(
    message: String,
    val statusCode: Int? = null,
    cause: Throwable? = null
) : TogglyException(message, cause)

TogglyConfigException​

Configuration errors.

class TogglyConfigException(
    message: String
) : TogglyException(message)