|
| 1 | +--- |
| 2 | +title: Android SDK v9 Migration Guide |
| 3 | +sidebar_label: Android SDK v9 |
| 4 | +description: Upgrade the Embedded Wallets Android SDK directly from older versions to v9. |
| 5 | +keywords: [migration, v9, android, web3auth, embedded wallets, kotlin] |
| 6 | +--- |
| 7 | + |
| 8 | +This guide upgrades Embedded Wallets Android SDK integrations from **v4 through v8** directly to |
| 9 | +**v9**. |
| 10 | + |
| 11 | +## AI-assisted migration |
| 12 | + |
| 13 | +For the best results, install the MetaMask Embedded Wallets **skill** and **MCP server** before |
| 14 | +you migrate. |
| 15 | +See [Build with AI](/embedded-wallets/build-with-ai) for setup (`npx skills add web3auth/skill` and |
| 16 | +MCP at `https://mcp.web3auth.io`). |
| 17 | + |
| 18 | +Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, Antigravity, or |
| 19 | +similar): |
| 20 | + |
| 21 | +```txt |
| 22 | +Migrate my MetaMask Embedded Wallets Android (web3auth-android-sdk) project to v9. |
| 23 | +
|
| 24 | +Before changing code: |
| 25 | +1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference). |
| 26 | +2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/android-v9 |
| 27 | +3. Detect my current SDK version from build.gradle and list which breaking changes apply. |
| 28 | +
|
| 29 | +Then migrate my codebase directly to v9: |
| 30 | +- Update the JitPack dependency to com.github.web3auth:web3auth-android-sdk:9.1.2 (or latest v9). |
| 31 | +- Set compileSdk and targetSdk to 34. |
| 32 | +- Add mandatory redirectUrl to Web3AuthOptions ({YOUR_APP_PACKAGE_NAME}://auth). |
| 33 | +- Update AndroidManifest.xml (allowBackup=false, tools:replace, deep link intent filter, singleTop). |
| 34 | +- Replace getSignResponse() with the SignResponse returned from request(). |
| 35 | +- Remove loginParams from launchWalletServices and request; pass chainConfig instead. |
| 36 | +- Update WhiteLabelData fields (appName, mode, buildEnv) if whitelabeling is configured. |
| 37 | +- Do not change my Client ID or Sapphire network unless I ask — that would change wallet addresses. |
| 38 | +
|
| 39 | +After migrating, list every file you changed and any manual dashboard steps I still need to do. |
| 40 | +``` |
| 41 | + |
| 42 | +:::tip |
| 43 | + |
| 44 | +Use planning mode (where available) for the initial prompt. |
| 45 | +Review the plan before generating code; config mistakes can change wallet addresses in production. |
| 46 | + |
| 47 | +::: |
| 48 | + |
| 49 | +## Install v9 |
| 50 | + |
| 51 | +Add JitPack to your project-level `build.gradle` if it is not already present: |
| 52 | + |
| 53 | +```groovy |
| 54 | +dependencyResolutionManagement { |
| 55 | + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) |
| 56 | + repositories { |
| 57 | + google() |
| 58 | + mavenCentral() |
| 59 | + maven { url "https://jitpack.io" } |
| 60 | + } |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +Update the dependency in your app-level `build.gradle`: |
| 65 | + |
| 66 | +```groovy |
| 67 | +dependencies { |
| 68 | + implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Set `compileSdk` and `targetSdk` to **34**: |
| 73 | + |
| 74 | +```groovy |
| 75 | +android { |
| 76 | + compileSdk 34 |
| 77 | +
|
| 78 | + defaultConfig { |
| 79 | + minSdk 24 |
| 80 | + targetSdk 34 |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +## Breaking changes |
| 86 | + |
| 87 | +Apply the sections below that match your current version. |
| 88 | +If you're already on v8, focus on the [v9 changes](#v9-changes). |
| 89 | + |
| 90 | +### Network and SDK requirements (from v5) |
| 91 | + |
| 92 | +Use Sapphire networks instead of legacy OpenLogin networks: |
| 93 | + |
| 94 | +```kotlin |
| 95 | +val web3Auth = Web3Auth( |
| 96 | + Web3AuthOptions( |
| 97 | + context = this, |
| 98 | + clientId = getString(R.string.web3auth_project_id), |
| 99 | + network = Network.SAPPHIRE_MAINNET, // or Network.SAPPHIRE_DEVNET |
| 100 | + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), |
| 101 | + ) |
| 102 | +) |
| 103 | +``` |
| 104 | + |
| 105 | +Add `buildEnv` when you need a non-production auth environment: |
| 106 | + |
| 107 | +```kotlin |
| 108 | +buildEnv = BuildEnv.PRODUCTION // PRODUCTION, STAGING, or TESTING |
| 109 | +``` |
| 110 | + |
| 111 | +### Whitelabel configuration (from v5) |
| 112 | + |
| 113 | +`WhiteLabelData` field names changed: |
| 114 | + |
| 115 | +| v4 and earlier | v5 and later | |
| 116 | +| -------------- | ------------------------------------------------------- | |
| 117 | +| `name` | `appName` | |
| 118 | +| `dark` | `mode` (`ThemeModes.LIGHT`, `ThemeModes.DARK`, or auto) | |
| 119 | + |
| 120 | +New optional fields include `appUrl` and `useLogoLoader`. |
| 121 | +Prefer [dashboard customization](/embedded-wallets/dashboard/customization) for new projects. |
| 122 | + |
| 123 | +### Mandatory redirect URL (from v7.4) |
| 124 | + |
| 125 | +`redirectUrl` is required in `Web3AuthOptions`: |
| 126 | + |
| 127 | +```kotlin |
| 128 | +redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth") |
| 129 | +``` |
| 130 | + |
| 131 | +Allowlist `{SCHEME}://{YOUR_APP_PACKAGE_NAME}` on the |
| 132 | +[Embedded Wallets dashboard](https://developer.metamask.io). |
| 133 | + |
| 134 | +### AndroidManifest changes (from v7.1.2) |
| 135 | + |
| 136 | +From v7.1.2, set `android:allowBackup` to `false` and add `tools:replace`: |
| 137 | + |
| 138 | +```xml |
| 139 | +<application |
| 140 | + android:allowBackup="false" |
| 141 | + tools:replace="android:fullBackupContent" |
| 142 | + android:dataExtractionRules="@xml/data_extraction_rules" |
| 143 | + android:fullBackupContent="@xml/backup_rules" |
| 144 | + android:icon="@mipmap/ic_launcher"> |
| 145 | +</application> |
| 146 | +``` |
| 147 | + |
| 148 | +Set your main activity `launchMode` to **singleTop** and add the deep link intent filter. |
| 149 | +See the [Android SDK get started](/embedded-wallets/sdk/android/) for the full manifest setup. |
| 150 | + |
| 151 | +### `launchWalletServices` signature (from v7.2) |
| 152 | + |
| 153 | +Remove `loginParams`. |
| 154 | +Pass only `chainConfig`: |
| 155 | + |
| 156 | +```kotlin |
| 157 | +val launchWalletCompletableFuture = web3Auth.launchWalletServices( |
| 158 | + chainConfig = ChainConfig( |
| 159 | + chainId = "0x1", |
| 160 | + rpcTarget = "https://rpc.ethereum.org", |
| 161 | + ticker = "ETH", |
| 162 | + chainNamespace = ChainNamespace.EIP155, |
| 163 | + ) |
| 164 | +) |
| 165 | +``` |
| 166 | + |
| 167 | +### `request` signature (from v7.3) |
| 168 | + |
| 169 | +Remove `loginParams`. |
| 170 | +Pass `chainConfig`, method name, and request parameters: |
| 171 | + |
| 172 | +```kotlin |
| 173 | +val params = JsonArray().apply { |
| 174 | + add("Hello, World!") |
| 175 | + add(address) |
| 176 | +} |
| 177 | + |
| 178 | +val signMsgCompletableFuture = web3Auth.request( |
| 179 | + chainConfig = ChainConfig( |
| 180 | + chainId = "0x1", |
| 181 | + rpcTarget = "https://rpc.ethereum.org", |
| 182 | + ticker = "ETH", |
| 183 | + chainNamespace = ChainNamespace.EIP155, |
| 184 | + ), |
| 185 | + "personal_sign", |
| 186 | + requestParams = params, |
| 187 | +) |
| 188 | +``` |
| 189 | + |
| 190 | +### v9 changes {#v9-changes} |
| 191 | + |
| 192 | +`getSignResponse()` is removed. |
| 193 | +The `request()` method returns `SignResponse` directly: |
| 194 | + |
| 195 | +```kotlin |
| 196 | +signMsgCompletableFuture.whenComplete { signResult, error -> |
| 197 | + if (error == null) { |
| 198 | + Log.d("Sign Result", signResult.toString()) |
| 199 | + } else { |
| 200 | + Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong") |
| 201 | + } |
| 202 | +} |
| 203 | +``` |
| 204 | + |
| 205 | +v9 also adds support for Web3Auth Auth Service v9 and Wallet Services v3 (including swap in the |
| 206 | +prebuilt wallet UI). |
| 207 | + |
| 208 | +## New APIs (non-breaking) |
| 209 | + |
| 210 | +These APIs were added in intermediate versions. |
| 211 | +If you're upgrading from an older SDK, adopt the v9 signatures shown above. |
| 212 | + |
| 213 | +| API | Added in | Purpose | |
| 214 | +| ------------------------ | -------- | --------------------------------------------- | |
| 215 | +| `enableMFA()` | v6 | Initiate MFA setup for logged-in users | |
| 216 | +| `launchWalletServices()` | v6 | Open the templated wallet UI | |
| 217 | +| `request()` | v6.1 | Sign transactions with confirmation screens | |
| 218 | +| SMS Passwordless login | v7.2 | `Provider.SMS_PASSWORDLESS` with `login_hint` | |
| 219 | +| Farcaster login | v7.2 | `Provider.farcaster` | |
| 220 | + |
| 221 | +See [Wallet Services](/embedded-wallets/sdk/android/usage/launch-wallet-services) and |
| 222 | +[MFA](/embedded-wallets/sdk/android/advanced/mfa) for usage details. |
| 223 | + |
| 224 | +## Summary table |
| 225 | + |
| 226 | +| Area | Before v5 | v5–v7.3 | v9 | |
| 227 | +| ---------------------- | ------------------- | -------------------------- | --------------------------- | |
| 228 | +| Network | MAINNET, CYAN, etc. | Sapphire supported | Sapphire recommended | |
| 229 | +| compileSdk / targetSdk | 33 | 34 | 34 | |
| 230 | +| `redirectUrl` | Optional | Mandatory (v7.4+) | Mandatory | |
| 231 | +| Whitelabel `name` | `name` | `appName` | `appName` | |
| 232 | +| `launchWalletServices` | N/A | Drops `loginParams` (v7.2) | `chainConfig` only | |
| 233 | +| `request` | N/A | Drops `loginParams` (v7.3) | Returns `SignResponse` | |
| 234 | +| Sign result | N/A | `getSignResponse()` | Return value of `request()` | |
| 235 | + |
| 236 | +## Next steps |
| 237 | + |
| 238 | +- [Android SDK get started](/embedded-wallets/sdk/android/) |
| 239 | +- [Build with AI](/embedded-wallets/build-with-ai) for ongoing integration help |
| 240 | +- [Release notes](https://github.com/Web3Auth/web3auth-android-sdk/releases) |
0 commit comments