atlas_support_sdk 2.0.1 copy "atlas_support_sdk: ^2.0.1" to clipboard
atlas_support_sdk: ^2.0.1 copied to clipboard

Atlas customer support chat widget

Atlas Support SDK for Flutter #

A Flutter SDK that integrates a real-time chat widget into Flutter applications.

Installation #

Add Atlas Support SDK to your Flutter project by adding the following dependency to your pubspec.yaml:

dependencies:
  atlas_support_sdk: ^2.0.0

Setup #

To use it with Android you need to ensure that internet access is enabled in AndroidManifest.xml:

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

Import the package into your code:

import 'package:atlas_support_sdk/atlas_support_sdk.dart';

Connect the SDK to your account (you can find your App ID in the Atlas company settings):

AtlasSDK.setAppId("YOUR_APP_ID");

â„šī¸ It's crucial to execute this code at the app's launch, as SDK functionality will be unavailable otherwise.

User Management #

Identify Users #

Make the following call with user details wherever a user logs into your application:

AtlasSDK.identify(
  userId: "user123",
  userHash: null, // Optional security hash
  name: "John Doe",
  email: "john@example.com",
  phoneNumber: "+1234567890",
  customFields: {
    "title": "senior",
    "level": 8,
  }
);

To make sure scammers can't spoof a user, you should pass a userHash into the identify call. You can find how to enable userHash validation in the User Authentication article.

Optional parameters like name, email, or phoneNumber should be set to null (not empty string) if they're unknown, so they won't override previously stored values.

When you want to update the user's details, you can call identify method again.

Logout #

To clear the user's session when they log out of your application, use:

AtlasSDK.logout();

Atlas Widget #

Basic Implementation #

To display the Atlas chat widget in your Flutter app:

AtlasSDK.Widget();

Configuring the Widget #

You can configure how Atlas UI looks through the Chat Configuration page. You can also configure the behavior using query parameters:

// Initialize chat with help center opened
AtlasSDK.Widget(query: "open: helpcenter")

// Initialize chat with a specific chatbot
AtlasSDK.Widget(query: "chatbotKey: report_bug")

// Initialize chat with last opened chatbot if exists
AtlasSDK.Widget(query: "chatbotKey: report_bug; prefer: last")

Persistent Chat Sessions #

To maintain chat state across widget rebuilds, use the persist parameter:

AtlasSDK.Widget(
  persist: "unique_key", // Controllers are stored by this key
  query: "chatbotKey: support"
)

Event Handling #

Errors #

The SDK provides detailed error information through the AtlasError class:

AtlasSDK.onError((error) {
  print("Error message: ${error.message}");
  print("Original error: ${error.original}"); // Additional error details if available
});

Ticket Events #

The SDK provides several event handlers to monitor chat activities:

// Triggered whenever user starts new chat
AtlasSDK.onChatStarted((chatStarted) {
  var message = "đŸ’Ŧ New chat: ${chatStarted.ticketId}"
  if (chatStarted.chatbotKey != null) message += " (🤖 via chatbot ${chatStarted.chatbotKey})"; 
  print(message);
});

// Triggered when either basic chat has started, or chatbot has created ticket from the conversation
AtlasSDK.onNewTicket((newTicket) {
  var message = "đŸŽĢ New ticket: ${newTicket.ticketId}"; 
  if (newTicket.chatbotKey != null) message += " (🤖 via chatbot ${newTicket.chatbotKey})"; 
  print(message);
});

// Triggered when user identity is changed or removed
AtlasSDK.onChangeIdentity((identity) {
  if (identity == null) {
    print("User logged out");
  } else {
    print("User identified: ${identity.atlasId}");
  }
});

// Triggered when messages are received, read, or ticket is closed/reopened
AtlasSDK.watchStats((stats) {
  var unreadCount = stats.conversations.fold(0, (sum, conversation) => sum + conversation.unread);
  print("Unread conversations: ${unreadCount}");
});

Event Handler Cleanup #

All event handlers return a dispose function that should be called when the listener is no longer needed:

// Register handler
final dispose = AtlasSDK.onError((error) {
  print(error.message);
});

// Later, when you want to remove the handler
dispose();

Ticket Management #

You can update custom fields for a specific ticket after it's created:

AtlasSDK.updateCustomFields(
  "ticket_123",
  {
    "priority": "high",
    "category": "billing",
    // Any valid custom field
  }
);

Custom Field Types #

The SDK supports various custom field types. Here's how to properly format each type:

{
  // Text field (string)
  "description": "Customer feedback",
  
  // Number field (integer)
  "age": 25,
  
  // Decimal field (number with decimal places)
  "price": 99.99,
  
  // Date field (YYYY-MM-DD format)
  "birthDate": "1990-01-01",
  
  // List field (single selection from predefined list)
  "status": "active",
  
  // Multi field (multiple selections from predefined list)
  "tags": ["urgent", "billing"],
  
  // URL field (object with url and title)
  "website": {
    "url": "https://example.com",
    "title": "Company Website"
  },
  
  // Address field (object with address components, each is optional)
  "shippingAddress": {
    "street1": "123 Main St",
    "street2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "US"
  },
  
  // Agent field (UUID)
  "assignedAgent": "550e8400-e29b-41d4-a716-446655440000",
  
  // Customer field (UUID)
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  
  // Account field (UUID)
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  
  // Ticket field (UUID)
  "relatedTicket": "550e8400-e29b-41d4-a716-446655440000"
}

Data Management #

The SDK automatically handles:

  • Persistent storage of user identification
  • Chat session management
  • Controller state persistence when using the persist parameter
  • Automatic reconnection handling

All data is securely stored using the device's SharedPreferences.

Requirements #

  • Flutter 2.0.0 or later
  • Dart 2.12.0 or later

Support #

For issues or feature requests, contact the engineering team at engineering@atlas.so or visit our GitHub Issues page.

For more details, visit the official Atlas Support website.

Author #

Atlas Support Inc, engineering@atlas.so

0
likes
100
points
100
downloads

Publisher

unverified uploader

Weekly Downloads

Atlas customer support chat widget

Homepage

Documentation

API reference

License

MIT (license)

Dependencies

flutter, http, shared_preferences, web_socket_channel, webview_flutter, webview_flutter_android, webview_flutter_wkwebview, yaml

More

Packages that depend on atlas_support_sdk