Katyayani Core Flutter SDK

Push notifications (standard, sticky, timer), in-app nudges, and event tracking for Flutter apps. Works on Android and iOS.

Installation

# pubspec.yaml
dependencies:
  katyayani_core:
    path: ../flutter_sdk  # or git URL / pub.dev

flutter pub get

Setup

1. Firebase Setup

2. Android — android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

<!-- For sticky notifications -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

3. Initialize SDK

import 'package:katyayani_core/katyayani_core.dart';

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

  await KatyayaniCore.init(KCConfig(
    siteId: 'nc_live_your_api_key',
    apiBase: 'https://api.yoursite.com',
    debug: true,
  ));

  runApp(MyApp());
}

Event Tracking

// Track custom event
KatyayaniCore.track('product_viewed', properties: {
  'product': 'Humic Acid',
  'price': 499,
});

// Identify user (after login)
KatyayaniCore.identify('user_123', traits: {
  'email': 'user@example.com',
  'name': 'Rajesh',
});

// Auto screen tracking — add observer to MaterialApp
MaterialApp(
  navigatorObservers: [KCNavigationObserver()],
);

// Manual screen view
KatyayaniCore.screenView('/products/humic-acid');

// Flush events immediately
KatyayaniCore.flushEvents();

// Logout
KatyayaniCore.resetIdentity();

Push Notifications

3 Types

Standard — Normal push, auto-dismisses

KatyayaniCore.showNotification(KCNotification(
  id: 'promo_1',
  title: 'New Offer!',
  body: 'Humic Acid at ₹399',
  actionUrl: '/products/humic-acid',
));

Sticky — Stays until user dismisses or takes action

KatyayaniCore.showNotification(KCNotification(
  id: 'order_tracking',
  title: '🛒 Order Processing',
  body: 'Your order is being packed',
  type: KCNotificationType.sticky,
  ongoing: true,  // Cannot swipe away (Android)
  buttons: [
    KCNotificationButton(id: 'track', label: 'Track Order', deepLink: '/orders/123'),
    KCNotificationButton(id: 'details', label: 'View Details'),
  ],
));

// Dismiss programmatically
KatyayaniCore.dismissStickyNotification('order_tracking');

Timer — Countdown with auto-action on expiry

KatyayaniCore.showNotification(KCNotification(
  id: 'flash_sale',
  title: '⏰ Flash Sale!',
  body: 'Flat 50% off fertilizers',
  type: KCNotificationType.timer,
  timerDurationSeconds: 300,  // 5 minutes
  timerText: 'Ends in {timer}',  // Shows "Ends in 4m 30s"
  timerAction: KCTimerAction.showFollowUp,
  timerActionPayload: 'Sale ended! Get 20% off instead.',
));

Timer Actions (what happens when countdown reaches 0)

Action What happens
dismiss Notification auto-dismisses
openUrl Opens URL/deeplink from timerActionPayload
showFollowUp Shows new notification with timerActionPayload as body
triggerNudge Triggers in-app nudge

Notification Callbacks

// Listen to all notification interactions
KatyayaniCore.onNotificationAction((notification, action) {
  switch (action) {
    case KCNotificationAction.clicked:
      // Navigate to notification.actionUrl or notification.deepLink
      break;
    case KCNotificationAction.dismissed:
      break;
    case KCNotificationAction.timerExpired:
      // Timer ran out
      break;
    case KCNotificationAction.stickyCleared:
      // Sticky was force-cleared
      break;
    case KCNotificationAction.shown:
      break;
    case KCNotificationAction.ctaClicked:
      break;
  }
});

// Listen to button taps
KatyayaniCore.onNotificationButtonAction((notification, buttonId) {
  if (buttonId == 'track') {
    // Navigate to tracking page
  }
});

Nudges (In-App Messages)

6 types: banner, modal, tooltip, slideIn, bottomSheet, fullScreen

// Check nudges for current screen (configured in dashboard)
KatyayaniCore.checkNudges(context, '/home');

// Auto-check on navigation (add observer)
MaterialApp(
  navigatorObservers: [KCNavigationObserver()],
);

// Dismiss all
KatyayaniCore.dismissAllNudges();

Cleanup

@override
void dispose() {
  KatyayaniCore.dispose();
  super.dispose();
}

File Structure

lib/
├── katyayani_core.dart          # Public exports
└── src/
    ├── katyayani_core.dart      # Main SDK class (singleton)
    ├── core/
    │   ├── config.dart          # SDK configuration
    │   ├── storage.dart         # SharedPreferences wrapper
    │   ├── identity.dart        # User identification
    │   ├── api_client.dart      # HTTP client to backend
    │   └── logger.dart          # Debug logger
    ├── modules/
    │   ├── event_tracker.dart   # Event batching & tracking
    │   ├── push_manager.dart    # Push: standard + sticky + timer
    │   ├── nudge_manager.dart   # In-app nudge display
    │   └── navigation_observer.dart  # Auto screen tracking
    └── models/
        ├── event.dart           # Event payload model
        ├── notification.dart    # Notification models (all types)
        └── nudge.dart           # Nudge models

Libraries

katyayani_core
Katyayani Core Flutter SDK Push notifications (standard, sticky, timer), nudges, event tracking