Skip to main content

Migration from iOS SDK v3 to v4

Migration Guide​

In the v4 SDK, we have significantly improved performance, SwiftUI support 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​

  • Improved WebView translation by hiding the WebView until content is confirmed to be translated (fixes flickering)
  • Improved Push Notification translation by only retrieving the content of the "PushNotification" screen for faster translation
  • Extended auto-translation coverage and bug fixes

New Features​

  • Development Mode replaces Debug Mode, providing improved security
  • Improved reporting with secure, client-based verification
  • SwiftUI auto-translation - no need to change Text to WovnText or Button to WovnButton
  • "!" markers for detected but untranslated text in development mode

Migration Steps​

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

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

In v3, you had to pass the isDebugMode parameter:

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // v3: Debug mode passed as parameter
        Wovn.start(isDebugMode: _isDebugAssertConfiguration())
        return true
    }
}

Or using the #if DEBUG directive:

// v3: Using preprocessor directive
#if DEBUG
    Wovn.start(isDebugMode: true)
#else
    Wovn.start(isDebugMode: false)
#endif

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

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // v4: No debug mode parameter needed
        Wovn.start()
        return true
    }
}

If you were using other parameters:

// v3
Wovn.start(appGroupIdentifier: "group.com.example.app", isDebugMode: true, autoTranslateUIKit: true)

// v4
Wovn.start(appGroupIdentifier: "group.com.example.app", autoTranslateUIKit: true)

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:

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

  • Report status (ON/OFF)
  • Your Client ID

Alternatively, check the console logs for:

ClientID: <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. Update SwiftUI Code (Optional - Simplification)​

One of the major improvements in v4 is automatic SwiftUI translation. You no longer need to use custom WovnText or WovnButton wrappers.

In v3, you had to use WOVN-specific wrappers:

// v3: Required custom wrappers
struct ContentView: View {
    var body: some View {
        VStack {
            WovnText("Hello World")
            WovnButton("Click Me") {
                // action
            }
        }
    }
}

In v4, standard SwiftUI components are automatically translated:

// v4: Use standard SwiftUI components
struct ContentView: View {
    var body: some View {
        VStack {
            Text("Hello World")  // Automatically translated
            Button("Click Me") { // Automatically translated
                // action
            }
        }
    }
}

This is a breaking change in the sense that if you were using WovnText and WovnButton, you should migrate to standard SwiftUI components for better compatibility and simpler code.

5. Test Development Mode​

After migration:

  1. Launch your app on a test device
  2. Check the console output for your Client ID: 
    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 configuration checks. 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.

Additional Improvements in v4​

WebView Translation Enhancement​

WebViews are now hidden until translation is confirmed, eliminating the flickering that could occur during the translation process. This provides a smoother user experience.

Push Notification Performance​

Push notification translation is now faster by only retrieving content specific to the "PushNotification" screen, rather than loading all translation data.

SwiftUI Support​

v4 brings first-class SwiftUI support with automatic translation of standard SwiftUI components like Text, Button, Label, and more - without requiring custom wrappers.

Untranslated Text Detection​

When running in Development Mode, any text that is detected but not yet translated will be marked with a "!" prefix, making it easy to identify missing translations during testing.

Breaking Changes Summary​

Removed Parameters​

  • Wovn.start(isDebugMode: Bool) - The isDebugMode parameter has been removed. Use Wovn.start() instead.

Behavior Changes​

  • Development mode is now determined server-side, based on Client ID verification instead of being set programmatically
  • SwiftUI components are automatically translated without requiring custom wrappers
  • WebView translation now hides the WebView until translation is confirmed, eliminating flickering

Deprecated APIs​

  • Custom WovnText and WovnButton wrappers (if they existed) are no longer needed - use standard SwiftUI components instead

Need Help?​

If you encounter any issues during migration:

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

Additional Resources​