Apptuner #

Integrate Apptuner into your Flutter application with just a few lines of code. The SDK automatically handles force update and maintenance mode checks — including built-in overlay screens that block user interaction when required.

Features #

• Force Update: Automatically prompt users to update their app when a critical version is released.
• Maintenance Mode: Display a maintenance screen when your backend services are down or undergoing maintenance.
• Cross-Platform: Works seamlessly on both Android and iOS.
• Customization: Fully customizable UI for overlay screens.

Installation #

Add apptuner to your pubspec.yaml:

dependencies:
  apptuner: ^1.0.0

Or run:

flutter pub add apptuner

Usage #

1. Initialize the SDK #

Initialize apptuner in your main() before calling runApp. The SDK only requires your API Key — the platform and app version are detected automatically.

import 'package:apptuner/apptuner.dart';
import 'package:flutter/material.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize apptuner with your API Key
  await apptuner.init(apiKey: 'YOUR_API_KEY');

  runApp(const MyApp());
}

Note: init() fetches the latest config from the Apptuner API on startup. The SDK automatically sends the current platform (android / ios) and app version with every request.

2. Add the ApptunerWrapper #

Wrap your app with ApptunerWrapper to automatically display a force update or maintenance overlay when needed. The easiest way is using the builder property of MaterialApp:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      builder: (context, child) {
        return ApptunerWrapper(
          child: child!,
        );
      },
      home: const HomeScreen(),
    );
  }
}

The wrapper automatically:

• Displays a maintenance screen when maintenance mode is active.
• Displays a force update dialog when a required update is available.
• Re-checks the config every time the app is resumed from background.

3. Customization #

Custom Styling

Use ApptunerStyle to customize the appearance of the built-in overlay screens:

ApptunerWrapper(
  style: const ApptunerStyle(
    backgroundGradient: LinearGradient(
      colors: [Colors.purple, Colors.blue],
    ),
    maintenanceIconColor: Colors.red,
    updateIconColor: Colors.orange,
    maintenanceIconBackgroundColor: Colors.black,
    updateIconBackgroundColor: Color(0xFF5A3010),
    titleStyle: TextStyle(fontSize: 28, fontWeight: FontWeight.bold),
    messageStyle: TextStyle(fontSize: 16, color: Colors.grey),
    buttonGradient: LinearGradient(
      colors: [Colors.orange, Colors.deepOrange],
    ),
    buttonTextStyle: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
  ),
  child: child!,
);

Fully Custom UI with Builder

For complete control over the overlay, use the builder parameter to render your own widget when maintenance or a force update is active:

ApptunerWrapper(
  builder: (context, config) {
    if (config.forceUpgrade) {
      return MyCustomUpdateScreen(message: config.message);
    }
    return MyCustomMaintenanceScreen(message: config.message);
  },
  child: child!,
);

The TunerConfig object passed to the builder contains:

4. Manual Update Check #

You can manually trigger a config re-fetch at any time — for example, from a pull-to-refresh or a button tap:

IconButton(
  icon: const Icon(Icons.refresh),
  onPressed: () {
    apptuner.checkUpdate();
  },
);

5. Access Config Directly #

If you need to read the config values without using the wrapper (e.g., for custom logic), you can access them directly:

if (apptuner.isMaintenance) {
  // App is in maintenance mode
}

if (apptuner.forceUpgrade) {
  // A required update is available
}

// Read individual fields
print(apptuner.message);
print(apptuner.androidSource);
print(apptuner.appleSource);

You can also listen for config changes since Apptuner extends ChangeNotifier:

apptuner.addListener(() {
  final config = apptuner.config;
  // React to config changes
});