Skip to main content

Solving Flutter Debug Install Failures on Vivo Devices (One-Click Auth)

 When executing flutter run on a physical Vivo device, the process frequently stalls at "Installing build/app/outputs/flutter-apk/app-debug.apk" or hard-crashes with INSTALL_FAILED_USER_RESTRICTED and INSTALL_CANCELED_BY_USER. Standard Android USB debugging toggles are insufficient to bypass this block.

In modern Flutter app development, deploying to physical hardware is vital for accurate cross-platform debugging. However, Vivo's proprietary Android skins (Funtouch OS and OriginOS) implement aggressive security layers that intercept standard Android Debug Bridge (ADB) commands. Resolving this requires accessing a hidden system menu via the USSD dialer to grant one-click authorization.

The Root Cause of Vivo ADB Rejections

Under standard Android Open Source Project (AOSP) architecture, enabling USB Debugging grants the ADB daemon (adbd) the necessary INSTALL_PACKAGES permission. This allows the Flutter toolchain to compile the Dart code, generate an APK, and silently install it via the adb install command.

Vivo's custom OS intercepts standard PackageManager requests. When adbd attempts to install an APK, the OS routes the request through a proprietary system app (often BBKInstaller). If the device does not recognize an explicit developer authorization state, BBKInstaller forcibly terminates the ADB session to prevent malicious sideloading.

This strict enforcement mechanism breaks the standard mobile application deployment pipeline. The OS demands a registered Vivo developer account and a specific hardware-level override that is intentionally hidden from the standard "Developer Options" menu.

The Fix: Bypassing the BBKInstaller Restriction

To resolve the installation failure, you must authenticate the device and expose the hidden "One-click authorization" settings.

Step 1: Bind a Vivo Developer Account

Before accessing the hidden menu, the device must verify your identity.

  1. Navigate to Settings > Accounts & Sync (or Vivo Account at the top of settings).
  2. Create or log into a Vivo developer account.
  3. Ensure the device is connected to the internet during this process, as the OS requires server-side validation to unlock the local deployment flags.

Step 2: Access the Hidden USSD Dialer Menu

Standard developer options do not contain the necessary overrides. You must use a dialer code to access the factory-level debugging menu.

  1. Open the native Phone/Dialer application.
  2. Enter the following USSD code exactly: *#*#112#*#*
  3. The device will immediately transition to a hidden screen titled Log and debugging or Factory test.

Step 3: Enable One-Click Authorization

Within the hidden menu, locate the security overrides.

  1. Tap on One-click authorization (sometimes labeled as BBKlog or Debug Authorization depending on the Funtouch OS version).
  2. Toggle the setting to ON.
  3. Return to the standard Android Developer Options menu.
  4. Locate Install via USB and toggle it ON. You may be prompted to enter your Vivo account password to confirm this change.

Deep Dive: Modifying the Flutter Deployment Pipeline

Once the hardware is authorized, the Flutter CLI can successfully communicate with the Vivo device. However, Vivo's package manager often performs aggressive background caching. If a previous debug session failed or was uninstalled manually, the system may retain ghost files that block subsequent flutter run commands.

To ensure a clean installation, bypass the standard IDE play button and use a custom deployment script. This allows you to pass specific ADB flags (-r for replace, -t for test packages, -d to allow downgrades) directly to the device.

Create a deploy_vivo.sh (or .bat for Windows) file in your Flutter project root:

#!/bin/bash
# deploy_vivo.sh - Execute with: bash deploy_vivo.sh

echo "Building Flutter APK for Vivo Deployment..."
flutter build apk --debug

# The package name from your pubspec.yaml / AndroidManifest.xml
PACKAGE_NAME="com.yourcompany.app"

echo "Clearing cached BBKInstaller states..."
adb shell pm uninstall -k $PACKAGE_NAME 2>/dev/null

echo "Installing application via ADB with override flags..."
# -r: Replace existing application
# -t: Allow test packages
# -d: Allow version code downgrade
adb install -r -t -d build/app/outputs/flutter-apk/app-debug.apk

echo "Launching application..."
adb shell am start -n $PACKAGE_NAME/.MainActivity

For developers relying on VS Code, you can optimize the launch configuration to handle Vivo's slightly delayed install times. The OS occasionally triggers a split-second UI prompt during installation. Extending the timeout prevents the IDE from detaching.

Update your .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Vivo Debug Deployment",
      "request": "launch",
      "type": "dart",
      "flutterMode": "debug",
      "args": [
        "--verbose"
      ],
      "toolArgs": [
        "--timeout",
        "120"
      ]
    }
  ]
}

Handling Edge Cases and Alternative Configurations

USSD Code Unresponsive

On specific regional variants of OriginOS (primarily devices shipped within mainland China), the standard *#*#112#*#* code may be disabled. If the dialer clears the text without opening a menu, use the fallback code: *#*#4256#*#*.

Wi-Fi Debugging Interference

Vivo's One-click authorization is notoriously unstable when paired with Wireless ADB. The authorization token is strictly bound to the physical USB connection state. Ensure Wireless Debugging is completely disabled in the Developer Options, and rely exclusively on a high-bandwidth USB-C cable for the initial deployment.

"App Not Installed" on Subsequent Runs

If you successfully run the application once, but subsequent hot restarts or rebuilds fail with INSTALL_FAILED_UPDATE_INCOMPATIBLE, the Vivo package verifier is blocking the signature update. You must explicitly disable package verification via ADB:

adb shell settings put global verifier_verify_adb_installs 0
adb shell settings put global package_verifier_enable 0

Final Deployment Verification

By authenticating the hardware through the USSD interface, you remove the BBKInstaller blockade from the standard ADB pipeline. The combination of the One-click authorization toggle and strict ADB replacement flags (-r -t -d) ensures that the Flutter toolchain can natively compile, deploy, and attach the Dart VM debugger to physical Vivo devices without encountering permission restrictions.

Labels: