flutter_communication_avatar

pub package License: MIT Flutter

A production-ready Flutter plugin for displaying native communication push and local notifications with user avatars on iOS and Android.

Unlike standard notifications, flutter_communication_avatar leverages native system APIs to render user avatars prominently on the LEFT side of notifications (overlaying the app icon on iOS 15+ and formatted as native MessagingStyle on Android), providing a modern messaging experience similar to iMessage, WhatsApp, and Telegram.

โœจ Features

  • iOS Communication Notifications: Full support for INSendMessageIntent, INPerson, INInteraction, and iOS 15+ notification content updates. Avatar renders on the LEFT overlaying the app icon.
  • Android MessagingStyle: Full support for NotificationCompat.MessagingStyle + Person + IconCompat.createWithBitmap. Avatar renders on the LEFT side of notifications.
  • Async Avatar Downloading: Downloads avatar images asynchronously over HTTP/HTTPS with timeout and caching.
  • Automatic Fallback Avatar: If the avatar URL fails, times out, or is omitted, automatically generates a clean circular initial letter badge avatar or uses a custom Flutter asset.
  • UNNotificationServiceExtension Support: Includes a Swift extension helper (CommunicationAvatarExtensionHelper) for formatting remote push notifications (FCM / APNs) on iOS.
  • Automated CLI Setup: CLI tool (bin/setup_ios.dart) to inspect and update iOS project settings automatically.
  • Permission & Channel Management: Built-in permission request/check API and Android Notification Channel builder.

๐Ÿ“ธ Platform Display Matrix

Platform Native API Avatar Location
iOS 15+ INSendMessageIntent + INPerson + UNNotificationContent LEFT (overlaying app icon)
Android 8.0+ NotificationCompat.MessagingStyle + Person LEFT (native messaging avatar)

๐Ÿš€ Getting Started

Add flutter_communication_avatar to your pubspec.yaml:

dependencies:
  flutter_communication_avatar: ^1.0.0

Run flutter pub get to install.

๐Ÿ“ฑ Platform Setup

iOS Setup

Run the included setup script inside your Flutter project directory:

# Check current iOS configuration status:
dart run flutter_communication_avatar:setup_ios --check

# Automatically update Info.plist with INSendMessageIntent:
dart run flutter_communication_avatar:setup_ios --apply

2. Manual Info.plist Setup

Add INSendMessageIntent to NSUserActivityTypes in your ios/Runner/Info.plist:

<key>NSUserActivityTypes</key>
<array>
    <string>INSendMessageIntent</string>
</array>

3. Remote Push Notifications (Notification Service Extension)

To display avatars for remote push notifications when your app is in the background or killed on iOS:

  1. Open ios/Runner.xcworkspace in Xcode.
  2. Go to File -> New -> Target, select Notification Service Extension, and name it NotificationServiceExtension.
  3. In NotificationService.swift, use the plugin's Swift helper:
import UserNotifications
import Intents
import flutter_communication_avatar

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.contentHandler = contentHandler

        // Automatically format remote notification payload into INSendMessageIntent with avatar
        CommunicationAvatarExtensionHelper.processNotificationRequest(request) { finalContent in
            contentHandler(finalContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler {
            contentHandler(UNMutableNotificationContent())
        }
    }
}

Android Setup

On Android 13+ (API level 33+), ensure you request notification permissions at runtime using the plugin API.

No complex AndroidManifest changes are required. Notification channels are created automatically or via createNotificationChannel().

๐Ÿ’ป Code Examples

1. Basic Communication Notification

import 'package:flutter_communication_avatar/flutter_communication_avatar.dart';

Future<void> sendChatNotification() async {
  // 1. Request notification permissions
  final granted = await FlutterCommunicationAvatar.instance.requestPermissions();
  if (!granted) return;

  // 2. Define sender person with avatar URL
  final sender = CommunicationPerson(
    id: 'user_alice_123',
    name: 'Alice Smith',
    avatarUrl: 'https://example.com/avatars/alice.png',
  );

  // 3. Construct notification
  final notification = CommunicationNotification(
    id: 1001,
    body: 'Hey! Are we still meeting for coffee at 3 PM?',
    sender: sender,
    conversationId: 'chat_alice_123',
  );

  // 4. Post notification
  await FlutterCommunicationAvatar.instance.showNotification(notification);
}

2. Group Conversation Notification

final sender = CommunicationPerson(
  id: 'user_bob_456',
  name: 'Bob Johnson',
  avatarUrl: 'https://example.com/avatars/bob.png',
);

final notification = CommunicationNotification(
  id: 1002,
  title: 'Project Alpha Team',
  body: 'Pull request #42 has been merged into main!',
  sender: sender,
  conversationId: 'group_project_alpha',
  conversationTitle: 'Project Alpha Team',
  isGroupConversation: true,
);

await FlutterCommunicationAvatar.instance.showNotification(notification);

3. Fallback Avatar (Initial Letter Badge)

If no avatarUrl is provided or if network download fails, a letter avatar is automatically generated:

final sender = CommunicationPerson(
  id: 'user_charlie_789',
  name: 'Charlie Brown',
  // avatarUrl is omitted or null
);

final notification = CommunicationNotification(
  id: 1003,
  body: 'Automatic letter badge fallback avatar test!',
  sender: sender,
  conversationId: 'chat_charlie_789',
);

await FlutterCommunicationAvatar.instance.showNotification(notification);

4. Managing Notification Channels (Android)

await FlutterCommunicationAvatar.instance.createNotificationChannel(
  const NotificationChannelConfig(
    id: 'custom_chat_channel',
    name: 'Direct Messages',
    description: 'High priority notifications for direct chat messages.',
    importance: 4, // High importance for heads-up banner
  ),
);

5. Canceling Notifications

// Cancel specific notification by ID
await FlutterCommunicationAvatar.instance.cancelNotification(1001);

// Cancel all active notifications
await FlutterCommunicationAvatar.instance.cancelAllNotifications();

๐Ÿ› ๏ธ CLI Setup Tool (setup_ios)

The plugin includes a CLI utility executable for Flutter projects:

# Display CLI usage
dart run flutter_communication_avatar:setup_ios --help

# Check iOS entitlement status
dart run flutter_communication_avatar:setup_ios --check

# Apply Info.plist updates automatically
dart run flutter_communication_avatar:setup_ios --apply

# Generate NotificationService.swift template
dart run flutter_communication_avatar:setup_ios --extension

๐Ÿ“– API Reference

CommunicationPerson

Property Type Description
id String Unique sender user identifier.
name String Display name of the person.
avatarUrl String? Optional HTTP/HTTPS image URL for the avatar.
fallbackAsset String? Optional local Flutter asset path fallback.
isBot bool Whether person is an automated bot.
isImportant bool High-priority person flag.

CommunicationNotification

Property Type Description
id int Unique notification integer ID.
body String Message content text.
sender CommunicationPerson Sender details.
conversationId String Room / thread identifier.
conversationTitle String? Optional group chat title.
isGroupConversation bool Flag for group conversations.
channelId String Android notification channel ID.
sound String? Notification sound ("default" or custom).

๐Ÿ‘จโ€๐Ÿ’ป Author & License

Developed and maintained by Hรนng Nguyแป…n.

Distributed under the MIT License. See LICENSE for details.

Libraries

flutter_communication_avatar
flutter_communication_avatar_method_channel
flutter_communication_avatar_platform_interface