Flutter Max Miniapp

A Flutter package for interacting with the Max Mini Apps API.

This package provides a convenient way to develop Max Mini Apps using Flutter. It handles the underlying JavaScript interop, providing you with type-safe Dart classes and methods to access the Max Mini Apps API via the MAX Bridge.

Ready for compilation in WASM

Features

  • Access to Web App API: Provides the MaxWebApp singleton class for accessing the Max Web App API methods.
  • Interface Control: Allows you to control the Mini App interface — back button, closing confirmation, screen brightness, vertical swipes.
  • Event Handling: Offers a MaxEventHandler class to subscribe to events such as back button press.
  • Typed Data: Includes strongly typed enums for haptic feedback styles and notification types.
  • Asynchronous Operations: Uses async/await with Future for non-blocking access to the API.
  • JS Interop: Employs dart:js_interop for direct interaction with the JavaScript API.
  • Biometric Support: Support for biometric authentication via BiometricManager.
  • Storage: Access to DeviceStorage (local on-device) and SecureStorage (encrypted).
  • Haptic Feedback: Trigger impact, notification, and selection-change vibrations via HapticFeedback.
  • Screen Capture Control: Block or allow screenshots and screen recording via ScreenCapture.
  • Sharing: Native OS share sheet (shareContent) and in-app Max sharing (shareMaxContent).
  • QR Code Reader: Open camera to scan QR codes via openCodeReader.
  • Well-Structured: Organized code into enums, extensions, and types folders.

Getting started

Add flutter_max_miniapp as a dependency in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  flutter_max_miniapp:
    path: local_plugins/mini_app/max

Add the Max bridge script to web/index.html:

<head>
  ...
  <script src="https://st.max.ru/js/max-web-app.js"></script>
</head>

Then import it in your Dart code:

import 'package:flutter_max_miniapp/flutter_max_miniapp.dart';

Usage

Initialization

Before using any other method, initialize the MaxWebApp class:

void main() {
  try {
    MaxWebApp().init();
    runApp(MyApp());
  } catch (e) {
    print('Error initializing Mini App: $e');
  }
}

Accessing Web App API

You can access the Max Web App API through the MaxWebApp() singleton:

final webApp = MaxWebApp();

// Signal readiness to Max
webApp.ready();

// Read user data (validate initData on your server!)
final initData = webApp.initDataUnsafe;
print(initData?.user?.firstName);
print(webApp.platform); // ios, android, desktop, web
print(webApp.version);  // e.g. 25.9.16

// Closing confirmation
webApp.enableClosingConfirmation();

// Open an external link
webApp.openLink('https://example.com');

// Open a Max deep link
webApp.openMaxLink('https://max.ru/some-path');

Back Button

final webApp = MaxWebApp();

// Show the back button
webApp.backButton.show();

// Handle back button press
webApp.backButton.onClick(() {
  print('Back button pressed');
});

// Hide the back button
webApp.backButton.hide();

Haptic Feedback

final haptic = MaxWebApp().hapticFeedback;

// Impact vibration
await haptic.impactOccurred(style: HapticFeedbackImpactStyle.medium);

// Notification vibration
await haptic.notificationOccurred(type: HapticFeedbackNotificationType.success);

// Selection change
await haptic.selectionChanged();

Screen Capture

final capture = MaxWebApp().screenCapture;

// Block screenshots
await capture.enableScreenCapture();

// Allow screenshots
await capture.disableScreenCapture();

Device Storage

final storage = MaxWebApp().deviceStorage;

await storage.setItem('key', 'value');
final value = await storage.getItem('key');
await storage.removeItem('key');
await storage.clear();

Secure Storage

final secure = MaxWebApp().secureStorage;

await secure.setItem('token', 'secret');
final token = await secure.getItem('token');
await secure.removeItem('token');

Biometric Manager

final bio = MaxWebApp().biometricManager;

// Initialize (call once)
await bio.init();

// Check availability
if (bio.isBiometricAvailable) {
  await bio.requestAccess(reason: 'Secure login');
  final result = await bio.authenticate(reason: 'Confirm identity');
}

QR Code Reader

final result = await MaxWebApp().openCodeReader(fileSelect: true);

Sharing

final webApp = MaxWebApp();

// Native OS share
await webApp.shareContent(text: 'Check this out', link: 'https://example.com');

// In-app Max share
await webApp.shareMaxContent(text: 'Hello', link: 'https://max.ru/something');

File Download

await MaxWebApp().downloadFile(
  url: 'https://example.com/file.pdf',
  fileName: 'document.pdf',
);

Screen Brightness

final webApp = MaxWebApp();

// Max brightness for 30 seconds
await webApp.requestScreenMaxBrightness();

// Restore original brightness
await webApp.restoreScreenBrightness();

Vertical Swipes

final webApp = MaxWebApp();

// Disable swipe-to-close
await webApp.disableVerticalSwipes();

// Re-enable swipe-to-close
await webApp.enableVerticalSwipes();

Working with Events

The MaxEventHandler class allows subscribing to bridge events:

final eventHandler = MaxWebApp().eventHandler;

eventHandler.onBackButtonPressed.listen((_) {
  print('Back button was pressed');
});

Request Contact

final result = await MaxWebApp().requestContact();

API Reference

Object / Method Description
MaxWebApp Main entry point — singleton
.initData Raw init data string for server validation
.initDataUnsafe Parsed WebAppInitData (user, chat, query_id, etc.)
.platform ios, android, desktop, web
.version Max app version
.ready() Signal readiness
.close() Close the mini-app
.enableClosingConfirmation() Show "unsaved data" dialog on close
.disableClosingConfirmation() Disable close confirmation
.openLink(url) Open URL in external browser
.openMaxLink(url) Open max.ru deep link inside Max
.requestContact() Request user phone number
.downloadFile(url, fileName) Download a file (https only)
.shareContent(text, link) Native OS share sheet
.shareMaxContent(...) In-app Max share dialog
.openCodeReader(fileSelect) Scan QR code
.requestScreenMaxBrightness() Max brightness for 30s
.restoreScreenBrightness() Restore brightness
.enableVerticalSwipes() Enable swipe-to-close
.disableVerticalSwipes() Disable swipe-to-close
BackButton .show(), .hide(), .onClick(), .offClick()
HapticFeedback .impactOccurred(), .notificationOccurred(), .selectionChanged()
ScreenCapture .enableScreenCapture(), .disableScreenCapture()
DeviceStorage .setItem(), .getItem(), .removeItem(), .clear()
SecureStorage .setItem(), .getItem(), .removeItem()
BiometricManager .init(), .requestAccess(), .authenticate(), .updateBiometricToken(), .openSettings()

Max Bridge Documentation

License

This project is licensed under the MIT License.

Libraries

flutter_max_miniapp