Flutter SDK

The gamifyhost_games Flutter package renders the GamifyHost game experience inside a WebView, providing a native integration for iOS and Android apps.

Installation

Add the package to your pubspec.yaml:

dependencies:
  gamifyhost_games: ^1.0.0

Then run:

flutter pub get

Platform Setup

The SDK uses webview_flutter under the hood. Ensure your platform is configured:

Android (android/app/build.gradle.kts):

android {
    defaultConfig {
        minSdk = 21  // WebView requires API 21+
    }
}

iOS (ios/Runner/Info.plist):

<key>io.flutter.embedded_views_preview</key>
<true/>

Quick Start

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

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Games')),
      body: const GamifyHostWidget(
        config: GamifyHostConfig(
          publicKey: 'pk_live_your_public_key',
          userId: 'user_12345',
          initialBalance: 5000,
        ),
      ),
    );
  }
}

Configuration

The GamifyHostConfig class accepts the following parameters:

Parameter	Type	Required	Default	Description
publicKey	String	Yes	—	Your GamifyHost public API key
userId	String	Yes	—	The authenticated user’s ID
apiUrl	String	No	https://api.gamifyhost.com	API base URL
widgetUrl	String	No	https://cdn.gamifyhost.com/widget.js	Widget script URL
initialBalance	int	No	0	Balance to show before API responds

const config = GamifyHostConfig(
  publicKey: 'pk_live_abc123',
  userId: 'user_12345',
  apiUrl: 'https://api.gamifyhost.com',
  widgetUrl: 'https://cdn.gamifyhost.com/widget.js',
  initialBalance: 5000,
);

Updating Config

Use copyWith to create a modified config:

final updatedConfig = config.copyWith(
  userId: 'user_67890',
  initialBalance: 3000,
);

Widget Properties

The GamifyHostWidget accepts these properties:

Property	Type	Default	Description
config	GamifyHostConfig	Required	Widget configuration
controller	GamifyHostController?	null	Optional controller for programmatic access
onReady	VoidCallback?	null	Called when widget finishes loading
onError	Function(String)?	null	Called on WebView loading errors
backgroundColor	Color	Color(0xFF1F1022)	Background while loading
showLoadingIndicator	bool	true	Show spinner while loading
loadingIndicatorColor	Color?	Theme primary	Spinner color

Controller

Use GamifyHostController for programmatic control:

class GameScreen extends StatefulWidget {
  const GameScreen({super.key});

  @override
  State<GameScreen> createState() => _GameScreenState();
}

class _GameScreenState extends State<GameScreen> {
  final _controller = GamifyHostController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Games'),
        actions: [
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: () => _controller.reload(),
          ),
        ],
      ),
      body: GamifyHostWidget(
        config: const GamifyHostConfig(
          publicKey: 'pk_live_abc123',
          userId: 'user_12345',
        ),
        controller: _controller,
        onReady: () => debugPrint('Widget loaded'),
        onError: (err) => debugPrint('Error: $err'),
      ),
    );
  }
}

Controller Methods

Method	Description
reload()	Reload the widget with the current config
reloadWithConfig(config)	Reload with a new GamifyHostConfig
runJavaScript(js)	Execute arbitrary JS inside the WebView
isReady	ValueNotifier<bool> indicating load state
dispose()	Clean up resources

Listening to Ready State

_controller.isReady.addListener(() {
  if (_controller.isReady.value) {
    debugPrint('Widget is ready');
  }
});

Switching Users

When the authenticated user changes (e.g. after login), reload with a new config:

_controller.reloadWithConfig(
  const GamifyHostConfig(
    publicKey: 'pk_live_abc123',
    userId: 'new_user_id',
    initialBalance: 0,
  ),
);

Or simply update the config prop — the widget auto-detects config changes and reloads:

GamifyHostWidget(
  config: GamifyHostConfig(
    publicKey: 'pk_live_abc123',
    userId: currentUserId,  // Changes trigger reload
  ),
)

Full Example

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(
          seedColor: const Color(0xFFD125F4),
          brightness: Brightness.dark,
        ),
      ),
      home: const GameScreen(),
    );
  }
}

class GameScreen extends StatefulWidget {
  const GameScreen({super.key});

  @override
  State<GameScreen> createState() => _GameScreenState();
}

class _GameScreenState extends State<GameScreen> {
  final _controller = GamifyHostController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('GamifyHost Games'),
        actions: [
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: () => _controller.reload(),
          ),
        ],
      ),
      body: GamifyHostWidget(
        config: const GamifyHostConfig(
          publicKey: 'pk_live_your_public_key',
          userId: 'user_12345',
          apiUrl: 'https://api.gamifyhost.com',
          initialBalance: 5000,
        ),
        controller: _controller,
        backgroundColor: const Color(0xFF1F1022),
        showLoadingIndicator: true,
        onReady: () => debugPrint('GamifyHost widget loaded'),
        onError: (error) => debugPrint('GamifyHost error: $error'),
      ),
    );
  }
}