diff --git a/packages/react-use-zendesk/CHANGELOG.md b/packages/react-use-zendesk/CHANGELOG.md index 1bce3e6..8b9a625 100644 --- a/packages/react-use-zendesk/CHANGELOG.md +++ b/packages/react-use-zendesk/CHANGELOG.md @@ -1,5 +1,11 @@ # react-use-zendesk +## 1.0.1 + +### Patch Changes + +- update readme in library package + ## 1.0.0 ### Major Changes diff --git a/packages/react-use-zendesk/README.md b/packages/react-use-zendesk/README.md index 8eb5204..bb817c8 100644 --- a/packages/react-use-zendesk/README.md +++ b/packages/react-use-zendesk/README.md @@ -1,2 +1,144 @@ +

react-use-zendesk

+

React Zendesk Web Widget integration written in typescript.

-## Please read [Readme](https://github.com/multivoltage/react-use-zendesk/blob/main/README.md) \ No newline at end of file +## Features +* Web Widget api available. Please see [Zendesk docs](https://developer.zendesk.com/api-reference/widget-messaging/web/core/) +* TypeScript support +* Only 25kb +* Working on NextJS/Gatsby + + +## ⚠️ Web widget vs Web Widget (classic) ⚠️ + + +This library offers API only for the new version called Web widget. +For more information please read [the comparison](https://support.zendesk.com/hc/en-us/articles/4429429087002-Comparing-the-Zendesk-Web-Widgets) + +## Installation + +```sh +npm i react-use-zendesk +``` + +## Usage +```ts + + +import { ZendeskProvider, useZendesk } from 'react-use-zendesk'; + +const App = () => ( + + + +); + +const Home = () => { + const { open, unreadMessages } = useZendesk(); + + return
+ you have ${unreadMessages} messages! + +
; +}; +``` + +## API +* [ZendeskProvider](#ZendeskProvider) +* [useZendesk](#useZendesk) + +### ZendeskProvider +library uses `ZendeskProvider` to initialize the `window.zE` instance. If any listeners are passed, the provider will make sure these callbacks are attached. + +Place the `ZendeskProvider` as high as possible in your application. This will make sure you can call `useZendesk` anywhere. Remember that the provider under the hood use React.context, so in Next JS you have to declare `"use client"` for the component. + +#### Props +| name | type | description | required | default | +|---------------------|------------------|-----------------------------------------------------------------------------------------|----------|---------| +| apiKey | string | api key of your Zendesk account | X | | +| children | React.ReactNode | React children | true | | +| onOpen | () => void | triggered when the Widget opens (chat is visible). Please see `isOpen` field if you want to get chat state by hooks | | | +| onClose | () => void | triggered when the Widget closes (chat is hidden). Please see `isOpen` field if you want to get chat state by hooks | | | +| onUnreadMessages | (count; number) => void | triggered when the current number of unread messages changes. If attached, Zendesk triggers this callback after initialization. Please see `unreadMessages` field if you want to get the number by hook | | | + + +#### Example +```ts +const App = () => { + const handleOpen = () => console.log('Chat become visible'); + const handleClose = () => console.log('Chat become hidden'); + const handleUnreadMessages = (count: number) => console.log('You have',count,'messages to read'); + + return ( + +

fake child example

+ + ); +}; +``` + +### useZendesk +Used to retrieve all methods bundled with Zendesk Web Widget. These are based on the official [Zendesk docs](https://developer.zendesk.com/api-reference/widget-messaging/web/core/). For each api if you want to get more details please refer to Zendesk Docs. +Library add some useful fields. + + Make sure `ZendeskProvider` is wrapped around your component when calling `useZendesk()`. + +**Remark** - You can't use `useZendesk()` in the same component where `ZendeskProvider` is initialized. + +#### API + +| name | type | description | +|-----------------|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| isOpen | boolean | the visibilty status if chat. If you call `open` after `hide` this flag will be `false` | | +| show | () => void | Displays the widget. The widget is displayed by default on page load. You don't need to call show to display the widget unless you use hide. +| hide | () => void | Hides all parts of the widget from the page. You can invoke it before or after page load. +| open | () => void | Opens the messaging Web Widget. Chat become visible +| close | () => void | Closes the messaging Web Widget +| setLocale | (newLocale: string) => void | Sets the locale of the messaging Web Widget. +| setZIndex | (newZIndex: number) => void | Sets the CSS property z-index on all the iframes for the messaging WebWidget. +| setCookies | (isEnabled: boolean) => void | The messaging Web Widget uses a mixture of cookies as well as local and session storage in order to function. +| setConversationFields | (conversationFields: ZendeskConversationField[]) => void | Allows values for conversation fields to be set in the client to add contextual data about the conversation. +| setConversationTags | (conversationTags: string[]) => void | Allows custom conversation tags to be set in the client to add contextual data about the conversation +| loginUser | (jwtToken: string) => void | If your application has a login flow, or if a user needs to access the same conversation from multiple devices +| logoutUser | () => void | Your app may have a logout function that brings users back to a login screen. In this case, revert the messaging Web Widget to a pre-login state +| isOpen | boolean | this flag indicates if chat is visible or hidden. Derivated from from `onOpen` and `onCLose` +| unreadMessages | number / undefined | this flag indicates number of unread messages . Derivated from from `onUnreadMessages`. Before internal callback this flag is `undefined` | + + +#### Example +```ts +import { ZendeskProvider, useZendesk } from 'react-use-zendesk'; + +const App = () => ( + + + +); + +const Home = () => { + const { + open, + close, + isOpen, + unreadMessages, + setLocale + } = useZendesk(); + + const changeLocale = () => setLocale("es") + + return ( + <> +

you have {unreadMessages} unread messages

+

your chat is ${isOpen ? "visible" : "hidden"}

+ + + ); +}; +``` + +## Examples +Go to [examples](https://github.com/multivoltage/react-use-zendesk/tree/main/apps/docs) to check out some integrations ( NextJS...). diff --git a/packages/react-use-zendesk/package.json b/packages/react-use-zendesk/package.json index 3353a19..c10bdfc 100644 --- a/packages/react-use-zendesk/package.json +++ b/packages/react-use-zendesk/package.json @@ -6,7 +6,7 @@ }, "description": "React Zendesk Web Widget integration written in typescript", "license": "MIT", - "version": "1.0.0", + "version": "1.0.1", "repository": { "type": "git", "url": "https://github.com/multivoltage/react-use-zendesk"