flutter_pushed_messaging 1.6.5

A Flutter plugin for use Multipushed messaging system.

🚀 Плагин Pushed Messaging для Flutter

Flutter плагин для интеграции с Multipushed Messaging

🌐 Официальный сайт • 📚 Документация

---

🚀 Начало работы

📦 Установка

Добавьте в ваш pubspec.yaml:

dependencies:
  flutter_pushed_messaging: ^1.6.5

Затем выполните:

flutter pub get

📥 Импорт

import 'package:flutter_pushed_messaging/flutter_pushed_messaging.dart';

---

📚 Содержание

• 🚀 Начало работы
• 📱 Настройка iOS
  • 📦 Базовая настройка iOS
  • 🔧 Notification Service Extension
  • 🔐 Настройка Keychain Sharing
• 🤖 Настройка Android
  • 🔥 Настройка Firebase (FCM)
  • 📱 Настройка Huawei (HMS)
  • 🏪 Настройка RuStore
• 💡 Реализация
• 🐛 Решение проблем
• ❓ Часто задаваемые вопросы

---

🚀 Начало работы

📦 Установка

Добавьте в ваш pubspec.yaml:

dependencies:
  flutter_pushed_messaging: ^1.6.5

Затем выполните:

flutter pub get

📥 Импорт

import 'package:flutter_pushed_messaging/flutter_pushed_messaging.dart';

---

📱 Настройка iOS

📦 Базовая настройка iOS

⚠️ Предварительные условия: Убедитесь, что ваше iOS приложение правильно настроено для push-уведомлений

🔧 Необходимые возможности

1. Откройте ваш iOS проект в Xcode
2. Добавьте возможность Push Notifications:
   • Выберите ваш target → Signing & Capabilities
   • Нажмите + Capability → Push Notifications
3. Добавьте возможность Background Modes:
   • Нажмите + Capability → Background Modes
   • Включите Remote notifications

📝 Настройка AppDelegate

Добавьте это в ваш AppDelegate.swift (или AppDelegate.m) в метод didFinishLaunchingWithOptions:

if #available(iOS 10.0, *) {
  UNUserNotificationCenter.current().delegate = self as? UNUserNotificationCenterDelegate
}

🎯 Следующий шаг: Настройка iOS Extension 👇

---

🔧 Настройка Notification Service Extension

🚀 Зачем это нужно? Notification Service Extension обеспечивает расширенные возможности push-уведомлений, такие как богатый контент, отслеживание доставки и фоновая обработка.

📱 Создание Extension

Шаг 1: Создание Extension Target

1. 🎯 В Xcode: File → New → Target → Notification Service Extension
2. 📝 Product Name: extension (или ваше предпочитаемое имя)
3. ✅ Нажмите: Activate
4. 🔄 Язык: Swift (рекомендуется)

Шаг 2: Настройка Build Phases

⚠️ Критический шаг: Это обеспечивает правильный порядок сборки

1. 🎯 Выберите ваш основной target (Runner)
2. 📂 Перейдите: на вкладку Build Phases
3. 🔄 Перетащите: Embed Foundation Extensions НАД Run Script

Шаг 3: Конфигурация сборки

# Выполните это в корне вашего проекта
flutter build ios --config-only

🛠️ Настройка Podfile

Редактируйте ios/Podfile

Найдите эту строку:

flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

Добавьте сразу после:

target 'extension' do  # ← Замените 'extension' на фактическое имя вашего extension
  inherit! :search_paths
end 

Обновите зависимости

cd ios
pod update

📝 Реализация NotificationService.swift

Замените содержимое вашего NotificationService.swift на:

import UserNotifications
import flutter_pushed_messaging

class NotificationService: UNNotificationServiceExtension {

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

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
        
        // 🚀 Эта магическая строка обеспечивает расширенные возможности
        FlutterPushedMessagingPlugin.confirmExtension(userInfo: request.content.userInfo)
        
        if let bestAttemptContent = bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
    
    override func serviceExtensionTimeWillExpire() {
        // Вызывается непосредственно перед завершением extension системой.
        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

---

🔐 Настройка Keychain Sharing

⚠️ КРИТИЧЕСКИ ВАЖНО: Без этой настройки Extension не будет работать!

🎯 Настройка основного приложения

1. 📱 Выберите ваш основной app target (Runner)
2. 🔧 Перейдите в: Signing & Capabilities
3. ➕ Добавьте: Keychain Sharing capability
4. 🔑 Добавьте keychain group: $(AppIdentifierPrefix)com.yourcompany.yourapp.shared

🔧 Настройка Extension

1. 🎯 Выберите ваш extension target
2. 🔧 Перейдите в: Signing & Capabilities
3. ➕ Добавьте: Keychain Sharing capability
4. 🔑 Добавьте ТУ ЖЕ keychain group: $(AppIdentifierPrefix)com.yourcompany.yourapp.shared

💡 Совет профи: Замените com.yourcompany.yourapp на ваш фактический bundle identifier

---

🤖 Настройка Android

🔥 Настройка Firebase (FCM)

📱 Для приложений Google Play Store и большинства Android устройств

Шаг 1: Зависимости в корневом build.gradle

Добавьте в android/build.gradle:

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.3.15'
        classpath 'com.google.firebase:firebase-crashlytics-gradle:2.8.1'
        // ... другие зависимости
    }
}

Шаг 2: Добавьте файл конфигурации

1. 📥 Скачайте google-services.json из Firebase Console
2. 📂 Поместите в: папку android/app/

Шаг 3: Конфигурация на уровне приложения

Добавьте в android/app/build.gradle:

apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.google.firebase.crashlytics'

---

📱 Настройка Huawei (HMS)

📱 Для устройств Huawei и AppGallery

Шаг 1: Конфигурация корневого build.gradle

Добавьте в android/build.gradle:

buildscript {
    repositories {
        maven { url 'https://developer.huawei.com/repo/' }
        // ... другие репозитории
    }
    dependencies {
        classpath 'com.huawei.agconnect:agcp:1.5.2.300'
        // ... другие зависимости
    }
}

allprojects {
    repositories {
        maven { url 'https://developer.huawei.com/repo/' }
        // ... другие репозитории
    }
}

Шаг 2: Добавьте файл конфигурации

1. 📥 Скачайте agconnect-services.json из Huawei Developer Console
2. 📂 Поместите в: папку android/app/

Шаг 3: Конфигурация на уровне приложения

Добавьте в android/app/build.gradle:

dependencies {
    implementation 'com.huawei.agconnect:agconnect-core:1.5.2.300'
    // ... другие зависимости
}

apply plugin: 'com.huawei.agconnect'

---

🏪 Настройка RuStore

🇷🇺 Для RuStore (российский магазин приложений)

Добавьте в android/app/src/main/AndroidManifest.xml:

<application>
    <!-- ... другие настройки ... -->
    
    <meta-data
        android:name="ru.rustore.sdk.pushclient.project_id"
        android:value="Ваш RuStore project ID" />
        
</application>

---

💡 Реализация

🚀 Обработчик фоновых сообщений

import 'package:flutter_pushed_messaging/flutter_pushed_messaging.dart';

// 🔄 Этот обработчик работает даже когда ваше приложение закрыто
@pragma('vm:entry-point')
Future<void> backgroundMessage(Map<dynamic, dynamic> message) async {
    print("📱 Получено фоновое сообщение: $message");
    
    // 💡 Добавьте вашу логику здесь
    // - Сохранение в локальную базу данных
    // - Показ кастомного уведомления
    // - Обновление значка приложения
}

🎯 Настройка основного приложения

void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    
    // 🚀 Инициализация плагина
    await FlutterPushedMessaging.init(
        backgroundMessage,
        notificationChannel: "messages",     // 🤖 Только для Android
        askPermissions: true,               // 📱 Автозапрос разрешений
        loggerEnabled: false,               // 🐛 Включите для отладки
        applicationId: "YOUR_APP_ID",       // 🔑 Кастомный идентификатор (опционально)
    );
    
    // 🔑 Получение уникального токена клиента
    print("🔑 Токен клиента: ${FlutterPushedMessaging.token}");
    
    runApp(const MyApp());
}

📱 Прослушивание сообщений

class _MyAppState extends State<MyApp> {
    @override
    void initState() {
        super.initState();
        _setupMessageListeners();
    }
    
    void _setupMessageListeners() {
        // 📥 Сообщения на переднем плане
        FlutterPushedMessaging.onMessage().listen((message) {
            print("📱 Сообщение на переднем плане: $message");
            
            // 💡 Обработка сообщения
            _showInAppNotification(message);
        });
        
        // 📊 Статус соединения
        FlutterPushedMessaging.onStatus().listen((status) {
            print("📡 Статус: $status");
            
            switch (status) {
                case ServiceStatus.active:
                    print("✅ Подключен и готов!");
                    break;
                case ServiceStatus.disconnected:
                    print("🔄 Переподключение...");
                    break;
                case ServiceStatus.notActive:
                    print("❌ Сервис неактивен");
                    break;
            }
        });
    }
}

🔐 Ручной запрос разрешений

// 📱 Запрос разрешений вручную при необходимости
await FlutterPushedMessaging.askPermissions(
    askNotificationPermission: true,    // 📱 Показ уведомлений
    askBackgroundPermission: true,      // 🤖 Фоновая работа Android
);

---

🐛 Решение проблем

📱 Проблемы iOS

🔴 Extension не работает

Проверьте эти распространенные проблемы:

1. ✅ Keychain Sharing - Оба target должны иметь одинаковую keychain group
2. ✅ Build Phases - Extension должен быть встроен перед Run Script
3. ✅ Podfile - Extension target должен быть правильно настроен
4. ✅ Подписание - Extension должен быть правильно подписан

Шаги отладки:

# Очистка и пересборка
flutter clean
cd ios && pod install
flutter build ios --config-only

🔴 Push-уведомления не появляются

Проверьте:

1. ✅ Capabilities - Push Notifications + Background Modes включены
2. ✅ APNs Сертификат - Действителен и не истек
3. ✅ Device Token - Приложение успешно зарегистрировано для push
4. ✅ Payload - Формат сообщения правильный

Тестирование:

# Проверка регистрации устройства
print("Токен: ${FlutterPushedMessaging.token}");

🤖 Проблемы Android

🔴 FCM не работает

Проверьте:

1. ✅ google-services.json - Файл существует в android/app/
2. ✅ Плагины - Оба плагина применены в app/build.gradle
3. ✅ Зависимости - Правильные версии в build.gradle
4. ✅ Имя пакета - Совпадает с Firebase проектом

Отладка:

# Проверка Firebase регистрации
flutter run --verbose
# Ищите логи "Firebase"

🔴 Фоновые сообщения не работают

Проверьте:

1. ✅ Оптимизация батареи - Приложение не ограничено
2. ✅ Автозапуск - Приложению разрешен автоматический запуск
3. ✅ Фоновый обработчик - Правильно зарегистрирован
4. ✅ Разрешения - Разрешение фоновой работы предоставлено

Тестирование:

// Добавьте логирование в фоновый обработчик
@pragma('vm:entry-point')
Future<void> backgroundMessage(Map<dynamic, dynamic> message) async {
    print("ФОНОВОЕ: $message"); // Это должно появиться в логах
}

🛠️ Общие проблемы

🔴 Плагин не инициализируется

Распространенные причины:

1. ❌ Отсутствует await - Убедитесь, что используете await для init()
2. ❌ Неправильное время - Инициализируйте после WidgetsFlutterBinding
3. ❌ Зависимости - Убедитесь, что все зависимости установлены

Правильная инициализация:

void main() async {
    WidgetsFlutterBinding.ensureInitialized(); // ← Важно!
    await FlutterPushedMessaging.init(
        backgroundMessage,
        notificationChannel: "messages",     // 🤖 Только для Android
        askPermissions: true,               // 📱 Автозапрос разрешений
        loggerEnabled: false,               // 🐛 Включите для отладки
        applicationId: "YOUR_APP_ID",       // 🔑 Кастомный идентификатор (опционально)
    ); // ← Await!
    runApp(MyApp());
}

---

❓ Часто задаваемые вопросы

📱 Могу ли я настроить внешний вид уведомлений?

Да! На Android вы можете настроить канал уведомлений. На iOS настройте payload в вашем NotificationService extension.

🔄 Как обрабатывать обновления приложения?

Токен остается действительным после обновлений приложения. Однако всегда тестируйте push-уведомления после крупных обновлений для обеспечения совместимости.

🌍 Работает ли это с несколькими языками?

Да! Плагин поддерживает интернационализацию. Настройте содержимое уведомлений на основе локали пользователя.

📊 Могу ли я отслеживать доставку сообщений?

Да! Используйте Extension на iOS и уведомления о доставке FCM на Android для отслеживания статуса доставки сообщений.

---

🎉 Всё готово!

Ваше приложение теперь готово для получения push-уведомления 🚀

Сделано с ❤️ командой Multipushed

---