docs: migration guide (#70)

* docs: migration guide --------- Co-authored-by: Thomas Heartman <[email protected]>
Unleash · Jul 25, 2024 · f1589ce · f1589ce
1 parent f644902
commit f1589ce
Show file tree

Hide file tree

Showing 2 changed files with 122 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -6,15 +6,17 @@
 
 ## Getting started
 
-This is the Android SDK for Unleash Proxy. It is a lightweight SDK that allows you to connect to the Unleash Proxy and fetch feature toggles.
+This is the Android SDK for [Unleash Frontend API](https://docs.getunleash.io/reference/front-end-api) provided by the [Unleash server](https://github.com/Unleash/unleash) or [Unleash Edge](https://github.com/Unleash/unleash-edge). It is a lightweight SDK that allows you to connect to the Unleash Proxy and fetch feature toggles.
 
 This supersedes the [previous Unleash Android Proxy SDK](https://github.com/Unleash/unleash-android-proxy-sdk/) this one is a an Android library instead of a Java library. 
 
 It's not a drop-in replacement of the previous one, so it requires code changes to use it.
 
 **What are the benefits of migrating?**
-1. This SDK will respect the Android lifecycle and stop polling when the app is in the background.
-2. It will also respect the network state and only poll when the device is connected to the internet.
+1. Respects the Android lifecycle and stops polling and sending metrics in the background.
+2. Monitors network connectivity to avoid unnecessary polling (requires API level 23 or above).
+3. Uses the native Android logging system instead of SLF4J.
+4. Respects the minimum Android API level 21, but we recommend API level 23.
 
 ### Step 1
 

diff --git a/docs/MigrationGuide.md b/docs/MigrationGuide.md
@@ -0,0 +1,117 @@
+# Migration Guide from unleash-android-proxy-sdk
+
+This guide provides detailed steps for migrating your project from the Unleash Android Proxy SDK version to the newer Unleash Android SDK.
+
+We will focus on the [previous sample application](https://github.com/Unleash/unleash-android-proxy-sdk/tree/main/samples/android), specifically highlighting the changes from this pull request: https://github.com/Unleash/unleash-android-proxy-sdk/pull/83
+
+## Benefits of Migrating
+
+This version of the Unleash Android SDK introduces several improvements, including:
+- Uses the native Android logging system instead of SLF4J.
+- Respects the Android lifecycle and stops polling and sending metrics in the background.
+- Respects the minimum Android API level 21, but we recommend API level 23.
+- Monitors network connectivity to avoid unnecessary polling (requires API level 23 or above).
+
+## Overview
+
+The new SDK introduces several changes and improvements, including API modifications and a new initialization process.
+
+## Step-by-Step Migration
+
+### 1. Update Gradle Dependency
+
+First, update the dependency in your `build.gradle` file:
+
+```gradle
+dependencies {
+    // Remove the old SDK
+    implementation 'io.getunleash:unleash-android-proxy-sdk:0.5.0'
+
+    // Add the new SDK
+    implementation 'io.getunleash:unleash-android:$version'
+}
+```
+
+### 2. Update the initialization code
+We won't cover all the details here as most of the configuration can be set using the builders fluent methods. However, the main difference is that the new SDK requires an `Application` context to be passed to the `Unleash` constructor. This is necessary to monitor the network connectivity and respect the Android lifecycle. If you use hilt, this can be injected with `@ApplicationContext context`.
+
+#### Unleash context initialization
+The main differences are:
+1. The application name is no longer configurable through the context, as it is constant throughout the application's lifetime. The `appName` should be set using the `UnleashConfig` builder.
+2. The instance ID is no longer configurable. The SDK will generate a unique instance ID for each instance.
+3. Update the import statements to use the new SDK classes.
+
+```kotlin
+val unleashContext = UnleashContext.newBuilder()
+    // .appName("unleash-android") // remove this line
+    // .instanceId("main-activity-unleash-demo-${Random.nextLong()}") // remove this line
+    .userId("unleash_demo_user")
+    .sessionId(Random.nextLong().toString())
+    .build()
+```
+
+#### Unleash configuration
+The main differences are:
+1. Metrics are enabled by default.
+2. App name is now a mandatory parameter to the builder.
+3. Instance id is no longer configurable.
+4. The polling mode is now a polling strategy with a fluent API.
+5. The metrics interval is now part of the metrics strategy with a fluent API.
+
+**Old SDK**
+```kotlin
+UnleashConfig.newBuilder()
+    .appName("unleash-android")
+    .instanceId("unleash-android-${Random.nextLong()}")
+    .enableMetrics()
+    .clientKey("xyz")
+    .proxyUrl("https://eu.app.unleash-hosted.com/demo/api/frontend")
+    .pollingMode(
+        PollingModes.autoPoll(
+            autoPollIntervalSeconds = 15
+        ) {
+
+        }
+    )
+    .metricsInterval(5000)
+    .build()
+```
+
+**New SDK**
+```kotlin
+UnleashConfig.newBuilder("unleash-android")
+    .clientKey("xyz")
+    .proxyUrl("https://eu.app.unleash-hosted.com/demo/api/frontend")
+    .pollingStrategy.interval(15000)
+    .metricsStrategy.interval(5000)
+    .build()
+```
+
+#### Creating the Unleash instance
+The previous SDK used a builder to construct the Unleash instance while the new SDK relies on constructor parameters. There are also other meaningful changes:
+
+1. The new SDK does not start automatically. You need to call `unleash.start()` to start the polling and metrics collection.
+2. The new SDK accepts event listeners at the constructor level or as parameters when calling `unleash.start()` (you can also edit your config object setting `delayedInitialization` to false).
+3. The interface `UnleashClientSpec` is now `Unleash`.
+
+```kotlin
+UnleashClient.newBuilder()
+    .unleashConfig(unleashConfig)
+    .unleashContext(unleashContext)
+    .build()
+```
+
+**New SDK**
+_Note:_ Android context is now required to be passed to the Unleash constructor and you will usually want it to be bound to the application context.
+
+```kotlin
+val unleash = DefaultUnleash(
+            androidContext = context,
+            unleashConfig = unleashConfig,
+            unleashContext = unleashContext
+        )
+unleash.start()
+```
+
+#### Updating class references
+Most of the classes have been moved to `io.getunleash.android` package. Update the import statements in your classes.