Giter Site home page Giter Site logo

papercups-io / papercups_flutter Goto Github PK

View Code? Open in Web Editor NEW
27.0 4.0 22.0 1.12 MB

Papercups.io Flutter chat widget

Home Page: https://papercups-demo.eduardom.dev

License: MIT License

Dart 81.38% Kotlin 0.07% Swift 0.23% Objective-C 0.02% HTML 0.85% CMake 4.68% C++ 11.59% C 0.42% Ruby 0.77%
papercups papercups-flutter dart flutter flutter-widget live-chat intercom-alternative widget pub

papercups_flutter's Introduction

logo

pub package style: effective dart License GitHub issues

likes popularity pub points

Demo Chat

button button

Compatible with all platforms: Windows, Android, Linux, MacOS, and iOS

Installing

To get started simply add papercups_flutter: and the latest version to your pubspec.yaml. Then run flutter pub get

๐ŸŽ‰ Done, It's that simple.

Using the widget

Integration with your app requires just a few lines of code, add the following widget wherever you want your papercups chat window to be:

import 'package:papercups_flutter/papercups_flutter.dart';

PapercupsWidget(
  props: PapercupsProps(
    accountId: "xxxxxxxx-xxxxxxx-xxxx-xxxxxx", //Your account id goes here.
  ),
),
    

That should get you up and running in just a few seconds โšก๏ธ.

Configuration

Available PapercupsWidget arguments

Parameter Type Value Default
props PapercupsProps Required. This is where all of the config for the chat is contained. N/A
dateLocale String Locale for the date, use the locales from the intl package. "en-US"
timeagoLocale dynamic Check timeago messages for the available classes. N/A

Available PapercupsProps parameters

Prop Type Value Default
accountId String Required. Your Papercups account token. N/A
baseUrl String The base URL of your API if you're self-hosting Papercups. Ensure you do not include the protocol (https) of a trailing dash (/). "app.papercups.io"
customer PapercupsCustomerMetadata Identifying information for the customer, including name, email, externalId, and otherMetadata (for any custom fields). N/A
closeIcon Widget The close button displayed in the header section. N/A
closeAction VoidCallback The function to handle closing the widget. If not null, close button will be shown. N/A
scrollEnabled bool Whether or not to allow scrolling. true
floatingSendMessage bool Wether to have the message box floating. false
requireEmailUpfront bool If you want to require unidentified customers to provide their email before they can message you. Not recommended for apps. false
sendIcon Widget Message send icon in the chat text field. N/A
onMessageBubbleTap void Function(PapercupsMessage) Function to handle message bubble tap action. N/A
style PapercupsStyle Class used to customize the widget appearance. PapercupsStyle()
translations PapercupsIntl If you want to override the default EN translations displayed by the widget. PapercupsIntl()

Available PapercupsCustomerMetadata parameters

Parameters Type Value Default
email String The customer's email N/A
externalId String The customer's external ID N/A
name String The customer's name N/A
otherMetadata Map<String, dynamic> Extra metadata to pass such as OS info, app version, etc. N/A

Available PapercupsStyle parameters

Parameters Type Value Default
primaryColor Color The theme color of the chat widget. Papercups blue:
Color(0xFF1890FF)
primaryGradient Gradient Gradient to specify, should be used instead of primaryColor. DO NOT USE BOTH! N/A
backgroundColor Color Color used in the background of the entire widget.
Theme.of(context).canvasColor
titleStyle TextStyle The text style of the title at the top of the chat widget.
TextStyle(
  color: textColor, // Using computeLuminance
  fontSize: 21,
  fontWeight: FontWeight.w600,
)
titleAlign TextAlign The widget title alignment.
TextAlign.left
subtitleStyle TextStyle The chat widget sub title text style.
TextStyle(
  color: props.style.titleStyle?.color?.withOpacity(0.8),
)
headerHeight double The chat widget header height. N/A
headerPadding EdgeInsetsGeometry The chat widget header padding.
EdgeInsets.only(
  top: 16,
  right: 20,
  left: 20,
  bottom: 12,
)
noConnectionIcon Widget The widget displayed in the chat when there's no Internet connection.
Icon(
  Icons.wifi_off_rounded,
  size: 100,
  color: Colors.grey,
)
noConnectionTextStyle TextStyle The text style of the text displayed in the chat widget when there's no Internet connection.
Theme.of(context).textTheme.headlineSmall?.copyWith(color: code.grey)
requireEmailUpfrontInputDecoration InputDecoration The input decoration of the require email text field.
InputDecoration(
  border: UnderlineInputBorder(
    borderSide: BorderSide(
      color: Theme.of(context).dividerColor,
      width: 0.5,
      style: BorderStyle.solid,
    ),
  ),
  enabledBorder: UnderlineInputBorder(
    borderSide: BorderSide(
      color: Theme.of(context).dividerColor,
      width: 0.5,
      style: BorderStyle.solid,
    ),
  ),
  focusedBorder: UnderlineInputBorder(
    borderSide: BorderSide(
      color: Theme.of(context).dividerColor,
      width: 0.5,
      style: BorderStyle.solid,
    ),
  ),
  hintText: widget.props.translations.enterEmailPlaceholder,
  hintStyle: widget.props.style.requireEmailUpfrontInputHintStyle,
),
requireEmailUpfrontKeyboardAppearance Brightness The keyboard brightness of the require email text field.
Brightness.light
requireEmailUpfrontInputHintStyle TextStyle The text style of the require email text field hint.
TextStyle(fontSize: 14)
requireEmailUpfrontInputTextStyle TextStyle The text style of the require email text field. N/A
floatingSendMessageBoxDecoration BoxDecoration The box decoration of the message text field when floatingSendMessage prop is true.
BoxDecoration(
  borderRadius: BorderRadius.circular(10),
  boxShadow: [
    BoxShadow(
      blurRadius: 10,
      color: Theme.of(context).brightness == Brightness.light
          ? Colors.grey.withOpacity(0.4)
          : Colors.black.withOpacity(0.8),
    ),
  ],
)
sendMessageBoxDecoration BoxDecoration The box decoration of the message text field.
BoxDecoration(
  color: Theme.of(context).cardColor,
  border: widget.showDivider
      ? Border(
          top: BorderSide(color: Theme.of(context).dividerColor),
        )
      : null,
  boxShadow: [
    BoxShadow(
      blurRadius: 30,
      color: Theme.of(context).shadowColor.withOpacity(0.1),
    )
  ],
)
sendMessageKeyboardAppearance Brightness The keyboard brightness of the send message text field.
Brightness.light
sendMessagePlaceholderInputDecoration InputDecoration The input decoration of the message text field.
InputDecoration(
  border: InputBorder.none,
  hintText: widget.props.translations.newMessagePlaceholder,
  hintStyle: widget.props.style.sendMessagePlaceholderTextStyle,
)
sendMessagePlaceholderTextStyle TextStyle The text style of the message text field input hint text.
TextStyle(fontSize: 14)
sendMessageInputTextStyle TextStyle The text style of the message text field input. N/A
botBubbleBoxDecoration BoxDecoration The box decoration of the bot chat bubbles.
BoxDecoration(
  color: Theme.of(context).brightness == Brightness.light
    ? brighten(Theme.of(context).disabledColor, 80)
    : const Color(0xff282828,
  ),
  borderRadius: BorderRadius.circular(4),
  )
botBubbleTextStyle TextStyle The text style of the bot chat bubbles.
TextStyle(
  color: Theme.of(context).textTheme.bodyLarge?.color,
)
botAttachmentBoxDecoration BoxDecoration The box decoration of the bot attachment (images, files) chat bubbles.
BoxDecoration(
  borderRadius: BorderRadius.circular(5),
  color: Theme.of(context).brightness == Brightness.light
    ? brighten(Theme.of(context).disabledColor, 70)
    : Color(0xff282828,
  ),
)
botAttachmentTextStyle TextStyle The text style of the bot attachments file name.
TextStyle(
  color: Theme.of(context).textTheme.bodyLarge?.color,
)
botBubbleUsernameTextStyle TextStyle The text style of bot user name displayed below its chat bubbles.
TextStyle(
  color: Theme.of(context).textTheme.bodyLarge?.color?.withOpacity(0.5),
  fontSize: 14,
)
userBubbleBoxDecoration BoxDecoration The box decoration of the user chat bubbles.
BoxDecoration(
  color: widget.props.style.primaryColor,
  gradient: widget.props.style.primaryGradient,
  borderRadius: BorderRadius.circular(4),
)
userBubbleTextStyle TextStyle The text style of the user chat bubbles.
TextStyle(color: widget.textColor)
Depending on the luminance of the provided primaryColor, textColor can be either Colors.black or Colors.white.
userAttachmentBoxDecoration BoxDecoration The box decoration of the user attachment (images, files) chat bubbles.
BoxDecoration(
  borderRadius: BorderRadius.circular(5),
  color: darken(widget.props.style.primaryColor!, 20),
)
userAttachmentTextStyle TextStyle The text style of the user attachments file name.
TextStyle(color: widget.textColor)
Depending on the luminance of the provided primaryColor, textColor can be either Colors.black or Colors.white.
userBubbleSentAtTextStyle TextStyle The text style of the "Sent x ago" (or "Sending...") text displayed below the latest user chat bubble.
TextStyle(color: Colors.grey)
chatBubbleTimeTextStyle TextStyle The text style of the time stamp displayed (on tap) next to the any chat bubble.
TextStyle(
  color: Theme.of(context).textTheme.bodyLarge?.color?.withAlpha(100),
  fontSize: 10,
)
chatBubbleFullDateTextStyle TextStyle The text style of the date displayed centered in the chat before the chat bubbles of a given day.
TextStyle(color: Colors.grey)
chatUploadingAlertTextStyle TextStyle The text style of the alert shown when an attachment is being uploaded.
Theme.of(context).textTheme.bodyMedium
chatUploadingAlertBackgroundColor Color The background color of the alert shown when an attachment is being uploaded.
BottomAppBarTheme.of(context).color!
chatUploadErrorAlertTextStyle TextStyle The text style of the error alert shown when an attachment failed to upload.
Theme.of(context).textTheme.bodyMedium
chatUploadErrorAlertBackgroundColor Color The background color of the error alert shown when an attachment failed to upload.
BottomAppBarTheme.of(context).color!
chatNoConnectionAlertTextStyle TextStyle The text style of the alert shown when the chat is displayed but no Internet connection is available.
Theme.of(context).textTheme.bodyMedium
chatNoConnectionAlertBackgroundColor Color The background color of the alert shown when the chat is displayed but no Internet connection is available.
BottomAppBarTheme.of(context).color!
chatCopiedTextAlertTextStyle TextStyle The text style of the alert shown when a chat bubble gets long pressed and its text copied.
Theme.of(context).textTheme.bodyMedium
chatCopiedTextAlertBackgroundColor Color The background color of the alert shown when a chat bubble gets long pressed and its text copied.
BottomAppBarTheme.of(context).color!

Available PapercupsIntl parameters

Parameters Type Value Default
attachmentNamePlaceholder String Text displayed when an attachment doesn't have a file name "No Name"
attachmentUploadErrorText String Error message displayed when an attachment could not be uploaded "Failed to upload attachment"
attachmentUploadedText String Text displayed when an attachment has been uploaded "Attachment uploaded"
attachmentUploadingText String Text displayed when an attachment is been uploaded "Uploading..."
companyName String Company name to show on greeting "Bot"
enterEmailPlaceholder String This is the placeholder text in the email input section "Enter your email"
fileText String Text displayed on the tile where the user decides to upload a file "File"
greeting String An optional initial message to greet your customers with N/A
historyFetchErrorText String Error message displayed when the customer history couldn't be fetched "There was an issue retrieving your details. Please try again!"
imageText String Text displayed on the tile where the user decides to upload an image "Image"
loadingText String Text displayed when the chat is loading "Loading..."
newMessagePlaceholder String The placeholder text in the new message input "Start typing..."
noConnectionText String The placeholder text in the new message input "No Connection"
retryButtonLabel String Label used in the retry button when the chat history couldn't be fetched "Retry"
sendingText String Text to show while message is sending "Sending..."
sentText String Text to show when the message is sent "Sent"
subtitle String The subtitle in the header of your chat widget "How can we help you?"
textCopiedText String Text displayed when a text has been copied after long press on a chat bubble "Text copied to clipboard"
title String The title in the header of your chat widget "Welcome!"
uploadedText String Text displayed after the percentage value of an attachment being uploaded "uploaded"

Supporters

Stargazers repo roster for @papercups-io/papercups_flutter Forkers repo roster for @papercups-io/papercups_flutter

papercups_flutter's People

Contributors

aguilaair avatar charlesmangwa avatar cheeseblubber avatar dependabot[bot] avatar fiyiin avatar marwenbk avatar ryg-git avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

papercups_flutter's Issues

๐Ÿ“ Add docs for 2.0.0 (next)

  • classes.dart
  • conversation.dart
  • customer.dart
  • message.dart
  • models.dart
  • user.dart
  • colorMod.dart
  • getConversationDetails.dart
  • getCustomerDetailsFromMetadata.dart
  • getCustomerHistory.dart
  • getPastCustomerMessages.dart
  • initChannels.dart
  • joinConversation.dart
  • updateUserMetadata.dart
  • utils.dart
  • header.dart
  • requireEmailUpfront.dart
  • sendMessage.dart
  • widgets.dart
  • papercus_flutter.dart
  • Readme.md

โœจ Add markdown support (next)

Currently markdown is not supported.
I'd like to keep dependencies minimal to avoid dependency issues (e.g. not including provider, get, etc), so I am not a fan of adding more deps. However, markdown is pretty complex and I don't have the time to implement a custom renderer, especially having flutter_markdown, which we might be able to use https://pub.dev/packages/flutter_markdown

Local, encrypted chat sessions

We will be using Hive for this. Stops the few seconds of requesting data and loading it up. Will still be requested and updated, but should first load the local version for speed

๐ŸŽ‰ Release 1.0

This should happen after testing thoroughly the app, and maybe even adding unit tests.

Multiple conversations

Having the ability to have multiple, concurrent conversations.
@phr34k started modularizing the package and adding the ability to do it but there is still a lot of work to be done

Proactive messaging

Being able to send a message to a user without having the user initiating the conversation

โœ… Add basic unit testing (next)

Should cover the basics for the time being

  • Classes
  • Theming
  • Get customer
  • Messages added
  • Get previous messages
  • Update customer
  • Socket creation
  • Channel joining

Any others?

๐Ÿ› Fix bools being sent incorrectly

Papercups currently uses 1 and 0 instead of true and false so the code will need to be adapted to do this, the current behavior is jut turning the bool into a string.

โœจ When a user is customizing their background color text should auto render black when it is a lighter color (next)

Derived from papercups-io/papercups#502

Problem
If a user has a lighter shade color for the chat widget the text is not legible

Solution
We should auto change the color of the text to black when the shade is too light (need to figure out how to detect the shades and brightness)

Describe alternatives you've considered
We could let them change the color of the text themselves but it could be too ugly if they choose some mismatch colors.

Right now if the color is too bright it is not legible
image

An example of changing to black text
image

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.