/webf-native-plugins

name: webf-native-plugins
description: Install WebF native plugins to access platform capabilities like sharing, payment, camera, geolocation, and more. Use when building features that require native device APIs beyond standard web APIs.

WebF Native Plugins

When building WebF apps, you often need access to native platform capabilities like sharing content, accessing the camera, handling payments, or using geolocation. WebF provides **native plugins** that bridge JavaScript code with native platform APIs.

What Are Native Plugins?

Native plugins are packages that:

• **Provide native platform capabilities** (share, camera, payments, sensors, etc.)
• **Work across iOS, Android, macOS, and other platforms**
• **Use JavaScript APIs** in your code
• **Require both Flutter and npm package installation**
• **Bridge to native platform APIs** through Flutter

When to Use Native Plugins

Use native plugins when you need capabilities that aren't available in standard web APIs:

Use Native Plugins For:

• Sharing content to other apps
• Accessing device camera or photo gallery
• Processing payments
• Getting geolocation with native accuracy
• Push notifications
• Biometric authentication (Face ID, fingerprint)
• Device sensors (accelerometer, gyroscope)
• File system access beyond web storage
• Native calendar/contacts integration

Standard Web APIs Work Without Plugins:

• `fetch()` for HTTP requests
• `localStorage` for local storage
• Canvas 2D for graphics
• Geolocation API (basic)
• Media queries for responsive design

Finding Available Plugins

Before implementing a feature, **always check** if a pre-built native plugin exists:

1. Visit the official plugin registry: **https://openwebf.com/en/native-plugins** 2. Browse available plugins by category 3. Check the plugin documentation for installation steps

Installation Process

Every native plugin requires **TWO installations**:

1. **Flutter side** (in your Flutter host app) 2. **JavaScript side** (in your web project)

Step 1: Check Plugin Availability

Visit https://openwebf.com/en/native-plugins and search for the capability you need:

• Click on the plugin to view details
• Note the Flutter package name (e.g., `webf_share`)
• Note the npm package name (e.g., `@openwebf/webf-share`)

Step 2: Install Flutter Package

If you have access to the Flutter project hosting your WebF app:

1. Open the Flutter project's `pubspec.yaml` 2. Add the plugin dependency:

   dependencies:
     webf_share: ^1.0.0  # Replace with actual plugin name

3. Run `flutter pub get` 4. Register the plugin in your main Dart file:

   import 'package:webf/webf.dart';
   import 'package:webf_share/webf_share.dart';  // Import the plugin

   void main() {
     // Initialize WebFControllerManager
     WebFControllerManager.instance.initialize(WebFControllerManagerConfig(
       maxAliveInstances: 2,
       maxAttachedInstances: 1,
     ));

     // Register the native plugin module
     WebF.defineModule((context) => ShareModule(context));

     runApp(MyApp());
   }

Step 3: Install npm Package

In your JavaScript/TypeScript project:

# For the Share plugin example
npm install @openwebf/webf-share

# Or with yarn
yarn add @openwebf/webf-share

Step 4: Use in Your JavaScript Code

Import and use the plugin in your application:

import { WebFShare } from '@openwebf/webf-share';

// Use the plugin API
const success = await WebFShare.shareText({
  title: 'My App',
  text: 'Check out this amazing content!',
  url: 'https://example.com'
});

Available Plugins

Share Plugin (webf_share)

**Description**: Share content, text, and images through native platform sharing

**Capabilities**:

• Share text, URLs, and titles to other apps
• Share images using native sharing mechanisms
• Save screenshots to device storage
• Create preview images for temporary display

**Flutter Package**: `webf_share: ^1.0.0`

**npm Package**: `@openwebf/webf-share`

**Example Usage**:

import { WebFShare, ShareHelpers } from '@openwebf/webf-share';

// Share text content
await WebFShare.shareText({
  title: 'Article Title',
  text: 'Check out this article!',
  url: 'https://example.com/article'
});

// Share an image from canvas
const canvas = document.getElementById('myCanvas');
const imageData = ShareHelpers.canvasToArrayBuffer(canvas);
await WebFShare.shareImage(imageData);

// Save screenshot
await WebFShare.saveScreenshot(imageData);

**Storage Locations**:

• Android: Downloads folder (`/storage/emulated/0/Download/`)
• iOS: App documents directory (accessible via Files app)
• macOS: Application documents directory (accessible via Finder)

See the [Native Plugins Reference](./reference.md) for more available plugins.

Common Patterns

1. Feature Detection

Always check if a plugin is available before using it:

// Check if plugin is loaded
if (typeof WebFShare !== 'undefined') {
  await WebFShare.shareText({ text: 'Hello' });
} else {
  // Fallback or show message
  console.log('Share plugin not available');
}

2. Error Handling

Wrap plugin calls in try-catch blocks:

try {
  const success = await WebFShare.shareText({
    title: 'My App',
    text: 'Check this out!'
  });

  if (success) {
    console.log('Content shared successfully');
  }
} catch (error) {
  console.error('Failed to share:', error);
  // Show error message to user
}

3. TypeScript Type Safety

All plugins include TypeScript definitions:

import type { ShareTextOptions } from '@openwebf/webf-share';

const shareOptions: ShareTextOptions = {
  title: 'Article',
  text: 'Read this article',
  url: 'https://example.com'
};

await WebFShare.shareText(shareOptions);

Creating Custom Plugins

If you need capabilities not provided by existing plugins, you can create your own:

1. **Read the Plugin Development Guide**: https://openwebf.c