hatang_chat 0.5.0

Hatang live chat for Flutter apps: a native customer-support chat screen that talks to your Hatang site over REST and WebSocket, with identity, events, presence and push hooks.

Changelog

All notable changes to hatang_chat are documented here. The format follows Keep a Changelog and the package uses Semantic Versioning.

[Unreleased]

0.5.0 - 2026-10-14

Added

• The chat screen follows more of the site's widget settings (dashboard: Hỗ trợ → Kênh → choose the site); older gateways that omit them keep today's behaviour.
  • Header: the subtitle under the site name (current language only), and the business logo (or the site name's first letter) instead of the agents when the profile is business. Agent avatars now show their pictures, falling back to initials.
  • Greeting: hidden when turned off or off on mobile (the SDK counts every platform as mobile); with the "online agent" sender, the first online agent's name shows under it.
  • Contact buttons: a scrolling row of Zalo, Messenger, phone and email pills under the header (only https:, tel: and mailto: links), opened with url_launcher.
• SiteConfig.header (HeaderConfig, HeaderProfile), SiteConfig.greetingOptions (GreetingOptions, GreetingSender) and SiteConfig.contactButtons (ContactButton, ContactKind).
• greetingRowFor(config, locale, online:) and GreetingRow.sender.
• HatangChatStrings.callUs and emailUs (required when building a HatangChatStrings by hand; copyWith is unaffected).

0.4.0 - 2026-10-13

Fixed

• A paid payment card no longer stays pending (QR, transfer note and Pay still showing) after the customer pays: the card message is not updated live, so the card also counts as paid when the timeline has an order_paid message for its order or an order_paid event for its payment or order. Paid and expired cards now also hide the transfer note.
• Payment cards now show the VietQR code. The gateway serves qr_image_url as SVG (/pay/{id}/qr.svg), which Image.network cannot decode, so the code never appeared. The SDK now draws it natively from the EMVCo payload, taken from the card (qr_payload / qr.payload) or, for older cards, from the public checkout (GET /pay/{id}); a raster qr_image_url still works. A failed lookup shows a QR icon and a Retry button instead of spinning.
• Product, order and payment cards no longer repeat their plain-text summary (the copy the gateway keeps for email, push and other channels) in a bubble above the card; only the sender's intro line is kept (metadata.intro, or parsed from the text), and with no intro the bubble is hidden. Quick replies, ratings and unknown card kinds still show the text.

Added

• PaidMarks, PaymentCard.statusPaid / isPaid(marks) and MessageRow.paid.
• PaymentCard.qrPayload, PaymentQr (resolve, checkoutUrlFor, isRaster), PaymentQrSource, PaymentQrException, and HatangChatController.resolvePaymentQr / ChatEngine.resolvePaymentQr.
• ProductCard.intro and cardBubbleText(content, card, {intro}).
• Dependency on qr (pure Dart, by the Dart team's kevmoo) to encode the code.

0.3.2 - 2026-09-29

Added

• "Chat by hatang.dev" (vi: "Chat bởi hatang.dev") under the composer, like the web widget. It is plain text, not a link, and follows the poweredBy string override.

0.3.1 - 2026-09-28

Added

• HatangChatLauncher follows the site's launcher settings from the dashboard: the preset icon (chat, support headset, question mark, round message) or the site's image, and a per-language label that turns it into an extended button such as "Hỗ trợ". child still overrides both. SiteConfig.launcher (LauncherConfig, LauncherIcon) exposes them.

0.3.0 - 2026-09-28

Changed (breaking, 0.x)

• File attachments need a picker: pass pickFile to HatangChat.configure (or HatangAttachmentPicker(pickFile:)). The attach sheet offers "File" only when one is set; camera and photo library are unchanged. The file_picker 13 picker moved to package:hatang_chat/file_picker.dart (pickFile: hatangFilePicker), so the main library no longer imports file_picker and apps pinned to an older one can add the SDK.

Changed

• Wider dependency ranges so existing apps resolve without upgrading native plugins: flutter_secure_storage >=10.0.0 <12.0.0, flutter_image_compress ^2.3.0, image_picker ^1.1.2.

Fixed

• reset() before the chat ever connected (autoConnect: false) did nothing, so signing out kept the previous user's visitor. It now forgets the stored visitor without opening a connection.

Added

• HatangAttachmentPicker, HatangAttachmentSource and HatangFilePick are exported from package:hatang_chat/hatang_chat.dart.

0.2.4 - 2026-09-28

Fixed

• "Load earlier messages" showed in a conversation an agent opened with a greeting although nothing older existed: the first visible item is past seq 1 because assignment events are hidden from the visitor. The SDK now uses the gateway's timeline_has_more (bootstrap and ready), falling back to the old guess with gateways that do not send it.

Added

• Example app on Android: push works with the public demo without any build flags (the demo's Firebase client options are in lib/demo.dart; the demo site holds the matching service account).

0.2.3 - 2026-09-28

Fixed

• handleNotification(data, context: …) waited until the chat screen was closed, so start-up code that awaited it (as in the README) hung while the chat was open. It now returns once the chat is pushed, like the navigatorKey and cold-start paths.

Added

• Example app: a Push tab (FCM token, paste a token, simulate notification taps) and optional Firebase Messaging wired to setPushToken and handleNotification, enabled with --dart-define=FIREBASE_* values.

Documentation

• iOS push checklist in the README (App ID matching the bundle ID exactly, APNs key in Firebase, capabilities); a mismatched App ID shows up as APNs TopicDisallowed.
• Android: replies use the notification channel hatang_messages; the README shows how to create it (otherwise Firebase's fallback channel is used).
• Local development on the Android emulator uses adb reverse tcp:3002 tcp:3002; 10.0.2.2 reached the REST API but not the WebSocket, whose URL the gateway builds from its CHAT_URL.

0.2.2 - 2026-09-28

Added

• Screenshots on pub.dev and in the README.
• The example app runs against Hatang's public demo inbox when started without --dart-define values (dart pub unpack hatang_chat, then flutter run in example/).

0.2.1 - 2026-09-27

Changed

• Text on the site colour (your bubbles, filled buttons, badges) is now dark or white, whichever has the higher contrast, instead of white for most colours. With the default #0ea5e9 it becomes dark (7:1 instead of 2.8:1). Where the site colour is used as text (quick replies, outlined buttons, links, prices) it is darkened or lightened just enough to reach 4.5:1. HatangChatTheme.accentText, contrastRatio and readableOn expose the rule; set onMineBubble to keep white bubble text.

Fixed

• Card buttons and quick replies use the app's font (labelLarge) instead of the platform default.
• Accessibility: the offline and "connecting" banners meet 4.5:1 contrast, the composer is at least 48 px tall, and order and payment lines wrap instead of overflowing when the text size is doubled.
• The package is WebAssembly-compatible (flutter build web --wasm): on the web the app version is read from version.json and the browser from the user agent instead of package_info_plus/device_info_plus, and photos are sent as picked instead of going through flutter_image_compress. Native platforms behave as before.
• Flutter web could not connect: the SDK sent the whole browser user agent as app.os_version and the gateway rejected the bootstrap (over 40 characters). The web now reports Chrome 140 / Chrome on macOS, and every app field is cut to the gateway's limits on all platforms (locale tags to language-region).

0.2.0 - 2026-09-27

Added

• Cards under the team's messages: product carousel (View opens the product page, Buy prefills the composer), order summary, payment request (VietQR, copyable transfer note, Pay now; paid and expired states), quick replies (newest message only) and the 1–5 star rating with an optional comment.
• HatangCommerce (configure(commerce:), HatangConversationView(commerce:)): onBuyProduct and onPay hooks so an app can sell through App Store / Play in-app purchase, and showExternalCheckout: false to hide the QR code, the transfer note and the web checkout where store rules forbid external payment.
• Attachments: an attach button in the composer (camera on phones, photo library, any file), upload progress on the pending bubble, retry that resumes an unfinished upload, HEIC/HEIF photos converted to JPEG and large photos scaled to 2048 px before upload, 10 MB and file-type checks before sending. Received pictures show as thumbnails cached by attachment id (re-signed links do not re-download) and open in a full-screen viewer with pinch and double-tap zoom; other files show name and size and open in the system handler. Expired links are refreshed once per message. HatangChatController.attach, pickAndSend, pickAndSendImage, pickAndSendFile; HatangAttachmentPicker for hosts with their own UI.
• History: HatangChatInbox (and HatangChat.openInbox) lists the visitor's conversations with the agent, last message, time, unread count and resolved status, with pull to refresh and paging; tapping one opens it and "New message" returns to the current conversation. HatangChat.open(context, conversationId: …) now opens that conversation (also from a notification on a cold start). Writing into a resolved conversation reopens it; a closed one is read-only. Engine/controller: listConversations, openConversation, openActive.
• Embedding: setBottomPadding now moves a chat screen and launcher that are already shown (bottomPaddingListenable); the launcher uses the host's string overrides. The example app has an Embedded tab.
• The User-Agent carries the OS version (hatang-chat-flutter/0.2.0 (ios/18.1; protocol/1)), and sdkVersion is generated from pubspec.yaml by the release tooling so they cannot drift.
• ProductCardItem.appStoreProductId / googlePlayProductId (and hasStoreProduct): the in-app purchase ids a shop sets per product in the dashboard, so onBuyProduct needs no SKU mapping.

0.1.0 - 2026-09-28

Added

• HatangChat.configure with a site id and app key; the SDK bootstraps a visitor, keeps its token in secure storage and connects to the Hatang gateway over WebSocket (protocol v1).
• HatangChatScreen and HatangChat.open(context): a full-screen text chat with greeting, away banner, day separators, typing indicator, read receipts, pending/failed bubbles with tap-to-retry and earlier-history paging.
• Session API: identify, setData, pushEvent, setLocale, setScreen, reset, restoreSession, linkTokenFromUri, session.
• Streams: events, unreadCount (+ unreadCountListenable), availability, connectionState.
• App lifecycle: app.state frames on background/foreground with a delayed socket close and a resume on return.
• Push hooks (setPushToken, clearPushToken, isHatangNotification, handleNotification); device registration is deferred until the gateway ships the /devices endpoints.
• Offline pre-chat form and email request gating, Vietnamese and English strings, light/dark theme derived from the site colour.

Coming

• Rich cards (products, orders, payments, quick replies, CSAT), attachments and image viewer, inbox of earlier conversations, launcher bubble, embedded conversation view (0.2.0).