universal_share 1.0.1

Premium, zero-configuration Flutter sharing plugin for WhatsApp, Instagram, Facebook, Telegram, SMS, and HTML Emails with multiple attachments.

Universal Share (universal_share)

A premium, unified, and zero-configuration Flutter plugin for direct and general sharing across Android and iOS.

Forget complex setups, tedious XML edits, and confusing native APIs. universal_share is designed to work out-of-the-box with zero developer friction. Whether you want to open a rich email composer, send a WhatsApp message directly, or share beautiful stickers to Instagram Stories, this plugin handles everything under a single, elegant Dart API.

---

💎 Why Universal Share?

Most sharing plugins require you to manually configure Android's package visibility (AndroidManifest.xml) or iOS's URL schemes (Info.plist), leading to endless build issues and runtime crashes. universal_share solves all of this automatically.

• ⚡ Zero Host App Manifest Configuration: Queries are automatically merged at compile time.

• 🛡️ Secure File Sharing Built-In: Custom FileProvider is pre-registered with unique dynamic authorities to prevent collisions.

• 📱 iOS 13+ & iPad Safe: Uses the latest scene-based window APIs and handles iPad popovers seamlessly without crashes.

• 🎨 Clean & Modern Dart API: Single static class (UniversalShare) with typed methods.

• 🎛️ Fully Customizable Combos: Share only text, only files/media, or text + files/media dynamically without boilerplate or empty strings!

---

🚀 Key Features & Supported Platforms

Platform	General Share	Direct WhatsApp	Instagram Stories	Instagram Feed	Facebook Stories	Facebook Feed	Messenger	Telegram	SMS	Rich Email
Android	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅ (HTML + Files)
iOS	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅ (HTML + Files)

---

🛠️ Deep Dive: Zero-Config Native Handling

Here is how the plugin natively resolves the most common platform-level hurdles:

1. Android 11+ Package Visibility (<queries>)

• The Problem: On Android 11 (API 30) and above, package visibility is restricted. If you try to query packages like com.instagram.android or com.whatsapp, the OS returns false (not installed) even if the app is physically present on the device.

• Our Solution: The plugin includes a pre-configured AndroidManifest.xml that defines all necessary queries. When you compile your app, Gradle's Manifest Merger automatically copies these definitions into your final app manifest. No manual edits required!

2. Android Secure File Provider (content://)

• The Problem: Sharing files directly on Android using raw file:// URIs throws a FileUriExposedException on modern versions. Setting up a custom FileProvider is complex and often causes collision errors if multiple plugins register the same provider authority.

• Our Solution: The plugin registers its own custom provider: UniversalFileProvider with a dynamic authority scheme (${applicationId}.universal_share.provider). It scales dynamically with your application package ID and handles the secure sharing of internal documents, PDFs, or photos effortlessly.

3. iOS Scene-Based Top View Controller & iPad Crash Prevention

• The Problem: Old plugins look up UIApplication.shared.keyWindow to present sheets, which is deprecated in iOS 13+ and fails on modern multi-window devices. Additionally, presenting a share sheet on iPads without popover anchor points causes an immediate crash.

• Our Solution: The plugin uses a scene-compatible algorithm to dynamically resolve the correct active UIWindow and presenting view controller. When running on an iPad, it safely falls back to a centered popover transition anchor so your app never crashes.

---

⚠️ Platform Limitations & Policy Rules

Meta (Facebook/Instagram) and OS policies enforce strict privacy controls. To help you set expectations for your users, here is how the plugin operates within these boundaries:

1. Instagram Direct Chat deep-linking: Deep-linking directly into a specific user's chat screen with pre-filled content is blocked by Meta. UniversalShare.shareToInstagramDirect opens Instagram's modern sharing hub where the user can pick their destination chat or group.

2. Facebook Feed pre-filled text: The official Facebook app strictly blocks pre-filled custom message parameters (EXTRA_TEXT) in intents unless you use the heavy, login-based Facebook SDK. When using shareToFacebookFeed, the user writes their post within Facebook's native editor window.

---

💻 Easy Code Examples

All UniversalShare APIs are fully customizable. You can pass any combination of parameters: text only, file only, or both text + file!

1. General System Share Sheet

Share text, multiple files, or a mix of both using the native system chooser.

import 'package:universal_share/universal_share.dart';

// Combo 1: Text only
await UniversalShare.shareGeneral(
  text: 'Hey! Check out this awesome sharing plugin.',
);

// Combo 2: Files only
await UniversalShare.shareGeneral(
  filePaths: ['/absolute/path/to/invoice.pdf', '/absolute/path/to/photo.png'],
);

// Combo 3: Text + Files
await UniversalShare.shareGeneral(
  text: 'Check out these files!',
  filePaths: ['/absolute/path/to/my_image.png'],
);

2. Direct WhatsApp

Open WhatsApp (or WhatsApp Business automatically if regular WhatsApp is missing) directly to a target contact's chat, or launch the contact selector.

// Combo 1: Chat Message only
await UniversalShare.shareToWhatsApp(
  phoneNumber: '[phone]', // Target contact with country code
  text: 'Hello from Flutter!',
);

// Combo 2: File Sharing only (opens WhatsApp share selector)
await UniversalShare.shareToWhatsApp(
  filePath: '/path/to/image.jpg',
);

// Combo 3: Text + File Caption (deep-links/copies text to clipboard)
await UniversalShare.shareToWhatsApp(
  text: 'Check out this awesome photo!',
  filePath: '/path/to/image.jpg',
);

3. Rich Email Composer

Compose native rich emails with custom HTML bodies, multiple document attachments, and prefilled recipients.

await UniversalShare.shareToEmail(
  recipients: ['[e-mail]'],
  subject: 'Monthly Business Report',
  body: '<h1>Hello Team</h1><p>Please find the requested PDF and PNG attachments below.</p>',
  attachmentPaths: ['/path/to/report.pdf', '/path/to/chart.png'], // Fully Optional!
  isHtml: true,
);

4. Direct Instagram Stories

Send customized sticker assets, overlay text stickers, or backgrounds directly to the Instagram Story editor.

// Share overlay text sticker dynamically generated as a beautiful transparent PNG on native side
await UniversalShare.shareToInstagramStory(
  text: 'Overlay Story Text Sticker!',
  topBackgroundColor: '#FF512F',
  bottomBackgroundColor: '#DD2476',
  facebookAppId: 'your_meta_app_id', // Required by Meta on iOS
);

// Share image background + sticker asset
await UniversalShare.shareToInstagramStory(
  stickerAssetPath: '/path/to/sticker_logo.png',
  backgroundAssetPath: '/path/to/gradient_bg.png',
  facebookAppId: 'your_meta_app_id',
);

5. Instagram Direct DM

Share text, attachments, or text+attachment combos directly to Instagram Direct messages.

// Combo 1: Text message directly to Direct DM
await UniversalShare.shareToInstagramDirect(
  text: 'Hey, let\'s chat here!',
);

// Combo 2: File attachment only
await UniversalShare.shareToInstagramDirect(
  filePath: '/path/to/invoice.pdf',
);

// Combo 3: File + Message Caption
await UniversalShare.shareToInstagramDirect(
  text: 'Here is the image you requested.',
  filePath: '/path/to/image.jpg',
);

6. Telegram Composition

Share text, files, or text+file combos directly to Telegram or Telegram X.

// Combo 1: Text message directly to Telegram
await UniversalShare.shareToTelegram(
  text: 'Join our Telegram channel: https://t.me/flutter',
);

// Combo 2: File only
await UniversalShare.shareToTelegram(
  filePath: '/path/to/doc.pdf',
);

// Combo 3: File + Caption Text
await UniversalShare.shareToTelegram(
  text: 'Here is the project outline PDF.',
  filePath: '/path/to/doc.pdf',
);

7. SMS Composition

Send direct SMS to multiple recipients.

await UniversalShare.shareToSMS(
  recipients: ['[phone]', '[phone]'],
  message: 'Hey, I am testing the new SMS feature!',
);

---

📝 API Reference

Method Name	Parameters	Return Type	Description
shareGeneral	String? text, List<String>? filePaths	Future<bool>	Opens the general native system share sheet.
shareToWhatsApp	String? text, String? phoneNumber, String? filePath	Future<bool>	Directly deep-links to WhatsApp/WhatsApp Business.
shareToInstagramStory	String? stickerAssetPath, String? backgroundAssetPath, String? topBackgroundColor, String? bottomBackgroundColor, String? facebookAppId, String? text	Future<bool>	Publishes stickers/backgrounds directly to Instagram Stories.
shareToInstagramFeed	required String filePath	Future<bool>	Directs to Instagram Feed post editor.
shareToInstagramDirect	String? text, String? filePath	Future<bool>	Opens Instagram's Direct Messages hub with optional text and file attachment.
shareToFacebookStory	String? stickerAssetPath, String? backgroundAssetPath, String? topBackgroundColor, String? bottomBackgroundColor, required String facebookAppId, String? text	Future<bool>	Publishes stickers/backgrounds directly to Facebook Stories.
shareToFacebookFeed	String? text, String? imagePath	Future<bool>	Directs to Facebook Feed composer.
shareToFacebookMessenger	String? text	Future<bool>	Opens Messenger app.
shareToTelegram	String? text, String? filePath	Future<bool>	Opens Telegram/Telegram X with optional text or file.
shareToSMS	required List<String> recipients, String? message	Future<bool>	Opens native SMS sheet with recipients and message text.
shareToEmail	required List<String> recipients, String? subject, String? body, List<String>? attachmentPaths, bool isHtml	Future<bool>	Opens rich Email composer with HTML and file attachments.

---

🔒 License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

---

🐛 Bug Reports & Support

If you encounter any issues, find a bug, or want to suggest a new feature, feel free to report it at: 👉 Yash Dodani - Bug Reports & Support

---

Made with ❤️ by Yash Dodani

If this package saved you time, please ⭐ it on pub.dev!