Intro
Requirements
Quickstart
Further Reading
Build Instructions

Use this README to get started with our Feature Flags (FF) SDK for Android. This guide outlines the basics of getting started with the SDK and provides a full code sample for you to try out.

This sample doesn’t include configuration options, for in depth steps and configuring the SDK, for example, disabling streaming or using our Relay Proxy, see the Android SDK Reference.

For a sample FF Android SDK project, see our test Android Project.

To use this SDK, make sure you've:

• Android Studio or the Android SDK for CLI only
  
• Java 11 or newer
  
• Gradle 8.3 or newer
  
• Android Studio Hedgehog is needed to support Android Gradle Plugin 8.2.x when not building SDK source code from command line
• Projects that consume this library will need Desugaring support enabled to support older phones. Please read https://developer.android.com/studio/write/java8-support#library-desugaring

To follow along with our test code sample, make sure you’ve:

• Created a Feature Flag on the Harness Platform called harnessappdemodarkmode
• Created a server/client SDK key and made a copy of it

You can add the Android SDK to your application by adding the following snippet to root project's build.gradle file:

buildscript {
    repositories {
        mavenCentral()
    }
}

In app module's build.gradle file add dependency for Harness's SDK

implementation 'io.harness:ff-android-client-sdk:2.1.0'

Here is a complete example that will connect to the feature flag service and report the flag value. An event listener is registered to receive flag change events. Any time a flag is toggled from the feature flag service you will receive the updated value.

package io.harness.cfsdk.gettingstarted

import android.os.Bundle
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import android.util.Log
import ch.qos.logback.classic.android.BasicLogcatConfigurator
import io.harness.cfsdk.*
import io.harness.cfsdk.cloud.model.Target
import io.harness.cfsdk.cloud.sse.StatusEvent


class MainActivity : AppCompatActivity() {

    private var flagName: String = BuildConfig.FF_FLAG_NAME.ifEmpty { "harnessappdemodarkmode" }

    // The SDK API Key to use for authentication.  Configure it when installing the app by setting FF_API_KEY
    // e.g. FF_API_KEY='my key' ./gradlew installDebug
    private val apiKey: String = BuildConfig.FF_API_KEY

        val client = CfClient()
        client.use {
            client.initialize(this, apiKey, sdkConfiguration, target)
            client.waitForInitialization()
            Log.i("SDKInit", "Successfully initialized client")

            // Get initial value of flag and display it
            var flagValue: Boolean = client.boolVariation(flagName, false)
            printMessage("$flagName : $flagValue")

            // Setup Listener to handle different events emitted by the SDK
            client.registerEventsListener { event ->
                when (event.eventType) {
                    // Setup Listener to handle flag change events.  This fires when a flag is modified.
                    StatusEvent.EVENT_TYPE.EVALUATION_CHANGE -> {
                        Log.i("SDKEvent", "received ${event.eventType} event for flag")
                        event.extractEvaluationPayload()
                        flagValue = client.boolVariation(flagName, false)
                        printMessage("$flagName : $flagValue")
                    }
                    else -> Log.i("SDKEvent", "Got ${event.eventType.name}")
                }
            }
        }
    }

    // printMessage uses the UI Thread to update the text on the display
    private fun printMessage(msg : String) {
        val tv1: TextView = findViewById(R.id.textView1)
        runOnUiThread { tv1.text = msg }
    }
}

If you want to run the getting started example, then you can open the project in Android Studio. If you would like to build, install and run the app from the CLI then follow these steps to setup the SDK.

N.B this assumes you have set $ANDROID_SDK to the location where the Android SDK has been installed.

$ANDROID_SDK/emulator/emulator @Pixel_4.4_API_32

./gradlew build -xtest

You must provide the FF_API_KEY which will be compiled in. You can also optionally override the flag that will be evaluated by providing FF_FLAG_NAME

FF_FLAG_NAME="harnessappdemodarkmode" FF_API_KEY=<YOUR_API_KEY> ./gradlew :examples:GettingStarted:installDebug

For more information on initialzation options, see Client Initialzation Options

For release builds, Android uses ProGuard to apply optimizations that can affect the behavior of the SDK.

Please add the following rule to your ProGuard configuration to ensure proper functionality when running your Android app from a release build

-keep class io.harness.cfsdk.** { *; }

You will need to install the Android SDK in order to run the emulator, but if you wish to avoid installing Java, Gradle etc you can use a docker image to compile and install the application to a locally running emulator. Follow the steps to setup and run the emulator.

With the emulator running build and install the app

# Build the code
docker run -v $(pwd):/app -v "$HOME/.dockercache/gradle":"/root/.gradle" -w /app mingc/android-build-box ./gradlew build

# Install Debug build to emulator
docker run -v $(pwd):/app -v "$HOME/.dockercache/gradle":"/root/.gradle" -w /app mingc/android-build-box ./gradlew installDebug

Further examples and config options are in the further reading section:

Further Reading
Getting Started Example

Harness is a feature management platform that helps teams to build better software and to test features quicker.