Skip to main content

Migration from Android SDK v3 to v4

Migration Guide​

In the v4 SDK, we have significantly improved performance, memory management and simplified the development workflow. The most notable change is the replacement of the Debug Mode with Development Mode, which provides a more secure and streamlined approach to reporting and testing. If you are using v3 and wish to upgrade, follow these steps to migrate to v4.

Key Changes in v4​

Performance & Stability​

  • Reduced memory usage and improved memory cleanup (eliminated memory leaks)
  • Improved WebView translation by hiding the WebView until content is confirmed to be translated (fixes flickering)
  • Extended auto-translation coverage and bug fixes

New Features​

  • Development Mode replaces Debug Mode, providing improved security
  • Improved reporting with secure, client-based verification
  • "!" markers for detected but untranslated text in development mode
  • Official Jetpack Compose support for modern Android UI development

Migration Steps​

1. Remove isDebugMode parameter from Wovn.start()​

The biggest change in v4 is the removal of the isDebugMode parameter from the initialization methods. Development mode is now automatically determined by the server based on client verification.

In v3, you had to pass the isDebugMode parameter:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // v3: Debug mode passed as parameter
        this.registerActivityLifecycleCallbacks(
            new WovnActivityLifecycleCallbacks(BuildConfig.DEBUG)
        );
    }
}

In v4, simply call Wovn.start() without the debug parameter:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // v4: No debug mode parameter needed
        this.registerActivityLifecycleCallbacks(
            new WovnActivityLifecycleCallbacks()
        );
    }
}

Or if you're calling Wovn.start() directly:

// v3
Wovn.start(context, true);  // isDebugMode = true

// v4
Wovn.start(context);  // Development mode determined automatically

2. Configure Client ID in WOVN Dashboard (For Development Mode)​

Instead of programmatically enabling debug mode, v4 uses Development Mode which is activated based on a Client ID whitelist, configured in your WOVN Dashboard.

Steps to enable Development Mode:

  1. Navigate to your project App settings in the WOVN Dashboard
  2. Go to the Security section
  3. Add your device's Client ID to the whitelist
  4. Save the settings

How to find your Client ID:

You can retrieve your device's Client ID programmatically:

String clientID = Wovn.getClientID();
Log.d("WOVN", "Client ID: " + clientID);

When Development Mode is enabled, you'll see a toast message on app launch showing:

  • Report status (On/Off)
  • Your Client ID

This ensures that only authorized devices can send reports to WOVN, providing better security for your production app.

3. Remove WOVN Settings Screen Debug Mode Toggle (Optional)​

If you previously implemented the WOVN Settings Screen with the Debug Mode toggle (Method 2 from the old debug_mode.md documentation), this is no longer necessary in v4. Development mode is now managed entirely through the WOVN Dashboard.

You can safely remove:

  • The Debug Mode toggle from your WOVN Settings screen
  • Any code that programmatically sets debug mode via the settings screen

4. Test Development Mode​

After migration:

  1. Launch your app on a test device
  2. Check the logcat output for your Client ID: 
    WOVN: ClientID: <your-client-id>
  3. Add this Client ID to your WOVN Dashboard's Development Mode whitelist
  4. Restart the app
  5. Verify you see the toast message confirming Development Mode is active
  6. Verify that "!" markers appear next to untranslated text (if any)

Benefits of Development Mode​

The new Development Mode in v4 offers several advantages over the old Debug Mode:

  1. Enhanced Security: No need to modify code or rebuild the app to enable/disable reporting. Simply manage the whitelist in the Dashboard.

  2. Simplified Workflow: No more conditional compilation or build variant configurations. Development mode is determined at runtime based on server verification.

  3. Better Visibility: Toast messages and "!" markers make it easier to identify what content is being reported and what remains untranslated.

  4. Reduced Risk: Production builds cannot accidentally enable debug/reporting features, as it's controlled server-side via Client ID whitelisting.

Breaking Changes Summary​

Removed APIs​

  • Wovn.start(Context, boolean isDebugMode) - Use Wovn.start(Context) instead
  • WovnActivityLifecycleCallbacks(boolean isDebugMode) - Use WovnActivityLifecycleCallbacks() instead

Behavior Changes​

  • Development mode is now determined server-side, based on Client ID verification instead of being set programmatically
  • WebView translation now hides the WebView until translation is confirmed, eliminating flickering
  • Memory management significantly improved with elimination of memory leaks

Need Help?​

If you encounter any issues during migration:

  1. Verify your Client ID is correctly added to the Dashboard whitelist
  2. Check the logcat output for any error messages
  3. Ensure you're using v4.0.0 or later of the Android SDK
  4. Contact WOVN support for assistance

Additional Resources​