3box-chatbox-react-enhanced 中文文档教程

发布于 5年前 浏览 30 更新于 3年前

不和谐”></a> 
  <a href=npm Twitter Follow

3Box Chatbox Plugin ????

3box-chatbox-react 节点包是一个嵌入式 React 组件,它为 Web3 开发人员的以太坊应用程序提供现成的聊天系统。 只需一行代码,即可轻松将丰富、去中心化的社交话语添加到您的 dApp。 3Box 聊天框插件是使用 3Box 基础架构构建的,并处理创建聊天框的所有逻辑。 从 v0.1.0 开始,Chatbox 支持对每条消息点赞。 阅读 docs.3box.io 上的文档。

Try the demo here

示例截图

How it Works

Architecture

Chatbox 插件是使用 Open Threads 的标准实现构建的在 3Box Threads API 中定义并通过 3Box.js SDK。 聊天框消息是短暂的,只有在聊天框中至少有一个用户时才会保留。 Chatbox 插件包括用于输入和显示窗口内和弹出式聊天以及所有相关逻辑的 UI。 该组件可配置为各种身份验证模式,并且可以处理 Web3/3Box 登录和登录。 注销状态。

Authentication

从 0.0.5 版本开始,配置的聊天框内容可以在组件挂载时直接读取。 当用户决定发布到聊天框时,将自动处理对所提供空间的身份验证。

Getting Started

  1. Install the component
  2. Choose your authentication pattern
  3. Configure application settings
  4. Usage

1. Install the component

npm i -S 3box-chatbox-react

2. Choose your authentication pattern

根据您的 dApp 何时以及如何处理 web3 和 3Box 的身份验证,您将需要为组件提供一组不同的道具。 以下 AC 中讨论了三种可接受的身份验证模式及其各自的道具:

A) Dapp 处理 web3 和 3Box 登录,并且它们组件安装之前运行。 (推荐)

Dapp 集成了3Box.js SDK3box-chatbox-react 组件。 在这种情况下,通过 3Box.js 从 Box.openBox(ethAddr) 返回的 box 实例应该传递给聊天框的 box 属性成分。 用户当前的以太坊地址应传递给 currentUserAddr 属性以确定哪些消息是他们自己的。

B) Dapp 处理 web3 和 3Box 登录,但它们在组件安装之前没有运行。 (推荐)

Dapp 集成了3Box.js SDK3box-chatbox-react 组件。 在这种情况下,dapp 中实现的登录逻辑应该作为 loginFunction 属性传递给 Chatbox 组件,该属性在用户尝试发布消息时运行。 用户当前的以太坊地址应传递给 currentUserAddr 属性以确定哪些消息属于该用户。

C) Dapp没有web3和3Box登录逻辑。

Dapp只集成了3box-chatbox-react组件,没有集成3Box.js SDK . 所有 web3 和 3Box 登录逻辑都将在 Chatbox 组件中处理,尽管它需要将来自 dapp 首选 web3 提供程序的 ethereum 对象传递到组件中的 ethereum 属性.

Best practice

为获得最佳用户体验,我们建议实施以下身份验证模式之一:A; B; 或 B 与 A。

这些模式中的每一个都允许您的应用程序使 box 对象在全局应用程序状态下可用,无论用户在哪个页面上,聊天框组件的所有实例都可以使用它。 这种全局模式消除了用户在每个聊天框组件上进行身份验证的需要,如果您决定拥有多个聊天框组件(在 C 中就是这种情况)。

3. Configure application settings

首先,为应用程序的 3Box 空间选择一个名称。

尽管您可以自由选择您喜欢的应用程序空间名称,但我们建议使用您的应用程序名称。 如果您的应用程序已经有一个 3Box 空间,欢迎您将同一个空间用于聊天框。

接下来,为您的应用程序的线程选择一个命名约定。

聊天框线程需要一个名称,我们建议您的应用程序根据一个简单的规则创建threadNames。 我们通常喜欢使用自然标识符,例如社区名称、页面 URL、令牌 ID 或其他类似方式。



4. Usage

Example

import ChatBox from '3box-chatbox-react';

const MyComponent = ({ handleLogin, box, ethereum, myAddress, currentUser3BoxProfile, adminEthAddr }) => (
    <ChatBox
        // required
        spaceName="mySpaceName"
        threadName="myThreadName"


        // Required props for context A) & B)
        box={box}
        currentUserAddr={myAddress}

        // Required prop for context B)
        loginFunction={handleLogin}

        // Required prop for context C)
        ethereum={ethereum}

        // optional
        mute={false}
        popupChat
        showEmoji
        colorTheme="#181F21"
        currentUser3BoxProfile={currentUser3BoxProfile}
        userProfileURL={address => `https://mywebsite.com/user/${address}`}
        spaceOpts={}
        threadOpts={}
        agentProfile={
            chatName: "3Box",
            imageUrl: "https://imgur.com/RXJO8FD"
        }
        openOnMount={false}

        // enable Persistent Thread
        persistent
        // open
        firstModerator={"0xF439..."}
        // moderators={["0xp83F..."]}
        // members={["0xp83F...", "0xu9i7..."]}
    />
);

Prop Types

Property Type Default Required Case Description
spaceName String Always Likely your dApp name and / or chatbox category. A single spaceName with different threadNames is common practice when building a dApp with multiple Chatbox threads.
threadName String Always A name specific to this Chatbox.
box Object A (and likely B) The box instance returned from running await Box.openBox(address, web3) somewhere in your dApp.
currentUserAddr String (Ethereum Address) A & B The current user's Ethereum address. Passing this will be used to check which messages belong to the current user and can be used for fetching their 3Box profile to render in the Chatbox input UI.
loginFunction Function B A function from your dApp that handles web3 and 3Box login at the global dApp state. This callback will run when a user attempts to join the Chatbox but a box instance doesn't yet exist. Running this function should result in a box instance (from const box = Box.openBox(address, web3)) being passed as the box prop to this component.
ethereum Object window.ethereum C The ethereum object from whichever web3 provider your dApp uses. The enable method on this object will be used to get the current user's Ethereum address and that address will be used to openBox within the current Component context.
popupChat Boolean False Optional A boolean - true - to configure a pop up style chatbox with a button fixed to the bottom right of the window to pop open the chat UI. False will render the component in whichever container you have implemented.
agentProfile Object { chatName: 'Chatbox', imageUrl: null } Optional An object with the name of the chatbox which will appear in the Join thread step and in the header of the chat UI. The default imageUrl is the provided chat icon.
spaceOpts Object Optional Optional parameters for threads (see Docs.3box.io for more info)
threadOpts Object Optional Optional parameters for threads (see Docs.3box.io for more info)
colorTheme String/Boolean False Optional Pass an rgb or hex color string to match the color theme of your application
mute Boolean False Optional Pass false to turn off sound for incoming messages.
showEmoji Boolean False Optional Pass false to turn off the emoji pop up within the chat input UI.
currentUser3BoxProfile Object Optional If the current user has already had their 3Box data fetched at the global dApp state, pass the object returned from Box.getProfile(profileAddress) to avoid an extra request. This data will be rendered in the Chatbox input interface.
userProfileURL Function Defaults to returning user's 3Box profile URL Optional A function that returns a correctly formatted URL of a user's profile on the current platform. The function will be passed an Ethereum address within the component, if needed. A user will be redirected to the URL returned from this function when clicking on the name or Ethereum address associated with the message in the chatbox. This prop is also used in the "Edit profile" link in the header of the Chatbox component.
openOnMount Boolean False Optional Set whether a Popup style Chatbox is open on component mount. This prop only affects desktop browsers.
persistent Boolean False Optional Use persistent thread if set to true.
open Boolean False Optional Make the persistent thread open and anyone can post. If set to False, only members can post.
firstModerator Eth Address Optional The first moderator in persistent thread. This field is important to find the exact thread.
members Array of Eth Address Optional When the thread is private (open is false), add the provided members into the thread. Ignored if the thread is public.
moderators Array of Eth Address Optional When the thread is private (open is false), set the provided moderators for this thread. Ignored if the thread is public.
onLoad({messages, likes, thread}) Function Optional The callback function which is called when the chat messages are loaded for the first time. The chat history of messages and likes, and the thread object will be returned
onUpdate({messages, likes, thread}) Function Optional The callback function which is called when messages arrive. The messages and likes contains all the messages and likes
onError Function Optional The callback function which is called when failed to send message to the chat. Parameters of (error, data, showError) will be sent to onError. error is the error thrown when failed, data contains the info membership data, and showError is the function to show error message which accepts message as its parameter

License

麻省理工学院

Discord npm Twitter Follow

3Box Chatbox Plugin ????

3box-chatbox-react node package is a drop-in react component that provides Web3 developers with a readymade chat system for their Ethereum application. Easily add rich, decentralized social discourse to your dApp with one line of code. The 3Box Chatbox plugin is built using 3Box infrastructure, and handles all logic for creating a chatbox. Starting with v0.1.0, Chatbox supports likes for every message. Read the docs on docs.3box.io.

Try the demo here

Example Screenshot

How it Works

Architecture

The Chatbox plugin is built using a standard implementation of Open Threads which are defined in the 3Box Threads API and made available via the 3Box.js SDK. Chatbox messages are ephemeral and are persisted only as long as there is at least one user in the chatbox. The Chatbox plugin includes UI for inputting and displaying both an in-window and pop-up chat and all relevant logic. The component is configurable to various authentication patterns, and can handle both Web3/3Box logged-in & logged-out states.

Authentication

Starting with version 0.0.5, the content of the configured chatbox can be read right on component mount. Authentication into the space provided is handled automatically when the user decides to post to the chatbox.

Getting Started

  1. Install the component
  2. Choose your authentication pattern
  3. Configure application settings
  4. Usage

1. Install the component

npm i -S 3box-chatbox-react

2. Choose your authentication pattern

Depending on when and how your dApp handles authentication for web3 and 3Box, you will need to provide a different set of props to the component. Three acceptable authentication patterns and their respective props are discussed below in A-C:

A) Dapp handles web3 and 3Box logins, and they run before component is mounted. (recommended)

Dapp integrates with 3Box.js SDK and the 3box-chatbox-react component. In this case, the box instance returned from Box.openBox(ethAddr) via 3Box.js should be passed to the box prop in the chatbox component. The user's current Ethereum address should be passed to the currentUserAddr prop to determine which messages are their own.

B) Dapp handles web3 and 3Box logins, but they haven't run before component is mounted. (recommended)

Dapp integrates with 3Box.js SDK and the 3box-chatbox-react component. In this case, the login logic implemented in the dapp should be passed to the Chatbox component as the loginFunction prop, which is run when a user attempts to post a message. The user's current Ethereum address should be passed to the currentUserAddr prop to determine which messages belong to that user.

C) Dapp has no web3 and 3Box login logic.

Dapp only integrates with the 3box-chatbox-react component, but not 3Box.js SDK. All web3 and 3Box login logic will be handled within the Chatbox component, though it's required for the ethereum object from your dapp's preferred web3 provider be passed to the ethereum prop in the component.

Best practice

For the best UX, we recommend implementing one of the following authentication patterns: A; B; or B with A.

Each of these patterns allow your application to make the box object available in global application state where it can be used by all instances of the Chatbox component regardless of which page the user is on. This global pattern removes the need for users to authenticate on each chatbox component, should you decide to have more than one, which would be the case in C.

3. Configure application settings

First, choose a name for your application's 3Box space.

Although you are free to choose whichever name you'd like for your app's space, we recommend using the name of your app. If your application already has a 3Box space, you are welcome to use that same one for the chatbox.

Next, choose a naming convention for your application's threads.

The Chatbox thread needs a name, and we recommend that your application creates threadNames according to a simple rule. We generally like using a natural identifier, such as community name, page URL, token ID, or other similar means.



4. Usage

Example

import ChatBox from '3box-chatbox-react';

const MyComponent = ({ handleLogin, box, ethereum, myAddress, currentUser3BoxProfile, adminEthAddr }) => (
    <ChatBox
        // required
        spaceName="mySpaceName"
        threadName="myThreadName"


        // Required props for context A) & B)
        box={box}
        currentUserAddr={myAddress}

        // Required prop for context B)
        loginFunction={handleLogin}

        // Required prop for context C)
        ethereum={ethereum}

        // optional
        mute={false}
        popupChat
        showEmoji
        colorTheme="#181F21"
        currentUser3BoxProfile={currentUser3BoxProfile}
        userProfileURL={address => `https://mywebsite.com/user/${address}`}
        spaceOpts={}
        threadOpts={}
        agentProfile={
            chatName: "3Box",
            imageUrl: "https://imgur.com/RXJO8FD"
        }
        openOnMount={false}

        // enable Persistent Thread
        persistent
        // open
        firstModerator={"0xF439..."}
        // moderators={["0xp83F..."]}
        // members={["0xp83F...", "0xu9i7..."]}
    />
);

Prop Types

Property Type Default Required Case Description
spaceName String Always Likely your dApp name and / or chatbox category. A single spaceName with different threadNames is common practice when building a dApp with multiple Chatbox threads.
threadName String Always A name specific to this Chatbox.
box Object A (and likely B) The box instance returned from running await Box.openBox(address, web3) somewhere in your dApp.
currentUserAddr String (Ethereum Address) A & B The current user's Ethereum address. Passing this will be used to check which messages belong to the current user and can be used for fetching their 3Box profile to render in the Chatbox input UI.
loginFunction Function B A function from your dApp that handles web3 and 3Box login at the global dApp state. This callback will run when a user attempts to join the Chatbox but a box instance doesn't yet exist. Running this function should result in a box instance (from const box = Box.openBox(address, web3)) being passed as the box prop to this component.
ethereum Object window.ethereum C The ethereum object from whichever web3 provider your dApp uses. The enable method on this object will be used to get the current user's Ethereum address and that address will be used to openBox within the current Component context.
popupChat Boolean False Optional A boolean - true - to configure a pop up style chatbox with a button fixed to the bottom right of the window to pop open the chat UI. False will render the component in whichever container you have implemented.
agentProfile Object { chatName: 'Chatbox', imageUrl: null } Optional An object with the name of the chatbox which will appear in the Join thread step and in the header of the chat UI. The default imageUrl is the provided chat icon.
spaceOpts Object Optional Optional parameters for threads (see Docs.3box.io for more info)
threadOpts Object Optional Optional parameters for threads (see Docs.3box.io for more info)
colorTheme String/Boolean False Optional Pass an rgb or hex color string to match the color theme of your application
mute Boolean False Optional Pass false to turn off sound for incoming messages.
showEmoji Boolean False Optional Pass false to turn off the emoji pop up within the chat input UI.
currentUser3BoxProfile Object Optional If the current user has already had their 3Box data fetched at the global dApp state, pass the object returned from Box.getProfile(profileAddress) to avoid an extra request. This data will be rendered in the Chatbox input interface.
userProfileURL Function Defaults to returning user's 3Box profile URL Optional A function that returns a correctly formatted URL of a user's profile on the current platform. The function will be passed an Ethereum address within the component, if needed. A user will be redirected to the URL returned from this function when clicking on the name or Ethereum address associated with the message in the chatbox. This prop is also used in the "Edit profile" link in the header of the Chatbox component.
openOnMount Boolean False Optional Set whether a Popup style Chatbox is open on component mount. This prop only affects desktop browsers.
persistent Boolean False Optional Use persistent thread if set to true.
open Boolean False Optional Make the persistent thread open and anyone can post. If set to False, only members can post.
firstModerator Eth Address Optional The first moderator in persistent thread. This field is important to find the exact thread.
members Array of Eth Address Optional When the thread is private (open is false), add the provided members into the thread. Ignored if the thread is public.
moderators Array of Eth Address Optional When the thread is private (open is false), set the provided moderators for this thread. Ignored if the thread is public.
onLoad({messages, likes, thread}) Function Optional The callback function which is called when the chat messages are loaded for the first time. The chat history of messages and likes, and the thread object will be returned
onUpdate({messages, likes, thread}) Function Optional The callback function which is called when messages arrive. The messages and likes contains all the messages and likes
onError Function Optional The callback function which is called when failed to send message to the chat. Parameters of (error, data, showError) will be sent to onError. error is the error thrown when failed, data contains the info membership data, and showError is the function to show error message which accepts message as its parameter

License

MIT

更多

友情链接

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文