katyayani_core 2.0.2

All-in-one customer engagement SDK for Flutter — event & ecommerce analytics, install/referral attribution (MMP), rich push (sticky & timer) and in-app nudges.

Katyayani Core — Flutter SDK

One SDK for your entire customer‑engagement stack. Track events & revenue, attribute installs to their source (ads / referral / organic), send rich push notifications, and show in‑app nudges — all from a single lightweight Flutter package, powered by the Katyayani Core platform.

Most apps bolt together 3–4 separate SDKs — one for analytics (Mixpanel/GA4), one for push (Netcore/Pushwoosh), one for attribution (AppsFlyer/Branch), one for referrals. Katyayani Core replaces all of them with one integration, one dashboard, and your own data.

---

✨ What you get

📊 Event & ecommerce analytics	Strongly‑typed key‑events (viewItem → purchase), custom events, funnels, revenue, product analytics.
🎯 Attribution (MMP)	Auto install attribution — smart links, Play Store referrer, UTM, fingerprint. Platform‑wise revenue & ROAS.
🔗 Referral sharing	Generate a referral link, auto‑capture the code on install, track who referred whom.
🔔 Rich push	Standard, sticky (stays until action) and timer (live countdown) notifications.
💬 In‑app nudges	Banner, modal, tooltip, slide‑in, bottom‑sheet, full‑screen — configured from the dashboard.
🆔 Identity & profiles	Stitch anonymous → identified users, set user attributes, cross‑platform dedup.

---

🆚 How it compares

Capability	Katyayani Core	Netcore	Pushwoosh
Event & ecommerce analytics	✅ built‑in	✅	⚠️ limited
Rich push (sticky + timer countdown)	✅	⚠️ partial	⚠️ rich media only
In‑app nudges / messages	✅	✅	✅
Install + referral attribution (MMP)	✅ built‑in	❌ needs AppsFlyer/Branch	❌ needs 3rd‑party
Referral link generation in‑SDK	✅	❌	❌
Platform‑wise revenue / ROAS	✅	⚠️ add‑on	❌
Single SDK for all of the above	✅	❌	❌
Own your data (self‑hosted backend)	✅	❌ SaaS	❌ SaaS

Netcore & Pushwoosh are excellent engagement platforms — but they focus on messaging. Katyayani Core adds attribution + referral + revenue in the same SDK, so you don't stitch together an MMP and an analytics tool on the side.

---

🔑 Get an API key

You need a Katyayani Core API key (nc_live_…) to send data.

📧 Request one — email us: [e-mail]

Clicking the link opens your email app with a ready‑to‑send request (just fill the blanks and hit send — it comes straight to our team). Prefer a form? Request via form » — fill it in and it lands directly in our team's inbox.

---

📦 Installation

# pubspec.yaml
dependencies:
  katyayani_core: ^2.0.1

flutter pub get

---

⚙️ Setup (3 steps)

Step 1 — Initialize the SDK

import 'package:katyayani_core/katyayani_core.dart';

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

  await KatyayaniCore.init(KCConfig(
    siteId: 'nc_live_your_api_key',              // from [e-mail]
    apiBase: 'https://your-katyayani-core-host',
    enablePush: false,                           // set true ONLY if Firebase is configured (Step 3)
  ));

  runApp(const MyApp());
}

No Firebase in your app? Keep enablePush: false. Everything else (analytics, attribution, referral) works without Firebase. Setting it true without Firebase will stop the SDK from initializing.

Step 2 — Auto screen & attribution tracking (recommended)

MaterialApp(
  navigatorObservers: [KCNavigationObserver()],  // auto screen_view + nudge checks
);

Step 3 — (Optional) Push notifications — needs Firebase

1. Add google-services.json (Android) / GoogleService-Info.plist (iOS). See Firebase Flutter setup.
2. Set enablePush: true in KCConfig.
3. Android — add to android/app/src/main/AndroidManifest.xml:

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

4. Ask for permission at a good moment: await KatyayaniCore.requestPushPermission();

---

🆔 Identify users & set attributes

Call identify() after login. This is how you set user attributes — there is no separate method.

KatyayaniCore.identify('[phone]', traits: {
  'phone': '[phone]',   // → phone column (needed for Users search)
  'email': '[e-mail]', // → email column
  'name': 'Ram Kumar',        // auto‑split into first/last name
  'city': 'Indore',           // any other key → custom attribute
  'plan': 'premium',
});

KatyayaniCore.resetIdentity();  // on logout

Steps: (1) user logs in → (2) call identify(userId, traits) → (3) profile appears in the Users dashboard, searchable by phone/email. Call again anytime to update attributes.

---

📈 Events reference — every event explained

Custom events

KatyayaniCore.track('coupon_applied', properties: {'code': 'SAVE10', 'value': 50});
KatyayaniCore.screenView('/products/humic-acid');

What / when: any app action you want to measure. Fires an analytics event with your properties.

Ecommerce key‑events (strongly typed)

Line items use the typed KCItem (sku, qty, rate are required). value auto‑computes from items (Σ qty×rate) if you omit it. params accepts any custom key‑values.

final items = [
  KCItem(
    sku: 'SKU-NEEM-1L', qty: 2, rate: 499,        // required
    name: 'Neem Oil 1L',
    category: 'Pesticides',
    subCategory: 'Organic',
    otherCategories: ['Kharif', 'Bestseller'],     // → other_category_1, other_category_2 … n
    extra: { 'hsn': '3808', 'batch': 'B-2607' },   // any extra item fields
  ),
];

Event	What it means / when to call	Example
viewItem	User opened a product page	KatyayaniCore.viewItem(items: items);
addToCart	Item added to cart	KatyayaniCore.addToCart(items: items);
removeFromCart	Item removed from cart	KatyayaniCore.removeFromCart(items: items);
viewCart	Cart screen opened	KatyayaniCore.viewCart(items: items);
beginCheckout	Checkout started	KatyayaniCore.beginCheckout(items: items, coupon: 'SAVE10');
addPaymentInfo	Payment method chosen	KatyayaniCore.addPaymentInfo(items: items, paymentType: 'UPI');
purchase ⭐	Order placed (drives Revenue)	see below
refund	Order refunded	KatyayaniCore.refund(transactionId: 'ORD-016', items: items);

// The full purchase — step at your order-success screen:
KatyayaniCore.purchase(
  transactionId: 'ORD-016',
  items: items,
  tax: 70, shipping: 50, coupon: 'SAVE10',
  params: { 'salesman_id': 'EMP-42', 'payment_mode': 'COD', 'farm_size_acre': 12 },
);
// ALSO attribute the revenue to the acquisition source (for ROAS):
KatyayaniCore.capturePayment(1497, orderId: 'ORD-016');

Typical funnel order: viewItem → addToCart → beginCheckout → addPaymentInfo → purchase (+ capturePayment). The dashboard builds the funnel automatically.

Engagement key‑events

KatyayaniCore.search(searchTerm: 'neem oil');
KatyayaniCore.signUp(method: 'phone');   // step: right after signup completes
KatyayaniCore.login(method: 'otp');

---

🎯 Attribution — where users come from

Source (ads / referral / organic) is detected automatically on first open. You only mark conversions and revenue:

KatyayaniCore.trackAttribution('signup');           // funnel milestone, tied to the acquired source
KatyayaniCore.capturePayment(1497, orderId: 'ORD1'); // revenue → source (Revenue/ROAS page)

// deferred deep link from the smart link the user came from
KatyayaniCore.onDeferredDeepLink((route, attr) {
  navigatorKey.currentState?.pushNamed(route);
});

---

🔗 Referral sharing

// 1) Referrer shares a link:
final url = await KatyayaniCore.generateReferralLink(
  myReferralCode,
  referrerId: currentUserId,
  androidStoreUrl: 'https://play.google.com/store/apps/details?id=com.myapp', // required
);
Share.share('Join with my code: $url');

// 2) New user installs → code auto‑arrives:
KatyayaniCore.onReferral((code, params) {
  referralField.text = code;                 // auto‑fill
});

// 3) After signup, lock it to the real user:
KatyayaniCore.confirmReferral(code, referrerId: params['referrerId']);

Steps: referrer taps Refer → generateReferralLink → share URL → friend installs → your app gets the code via onReferral → confirmReferral on signup. The dashboard shows who referred whom.

---

🔔 Push notifications

// Standard — normal push
KatyayaniCore.showNotification(KCNotification(
  id: 'promo_1', title: 'New Offer!', body: 'Neem Oil at ₹399', actionUrl: '/products/neem-oil',
));

// Sticky — stays until dismissed / action taken
KatyayaniCore.showNotification(KCNotification(
  id: 'order_1', title: '🛒 Order Processing', body: 'Being packed',
  type: KCNotificationType.sticky, ongoing: true,
  buttons: [KCNotificationButton(id: 'track', label: 'Track', deepLink: '/orders/1')],
));

// Timer — live countdown, auto‑action on expiry
KatyayaniCore.showNotification(KCNotification(
  id: 'sale_1', title: '⏰ Flash Sale!', body: '50% off',
  type: KCNotificationType.timer, timerDurationSeconds: 300, timerText: 'Ends in {timer}',
  timerAction: KCTimerAction.showFollowUp, timerActionPayload: 'Sale ended — 20% off instead.',
));

// React to taps
KatyayaniCore.onNotificationAction((n, action) { /* clicked / dismissed / timerExpired … */ });
KatyayaniCore.onNotificationButtonAction((n, buttonId) { /* handle button */ });

Timer actions on expiry: dismiss · openUrl · showFollowUp · triggerNudge.

---

💬 In‑app nudges

Six types configured from the dashboard: banner, modal, tooltip, slideIn, bottomSheet, fullScreen.

KatyayaniCore.checkNudges(context, '/home');   // or automatically via KCNavigationObserver
KatyayaniCore.dismissAllNudges();

---

🧹 Cleanup

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

---

💛 Support & API keys

• API key / onboarding: [e-mail]
• Questions / issues: email the same address and we'll help you integrate.

Made with 💛 by Katyayani Organics.