https://github.com/harness/ff-android-client-sdk
Android SDK to integrate with Harness Feature Flag service
https://github.com/harness/ff-android-client-sdk
Last synced: 8 months ago
JSON representation
Android SDK to integrate with Harness Feature Flag service
- Host: GitHub
- URL: https://github.com/harness/ff-android-client-sdk
- Owner: harness
- License: apache-2.0
- Created: 2021-03-01T17:24:06.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-16T12:39:46.000Z (about 1 year ago)
- Last Synced: 2025-05-07T04:44:47.439Z (8 months ago)
- Language: Java
- Size: 6.09 MB
- Stars: 3
- Watchers: 5
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Android SDK for Harness Feature Flags
========================
## Table of Contents
**[Intro](#Intro)**
**[Requirements](#Requirements)**
**[Quickstart](#Quickstart)**
**[Further Reading](docs/further_reading.md)**
**[Build Instructions](docs/build.md)**
## Intro
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](https://ngdocs.harness.io/article/74t18egxbi-android-sdk-reference).
For a sample FF Android SDK project, see [our test Android Project](https://github.com/harness/ff-android-client-sdk/tree/main/examples/GettingStarted).
## Requirements
To use this SDK, make sure you've:
- [Android Studio](https://developer.android.com/studio?gclid=CjwKCAjwp7eUBhBeEiwAZbHwkRqdhQkk6wroJeWGu0uGWjW9Ue3hFXc4SuB6lwYU4LOZiZ-MQ4p57BoCvF0QAvD_BwE&gclsrc=aw.ds) or the [Android SDK](docs/dev_environment.md) for CLI only
- [Java 11](https://www.oracle.com/java/technologies/downloads/#java11) or newer
- [Gradle 8.3](https://gradle.org/releases/) 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](https://ngdocs.harness.io/article/1j7pdkqh7j-create-a-feature-flag) on the Harness Platform called harnessappdemodarkmode
- Created a [server/client SDK key](https://ngdocs.harness.io/article/1j7pdkqh7j-create-a-feature-flag#step_3_create_an_sdk_key) and made a copy of it
### Install the SDK
You can add the Android SDK to your application by adding the following snippet to root project's [build.gradle](https://github.com/harness/ff-android-client-sdk/blob/main/examples/GettingStarted/build.gradle#L2) file:
```gradle
buildscript {
repositories {
mavenCentral()
}
}
```
In app module's [build.gradle](https://github.com/harness/ff-android-client-sdk/blob/main/examples/GettingStarted/app/build.gradle#L41) file add dependency for Harness's SDK
`implementation 'io.harness:ff-android-client-sdk:2.1.0'`
### Code Sample
Here is a complete [example](https://github.com/harness/ff-android-client-sdk/blob/main/examples/GettingStarted/app/src/main/java/io/harness/cfsdk/gettingstarted/MainActivity.kt) 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.
```Kotlin
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 }
}
}
```
### Running the example
If you want to run the [getting started example](examples/GettingStarted), 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](docs/dev_environment.md).
N.B this assumes you have set `$ANDROID_SDK` to the location where the Android SDK has been installed.
#### Start the emulator
```
$ANDROID_SDK/emulator/emulator @Pixel_4.4_API_32
```
#### Build the project
```shell
./gradlew build -xtest
```
#### Install the Project
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
```shell
FF_FLAG_NAME="harnessappdemodarkmode" FF_API_KEY= ./gradlew :examples:GettingStarted:installDebug
```
The app should show the configured flags current value. As you toggle the flag in the Harrness UI you will see the
value update.
### Client Initialzation
For more information on initialzation options, see [Client Initialzation Options](docs/further_reading.md#client-initialization-options)
### Release builds and ProGuard
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.** { *; }
```
### Running the example with docker
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](docs/dev_environment.md).
With the emulator running build and install the app
```shell
# 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
```
### Additional Reading
Further examples and config options are in the further reading section:
[Further Reading](docs/further_reading.md)
[Getting Started Example](examples/GettingStarted)
-------------------------
[Harness](https://www.harness.io/) is a feature management platform that helps teams to build better software and to
test features quicker.
-------------------------