Flutter集成支持插件atlas_support_sdk的使用

获取开始

要使用此插件，首先需要确保在 AndroidManifest.xml 文件中包含以下权限：

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

使用方法

你可以通过修改示例应用中的凭据来运行示例应用。示例应用的代码位于 这里。

添加聊天窗口

通过以下方式将聊天窗口添加到你的应用中：

import 'package:atlas_support_sdk/atlas_support_widget.dart';

// 使用小部件：
AtlasSupportWidget(
  appId: "...", 
  userId: "...", 
  userHash: "...", 
  onError: print
)

监听统计信息的变化

每个会话统计实例包含 id、unread（未读消息的数量）和 closed 标志。

import 'package:atlas_support_sdk/watch_atlas_support_stats.dart';

// 监听统计变化：
class _MyWidgetState extends State<MyWidget> {
  int _unreadCount = 0;
  Function? _unsubscribe = null;

  [@override](/user/override)
  void initState() {
    super.initState();
    _unsubscribe = watchAtlasSupportStats(
        appId: "...",
        userId: "...",
        userHash: "...",
        onStatsChange: (stats) {
          setState(() {
            _unreadCount = stats.conversations
                .fold(0, (sum, conversation) => sum + conversation.closed ? 0 : conversation.unread);
          });
        },
        onError: print);
  }

  [@override](/user/override)
  void dispose() {
    _unsubscribe?.call();
    super.dispose();
  }

  // ...
}

更新用户自定义字段

import 'package:atlas_support_sdk/update_atlas_custom_fields.dart';

AtlasSupportWidget(
  appId: "...",
  onNewTicket: (data) {
    updateAtlasCustomFields(
      "...", // atlasId
      data["ticketId"], // ticketId
      {"prop": "value"}, // 自定义字段
      // 如果需要：
      userHash: "...",
    );
  },
);

使用具有共享设置的实例

通过调用 sdk.identify(userId: "...", userHash: "...") 可以更改所有小部件和监听器的用户。

import 'package:atlas_support_sdk/atlas_support_sdk.dart';

// 监听：
class _MyWidgetState extends State<MyWidget> {
  int _unreadCount = 0;
  Function? _unsubscribe = null;
  AtlasSupportSDK atlasSdk = createAtlasSupportSDK(
    appId: "...",
    userId: "...",
    userHash: "...",
    onError: print,
  );

  [@override](/user/override)
  void initState() {
    super.initState();
    _unsubscribe = atlasSdk.watchStats((stats) {
      setState(() {
        _unreadCount = stats.conversations
            .fold(0, (sum, conversation) => sum + conversation.closed ? 0 : conversation.unread);
      });
    });
  }

  [@override](/user/override)
  void dispose() {
    _unsubscribe?.call();
    super.dispose();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: atlasSdk.Widget(
        onNewTicket: (data) {
          atlasSdk.updateCustomFields(
            data["ticketId"], // ticketId
            {"prop": "value"}, // 自定义字段
          );
        },
      )
    );
  }

  // ...
}

// 当通过 SDK 实例使用小部件时，还可以持久化其状态以防止多次加载 Atlas。
// 使用 `persist` 属性并传递唯一的字符串值，加载后应用将立即渲染：
sdk.Widget(persist: "main")

小部件的 query 参数

可选的 query 参数以字符串格式提供。query 用于配置嵌入式聊天小部件的行为或内容。

// 初始化小部件并立即启动聊天机器人（chatbotKey: report_bug），或者打开最后一个聊天机器人（prefer: last）
AtlasSupportWidget(appId: "...", query: "chatbotKey: report_bug; prefer: last")
// 或者
atlasSdk.Widget(query: "chatbotKey: report_bug; prefer: last")

// 初始化小部件并立即打开帮助中心
atlasSdk.Widget(query: "open: helpcenter")

• <code>chatbotKey: key</code>: （可选）指定必须立即启动的聊天机器人。
• <code>prefer: last</code>: （可选）不是每次都要启动新的聊天机器人，而是打开最后一个未完成的聊天机器人（如果存在）。
• <code>open: helpcenter</code>: 启动带有帮助中心屏幕的小部件。

完整示例代码

以下是完整的示例代码，展示了如何集成 atlas_support_sdk 插件：

// ignore_for_file: avoid_print

import 'package:atlas_support_sdk/atlas_support_sdk.dart';
import 'package:flutter/material.dart';
import 'package:badges/badges.dart' as badges;
import 'test_users.dart';

var firstUser = user;
var secondUser = userEmpty;
var currentUser = secondUser;

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;
  int _unreadCount = 0;
  Function? _unsubscribe;
  AtlasSupportSDK sdk = createAtlasSupportSDK(
    appId: appId,
    userId: currentUser['id'],
    userHash: currentUser['hash'],
    onError: (error) => print("onError($error)"),
    onNewTicket: (data) => print("onNewTicket($data)"),
    onChangeIdentity: (identity) => print("onChangeIdentity($identity)"),
  );

  [@override](/user/override)
  void initState() {
    super.initState();
    _unsubscribe = sdk.watchStats((stats) {
      setState(() {
        _unreadCount = stats.conversations
            .fold(0, (sum, conversation) => sum + conversation.unread);
      });
    });
  }

  [@override](/user/override)
  void dispose() {
    _unsubscribe?.call();
    super.dispose();
  }

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
        actions: [
          badges.Badge(
            showBadge: _unreadCount > 0,
            badgeContent: Text(_unreadCount.toString()),
            position: badges.BadgePosition.topEnd(top: 5, end: 5),
            child: IconButton(
              icon: const Icon(Icons.help),
              onPressed: () {
                Navigator.push(
                  context,
                  MaterialPageRoute(builder: (context) {
                    return Scaffold(
                      appBar: AppBar(
                        title: const Text('Help'),
                        actions: [
                          IconButton(
                            onPressed: () {
                              currentUser = currentUser == firstUser
                                  ? secondUser
                                  : firstUser;
                              sdk.identify(
                                  userId: currentUser['id'],
                                  userHash: currentUser['hash']);
                            },
                            icon: const Icon(Icons.refresh),
                          )
                        ],
                      ),
                      body: sdk.Widget(
                        persist: "main",
                        query: "chatbotKey: embed_test",
                        onNewTicket: (data) {
                          sdk.updateCustomFields(
                              data['ticketId'], {'test': 'flutter-sourced'});
                        },
                      ),
                    );
                  }),
                );
              },
            ),
          )
        ],
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('You have pushed the button this many times:'),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}