mysampark_chat 1.2.2

Official MySampark Chat Widget for Flutter. Add AI-powered live chat with human agent takeover, typing indicators, lead forms, and real-time WebSocket support.

mysampark_chat

Official MySampark Chat Flutter plugin — Add AI-powered live chat with human agent takeover, typing indicators, pre-chat surveys, lead forms, and real-time WebSocket support to any Flutter app in minutes.

---

✨ Features

• 🤖 AI-powered replies — instant responses via your trained chatbot
• 👨‍💼 Human agent live takeover — agents reply in real-time via WebSocket
• ⌨️ Typing indicator — animated 3-dot bounce while AI/agent is responding
• 🏠 Home tab — branded greeting screen with Offers / Chat / Track Order cards, same layout as the web widget
• 🎁 Offers card — live deals & discount codes fetched from your store, tap-to-copy code
• 📦 Order tracking card — visitors check an order's status, carrier & tracking link without leaving the chat
• 📋 Pre-chat survey gate — collect visitor info before first message (admin controlled)
• 📝 In-chat lead form — name / email / phone capture after N messages
• 💬 Conversation starters — quick-reply chips to help visitors start a chat
• 📜 Chat history — load previous messages with scroll-up pagination
• 🟢 Online / Offline status — live indicator in the chat header
• 🖼️ Logo & branding — logo, colors, widget name all synced from your admin dashboard
• 🔐 HMAC identity — verified logged-in users skip survey, lead form & order-tracking email prompt automatically
• 💾 Session persistence — conversation resumes across app restarts
• 🫧 Floating bubble launcher — drop-in FAB that opens chat as a bottom sheet

---

🔑 Getting Your Widget Key

Every widget below needs a widgetKey from your MySampark account:

1. Sign up / log in at mysampark.com (dashboard: socialadmin.mysampark.com).
2. Open the Chatbot section of your dashboard and create (or select) a widget.
3. Copy its Widget Key (starts with pk_) — this is public and safe to embed in your app, same as the data-key used in the website embed script.
4. The widget also has a Widget Secret (starts with sk_) — used only for identifying logged-in users (see below). Never put this in your Flutter app's source. It belongs on your own backend.

Exact menu labels may differ slightly as the dashboard evolves — if a step above doesn't match what you see, the Chatbot → Widgets area is the place to look.

Identifying logged-in users (optional)

If you want returning/logged-in users to skip the pre-chat survey and be recognized automatically, your own backend (not the Flutter app) computes a verification hash for the current user and sends it to the app:

// your_backend — an authenticated endpoint, e.g. POST /me/chat-hash
return hash_hmac('sha256', $user->id, env('MYSAMPARK_WIDGET_SECRET'));

Then pass the result as userHash (see Usage below). Anonymous visitors can skip userId/userHash entirely.

---

🚀 Installation

Add to your pubspec.yaml:

dependencies:
  mysampark_chat: ^1.1.0

Run:

flutter pub get

---

📱 Platform Setup

Android Setup

To allow links (URLs) in chat messages to open in external browsers on Android 11+ (API Level 30+), add the following <queries> configuration inside <manifest> in your app's android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <queries>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="https" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="http" />
        </intent>
    </queries>
</manifest>

---

🔧 Usage

Option A — Floating Bubble (Recommended)

Drop it as your Scaffold's floatingActionButton and it renders a branded chat bubble:

import 'package:mysampark_chat/mysampark_chat.dart';

Scaffold(
  body: YourAppBody(),
  floatingActionButton: MySamparkChatBubble(
    widgetKey: 'YOUR_WIDGET_KEY',   // from MySampark dashboard

    // ── Optional: User identity parameters ───────────────────────────
    userId:    currentUser.id,
    userHash:  currentUser.chatHash,  // Verification hash from your backend
    userName:  currentUser.name,
    userEmail: currentUser.email,
    // ───────────────────────────────────────────────────────────────────
  ),
);

Option B — Full Screen Chat Page

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => MySamparkChatScreen(
      widgetKey: 'YOUR_WIDGET_KEY',

      // Optional: User identity parameters
      userId:    currentUser.id,
      userHash:  currentUser.chatHash,
      userName:  currentUser.name,
      userEmail: currentUser.email,
    ),
  ),
);

Option C — Anonymous Visitor (No login required)

// Just the widgetKey — everything else is optional
MySamparkChatBubble(widgetKey: 'YOUR_WIDGET_KEY');

---

🛒 Opening Products Inside Your App

When the AI recommends a product, the card opens the merchant's website in a browser. If your app already sells that product, onProductTap lets you open your own product screen instead — keeping the visitor's cart, session and analytics intact.

MySamparkChatBubble(
  widgetKey: 'YOUR_WIDGET_KEY',
  onProductTap: (chatContext, product) {
    final id = product.externalId;

    // Not in your catalogue (or a hand-entered product with no id at all)
    // — return false and the package opens the website, as it always has.
    if (id == null || !myCatalog.contains(id)) return false;

    Navigator.pop(chatContext);                  // close the chat sheet
    Navigator.pushNamed(context, '/product/$id');
    return true;                                 // handled — no browser
  },
)

Three things worth knowing:

• Match on product.externalId, not product.id. id is MySampark's internal id and means nothing in your catalogue. externalId is your id for the product — the SKU you pushed over the product sync API, or the Shopify / WooCommerce product id. product.source tells you which ('api', 'shopify', 'woocommerce'), and those id spaces are unrelated, so check it before treating them as one namespace.
• Returning false is a normal outcome, not an error path — you only write code for the products you stock, and everything else keeps its old behaviour. externalId is null for products the merchant typed into the dashboard by hand, and for cards restored from conversations that happened before this feature shipped.
• Use the chatContext you're handed to close the chat. MySamparkChatBubble opens the chat as a modal bottom sheet, and only that context can pop it — pushing from your own context leaves your product page behind the sheet, where nobody sees it.

The same parameter exists on MySamparkChatScreen when you push the chat as a full-screen route.

---

🏠 Home Tab, Offers & Order Tracking

MySamparkChatScreen opens on a Home tab by default — a greeting header plus up to three cards:

Card	Shown when	What it does
Offers	Admin has show_offers on + an offers source connected	Fetches GET /api/chatbot/offers, shows a bottom sheet of live deals with tap-to-copy discount codes
Chat with us	Always	Switches to the normal chat conversation view
Track your order	Admin has show_order_tracking on + an order source connected	Opens a form (order number + email — email is skipped for HMAC-identified users), calls POST /api/chatbot/track-order, and shows status / carrier / tracking link

This is entirely admin-controlled — nothing to configure in Flutter. If a merchant hasn't enabled Offers or Order Tracking in the dashboard, those cards simply don't render and only "Chat with us" is shown.

The header back arrow (and the Android hardware back button) returns from the Chat view to Home instead of closing the screen; closing the screen itself is the ✕ button on the Home header.

---

🎨 What the Admin Dashboard Controls

Everything is configured from your MySampark dashboard — no code changes needed in the Flutter app:

Admin Setting	Effect in Flutter App
Primary color	Home header, chat header, buttons, focus borders
Action color	Send button, bubbles, active nav item, cards' icon badges
Widget name	AppBar title
Logo	AppBar avatar & survey screen
Welcome message	Empty state text
Home greeting title / subtitle	Home tab header text
Show Offers + offers source	Offers card visibility on Home tab
Show Order Tracking + tracking source	Track your order card visibility on Home tab
Online / Offline text	Status indicator in header
Conversation starters	Quick-reply chips
Pre-chat survey	Survey overlay before first message
Collect name / email / phone	Lead form fields
Lead form skippable	Skip button visibility
AI on / off	AI reply vs human-only mode

---

📦 Package Structure

lib/
├── mysampark_chat.dart           ← Public exports
└── src/
    ├── models.dart               ← ChatMessage, WidgetConfig, OfferItem, OrderTrackResult
    ├── chat_service.dart         ← REST API + WebSocket handler (incl. offers & order tracking)
    ├── chat_screen.dart          ← Home tab + full-screen chat UI
    └── chat_bubble_launcher.dart ← Floating bubble widget

---

📄 License

MIT License © 2026 MySampark