RemoteBase Flutter Package

A Flutter package for displaying a highly configurable, draggable, and dismissible webview popup. Ideal for showing remote content, upload status, or any web-based information within your app seamlessly.

It supports loading content from a specified API endpoint, handles API key integration, and includes features like shimmer loading effects and content pre-caching.

Features

  • Draggable Popup: Users can drag the popup around the screen by its header.
  • Dismissible: Tap outside the popup or use the close button to dismiss it.
  • Webview Content: Loads and displays content from a remote URL within a webview.
  • API Integration: Initializes with an API key and base URL, automatically appending the key to content requests.
  • Shimmer Loading: Shows an elegant shimmer/skeleton loading effect while web content is being fetched.
  • Error Handling: Displays a user-friendly error message if web content fails to load.
  • Content Pre-caching: Optionally pre-fetches and caches specified content paths during initialization for faster subsequent loads (relies on server caching headers).
  • Customizable: The popup's appearance and behavior can be further customized.

Getting Started

Prerequisites

Ensure you have Flutter installed. This package relies on the webview_flutter, shimmer, and http packages.

Installation

Add remote_base to your pubspec.yaml dependencies:

dependencies:
  flutter:
    sdk: flutter
  remote_base: ^0.0.1 # Replace with the latest version

Then, run flutter pub get.

Initialization

Initialize RemoteBase early in your application's lifecycle, typically in your main.dart's main() function. Provide your API key and the base URL for your backend.

import 'package:flutter/material.dart';
import 'package:remote_base/remote_base.dart'; // Adjust import path if your package name differs

void main() async {
  WidgetsFlutterBinding.ensureInitialized(); // Required if main is async

  await RemoteBase.init(
    apiKey: 'YOUR_API_KEY',
    apiUrl: 'https://your.api.endpoint.com/basepath',
    // Optionally, specify paths to pre-cache:
    // pathsToPrecache: ['/content/onboarding', '/content/faq'],
  );

  runApp(MyApp());
}

Usage

To display the popup from anywhere in your app where you have a BuildContext (e.g., from a button press):

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

class MyScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('My App')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // Show the popup, loading content from 'feature/details'
            // The full URL loaded might be:
            // https://your.api.endpoint.com/basepath/feature/details?apiKey=YOUR_API_KEY
            RemoteBase.showPopup(context, path: 'feature/details');
          },
          child: Text('Show Remote Content'),
        ),
      ),
    );
  }
}

Controlling the Popup

  • Show Directly: RemoteBase.showPopup(context, path: 'your_path')
  • Hide: RemoteBase.hidePopup() (called automatically on dismiss or close button)
  • Check Visibility: RemoteBase.isVisible (returns a boolean)

The Placement API allows you to pre-define popup configurations (a path and an optional onDismissed callback) and then trigger them by name. This is useful for organizing different popup scenarios in your app, similar to how Superwall handles placements.

1. Register a Placement:

Call this early in your app, perhaps after RemoteBase.init().

await RemoteBase.registerPlacement(
  'UpgradeScreen',
  path: 'content/upgrade-prompt',
  onDismissed: () {
    print('UpgradeScreen placement popup was dismissed.');
    // You could trigger analytics, or check a purchase status here.
  },
);

await RemoteBase.registerPlacement(
  'FeatureAnnouncement',
  path: 'announcements/new-feature-x',
  // No onDismissed callback needed for this one
);

2. Show a Placement:

When you want to display the popup associated with a registered placement:

// Somewhere in your UI code, e.g., button press:
RemoteBase.showPlacement(context, 'UpgradeScreen');

Or for another placement:

RemoteBase.showPlacement(context, 'FeatureAnnouncement');

The onDismissed callback you provided during registration will be invoked when the popup for that specific placement is hidden (either by user action or by calling RemoteBase.hidePopup()).

Additional Information

  • Caching Behavior: The pre-caching feature initiates HTTP GET requests for the specified paths. Actual caching effectiveness depends on your server's HTTP caching headers (e.g., Cache-Control, ETag). The webview_flutter also has its own caching mechanisms.
  • Customization: The current implementation provides a good base. You can further customize the appearance of the shimmer effect, popup dimensions, error messages, and more by modifying the lib/remote_base.dart file.
  • Backend Interaction: This package is client-focused. Your backend (e.g., remotebase/src/index.ts) should be set up to serve content at the paths used with showPopup and pathsToPrecache, and handle the apiKey query parameter if needed for authentication or content serving logic.

Contributing

Contributions are welcome! If you have suggestions or improvements, please feel free to fork the repository and submit a pull request, or open an issue.

Filing Issues

If you encounter any bugs or have feature requests, please file an issue on the project's issue tracker. Provide as much detail as possible, including steps to reproduce, Flutter version, and package version.

Libraries

remote_base