entrig 0.0.1-beta

Entrig Plugin

Entrig

No-code Push Notifications for Supabase

Send push notifications to your Flutter app, triggered by database events.

Minimum Requirements

Flutter & Dart

• Flutter: 3.3.0 or higher
• Dart: 3.8.1 or higher

Platform Requirements

iOS

• Minimum iOS version: 13.0

Android

• Minimum SDK: 23

---

Prerequisites

1. Entrig Account

• Sign up at entrig.com

2. Connect Supabase Project

• Create a project at supabase.com
• Note your project URL and anon key

3. Push Notification Services

Configure platform-specific push services:

Firebase Cloud Messaging (FCM) - For Android

• Create a Firebase project at console.firebase.google.com
• Add your Android app to the project
• Download google-services.json (Project Settings -> General -> Your apps -> SDK setup and configuration)
• Download Service Account JSON file (Project Settings -> Service Accounts -> Firebase Admin SDK -> Generate new private key)
• Upload both google-services.json and Service Account JSON to Entrig dashboard

Apple Push Notification Service (APNs) - For iOS

• Enroll in Apple Developer Program
• Create an APNs Authentication Key in Apple Developer portal (Certificates, Identifiers & Profiles -> Keys -> Create a key -> Enable Apple Push Notifications service)
• Download the .p8 key file
• Upload the .p8 file to Entrig dashboard along with your Team ID (found in Apple Developer Membership) and Key ID (shown when you create the key)

---

Installation

Add Entrig to your pubspec.yaml:

dependencies:
  entrig: ^0.0.1
  supabase_flutter: ^2.10.3  # Required peer dependency

Run:

flutter pub get

---

Platform Setup

Android

No setup required for Android. We'll take care of it.

iOS

1. Enable Push Notifications capability

   In Xcode:

   • Open ios/Runner.xcworkspace
   • Select Runner target → Signing & Capabilities
   • Click + Capability → Push Notifications
   • Click + Capability → Background Modes -> Enable Remote notifications and Background fetch

2. Update AppDelegate.swift

   Choose one of the following options:

   Option A: Automatic setup (Recommended)

   Run this command in your project root:

   dart run entrig:setup ios
   

   Option B: Manual setup

   Update your ios/Runner/AppDelegate.swift file:

    import Flutter
    import UIKit
    import entrig
    import UserNotifications
   
    @main
    @objc class AppDelegate: FlutterAppDelegate {
        override func application(
            _ application: UIApplication,
            didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
        ) -> Bool {
            GeneratedPluginRegistrant.register(with: self)
               
            // Setup Entrig notification handling
            UNUserNotificationCenter.current().delegate = self
            EntrigPlugin.checkLaunchNotification(launchOptions)
               
            return super.application(application, didFinishLaunchingWithOptions: launchOptions)
        }
           
        override func application(_ application: UIApplication,
                                didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
            EntrigPlugin.didRegisterForRemoteNotifications(deviceToken: deviceToken)
        }
           
        override func application(_ application: UIApplication,
                                didFailToRegisterForRemoteNotificationsWithError error: Error) {
            EntrigPlugin.didFailToRegisterForRemoteNotifications(error: error)
        }
           
        // MARK: - UNUserNotificationCenterDelegate
        override func userNotificationCenter(_ center: UNUserNotificationCenter,
                                            willPresent notification: UNNotification,
                                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
            EntrigPlugin.willPresentNotification(notification)
            completionHandler([])
        }
           
        override func userNotificationCenter(_ center: UNUserNotificationCenter,
                                            didReceive response: UNNotificationResponse,
                                            withCompletionHandler completionHandler: @escaping () -> Void) {
            EntrigPlugin.didReceiveNotification(response)
            completionHandler()
        }
    }
   

---

Usage

Initialize

Initialize Entrig and Supabase in your main():

import 'package:flutter/material.dart';
import 'package:entrig/entrig.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize Supabase
  await Supabase.initialize(
    url: 'YOUR_SUPABASE_URL',
    anonKey: 'YOUR_SUPABASE_ANON_KEY',
  );

  // Initialize Entrig (Get API Key from Entrig Settings)
  await Entrig.init(apiKey: 'YOUR_ENTRIG_API_KEY');

  runApp(MyApp());
}

Register Device

Register the current device to receive notifications for a user:

final userId = Supabase.instance.client.auth.currentUser?.id;
if (userId != null) {
  // userId is required to find the user when sending push notifications
  await Entrig.register(userId: userId);
}

Note: register() automatically handles permission requests, so you don't need to call requestPermission() separately in most cases.

Request Permission (Optional)

For custom permission handling, you can manually request notification permissions:

final granted = await Entrig.requestPermission();
if (granted) {
  print('Notification permission granted');
}

Listen to Notifications

Foreground notifications (when app is open):

Entrig.foregroundNotifications.listen((event) {
  print('Title: ${event.title}');
  print('Body: ${event.body}');
  print('Data: ${event.data}');
});

Notification tap (when user taps a notification when app is not in foreground):

Entrig.onNotificationOpened.listen((event) {
  print('User tapped notification');
  print('Data: ${event.data}');
  // Navigate to a specific screen based on event.data
});

Unregister Device

When user logs out or no longer wants notifications:

await Entrig.unregister();

---

API Reference

Methods

Entrig.init({required String apiKey})

• Initialize Entrig with your API key (get API key from settings in Entrig dashboard)
• Call once during app startup

Entrig.register({required String userId})

• Register device for a specific user
• Automatically handles permission requests
• Returns Future<String?> - device token
• Call after user logs in

Entrig.requestPermission()

• Manually request notification permissions (optional)
• Returns Future<bool> - true if granted
• Use only for custom permission handling flows

Entrig.unregister()

• Unregister the current device
• Returns Future<bool> - true if successful
• Call when user logs out

Streams

Entrig.foregroundNotifications

• Stream of notifications received while app is in foreground
• Emits NotificationEvent objects

Entrig.onNotificationOpened

• Stream of notification tap events
• Emits NotificationEvent objects

NotificationEvent

class NotificationEvent {
  final String? title;
  final String? body;
  final Map<String, dynamic>? data;
}

---

Creating Notifications

Create notification triggers in the Entrig dashboard at entrig.com/dashboard. When you create a notification, Entrig automatically sets up the necessary database function and trigger in your Supabase project.

Notification Configuration

Step 1: Configure Trigger

1. Select Table: Choose the table where the event occurs (e.g., messages, orders)

2. Select Event: Choose when to trigger the notification:

   • INSERT - When new rows are created
   • UPDATE - When existing rows are modified
   • DELETE - When rows are deleted

3. Select User Identifier: Choose how to identify recipients:

   Single User Mode:

   • Select a field that contains the user ID (e.g., user_id, recipient_id)
   • Supports foreign key navigation (e.g., order.customer.user_id)

   Multi-User Mode (Join Table):

   • Use when sending to multiple users from one database event
   • Configure:
     • Lookup Field: Field linking to the join table (e.g., room_id)
     • Join Table: Table containing recipient records (e.g., room_members)
     • Matching Field: Field in join table matching lookup field (e.g., room_id)
     • User ID Field: Field containing user IDs (e.g., user_id)

4. Event Conditions (Optional): Filter when notifications send based on event data

   • Example: Only send when status = 'completed'
   • Supports multiple conditions with AND/OR logic

5. Recipient Filters (Optional, Multi-User only): Filter which recipients receive the notification

   • Example: Only send to users where role = 'admin'

Step 2: Compose Notification

1. Notification Type (Optional): Custom identifier for client-side handling

   • Example: new_message, order_update, friend_request
   • Use in your app to handle different notification types

2. Payload Data (Optional): Select fields to include as placeholders

   • Click field names to insert as {{table.column}} placeholders
   • Example: {{messages.content}}, {{orders.total}}

3. Title & Body: Write notification text with placeholders

   • Example Title: New message from {{messages.sender_name}}
   • Example Body: {{messages.content}}

What Happens Behind the Scenes

When you create a notification, Entrig automatically:

1. Enables pg_net extension in your Supabase project
2. Creates a PostgreSQL function to send HTTP requests to Entrig
3. Sets up a database trigger on your selected table
4. Configures webhook endpoint for your notification

No manual SQL or backend code required!

Example Use Cases

Single User Notification:

• Table: orders, Event: INSERT
• User ID: customer_id
• Title: Order Confirmed!
• Body: Your order #{{orders.id}} has been received

Multi-User Notification (Group Chat):

• Table: messages, Event: INSERT
• Lookup Field: room_id
• Join Table: room_members
• Matching Field in Join Table: room_id
• User ID: user_id
• Title: New message in {{messages.room_name}}
• Body: {{messages.sender_name}}: {{messages.content}}

---

Support

• Email: [e-mail]

---

License

MIT License