Update methods.mdx #86
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,146 +1,199 @@ | ||||||
| The PLuG SDK is a robust tool designed to elevate your website or application by enhancing our widget’s capabilities. With our SDK, you can integrate our feature-rich widget, creating a dynamic and personalized user experience. | ||||||
|
|
||||||
| ## Methods | ||||||
|
|
||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ## Initialize SDK | ||||||
|
|
||||||
| To get started with the PLuG SDK on your website, call the `init()` method. This method is essential for enabling the SDK’s functionality, including session recording, the chat widget, and the search agent. Initialization is required before you can perform any other actions using the PLuG SDK. | ||||||
|
|
||||||
| ```jsx | ||||||
| useEffect(() => { | ||||||
| window.plugSDK.init({ | ||||||
| app_id: <your_unique_app_id>, | ||||||
| }); | ||||||
| }, []); | ||||||
| ``` | ||||||
| The `init()` method can accept multiple inputs, which are explained below: | ||||||
|
|
||||||
| |Input parameter |Description |Values | | ||||||
| |---|---|---| | ||||||
| |`app_id` |This is the unique identifier for your PLuG SDK. This is a mandatory parameter. |String | | ||||||
| |`disable_plug_chat_window` |The chat widget is enabled by default. Use this option if you want to disable the chat widget. |Boolean (True or False) | | ||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| |`enable_default_launcher` |Show/hide the default PLuG widget launcher. |Boolean (True or False) | | ||||||
| |`session_recording_key` |This key identifies your session recording account and is required to enable the PLuG SDK session recording features. |String | | ||||||
| |`enable_session_recording` |This instructs the widget to determine whether to start the session recording. |Boolean (True or False) | | ||||||
| |`session_token` |This unique token identifies the user interacting with your app. |String | | ||||||
| |`primary_text_color` |This determines the launcher color, button text for new tickets and conversations, conversation user text, and more. It should be a valid hex code, such as #f0f0f0. |String | | ||||||
| |`session_recording_options` |Options for recording observability sessions. |To view the values, see [Session recording options](https://devrev.ai/docs/plug/session-recording) | | ||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| |`accent_color` |The accent color of the PLuG affects the launcher, new ticket and conversation buttons, conversation user text, and more. |String | | ||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| |`custom_launcher_selector` |A CSS selector string is used to match the element to which the widget will be attached. You can also set this selector from the PLuG settings on app.devrev.ai. If both sources are set, this value will be considered the definitive source. |Boolean (True or False) | | ||||||
| |`spacing` |Padding from the launcher: This padding can also be set in the plug settings on app.devrev.ai. If a value is specified in both places, this value will be considered the definitive source. Bottom: Padding from the bottom of the launcher. Side: Spacing from the sides of the launcher |object `{bottom: string; side: string;}` | | ||||||
|
There was a problem hiding this comment. 🚫 [EkLine] reported by reviewdog 🐶
Suggested change
|
||||||
| |`theme` |The color scheme for the launcher and widget. |light or dark | | ||||||
| |`widget_alignment` |The PLuG widget can be positioned on either the left or right side of the launcher. You can also adjust the widget alignment through the plug settings at app.devrev.ai. If alignment settings are configured in both places, the value from app.devrev.ai will override the launcher setting. |left or right | | ||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| <Callout intent="note"> | ||||||
| When React is in Strict mode, you may receive a warning about `window.plugSDK.init()` being called multiple times. These warnings do not affect the widget's installation or functionality. | ||||||
| </Callout> | ||||||
|
|
||||||
| ## Toggle widget theme | ||||||
|
|
||||||
| The toggle theme method lets you dynamically adjust the PLuG SDK’s theme, even after the widget has been initialized. This feature allows for real-time theme changes based on your users' preferences. | ||||||
|
|
||||||
| The method accepts the input options: `light` and `dark`. | ||||||
|
|
||||||
| ```jsx | ||||||
| window.plugSDK.toggleTheme('light | dark'); | ||||||
| ``` | ||||||
|
|
||||||
| The parameter is optional; calling `toggleTheme()` will switch between the current themes. Specifying a theme as a parameter allows you to toggle directly to that specific theme. | ||||||
|
|
||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| <Callout intent="note"> | ||||||
| The theme specified in this method takes precedence over the theme configured in the PLuG settings in your DevRev app. | ||||||
| </Callout> | ||||||
|
|
||||||
| ## Toggle widget | ||||||
|
|
||||||
| The `toggleWidget` method allows you to control the visibility of the PLuG chat widget. | ||||||
|
|
||||||
| Passing input = true opens the chat widget. | ||||||
|
|
||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| Passing input = false closes the chat widget. | ||||||
|
|
||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ```jsx | ||||||
| window.plugSDK.toggleWidget(true); | ||||||
| ``` | ||||||
|
|
||||||
| ## Take action from PLuG chat events | ||||||
|
|
||||||
| This method allows you to listen for events from the PLuG widget. Below are the available `PAYLOAD_TYPES`. | ||||||
| - `ON_PLUG_WIDGET_CLOSED`: Triggered when the PLuG widget is closed. | ||||||
Atul-Butola marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| - `ON_PLUG_WIDGET_OPENED`: Triggered when the PLuG widget is opened. | ||||||
| - `ON_PLUG_WIDGET_READY`: Triggered when the PLuG widget is ready. | ||||||
| - `ON_PLUG_WIDGET_UNREAD_COUNT_CHANGE`: Triggered when the user receives a new message. You can also track the number of unread messages and display them to the user. | ||||||
| - `ON_CONVERSATION_START`: Indicates that the user has started a new conversation. | ||||||
| - `ON_SEARCH_AGENT_QUERY`: Indicates that a new search query has been made in the PLuG search agent. | ||||||
| - `ON_OBSERVABILITY_READY`: Triggered when the session analytics capabilities of PLuG are initialized. | ||||||
|
|
||||||
| ```jsx | ||||||
| useEffect(() => { | ||||||
| window.plugSDK.onEvent((payload) => { | ||||||
| if (payload.type === PAYLOAD_TYPE) { | ||||||
| //Your logic goes here | ||||||
| } | ||||||
| }); | ||||||
| }, []); | ||||||
| ``` | ||||||
|
|
||||||
| ## Check widget status | ||||||
|
|
||||||
| Use `isWidgetOpen` to determine whether your chat widget is currently open or closed. | ||||||
|
|
||||||
| ```jsx | ||||||
| window.plugSDK.isWidgetOpen | ||||||
| ``` | ||||||
|
|
||||||
| This returns true if the chat widget is open and false if it is closed. | ||||||
|
|
||||||
| ## Start conversation | ||||||
|
|
||||||
| The `startConversationContent` method opens the PLuG widget directly to the conversation creation view. It replicates the action of clicking the **Send us a message** button, launching the widget to the conversation initiation screen. | ||||||
|
|
||||||
| This method also accepts an optional input parameter to pre-fill a message on the conversation creation screen, providing your users with a prompt to start a conversation with your team. | ||||||
|
|
||||||
| ```jsx | ||||||
| plugSDK.toggleWidget(true, 'create_conversation', { | ||||||
| startConversationContent: 'Hi', | ||||||
| }); | ||||||
| ``` | ||||||
|
|
||||||
| ## Shutdown | ||||||
|
|
||||||
| The `shutdown()` method is used to end the current user session in the PLuG widget. It allows you to clear users' conversations and tickets when they log out of your application. | ||||||
|
|
||||||
| ```jsx | ||||||
| await window.plugSDK.shutdown(); | ||||||
| ``` | ||||||
| After calling the `shutdown()` method, you can use the `init()` method to reinitialize the PLuG widget on your website if you want to display it again in the logged-out version of your application. | ||||||
|
|
||||||
| <Callout intent="note"> | ||||||
| Once the `shutdown()` method is called, all other widget functionalities, such as session recording and Nudges, will also be stopped. You will need to reinitialize the widget to reactivate these features. | ||||||
| </Callout> | ||||||
|
There was a problem hiding this comment. 📝 [EkLine] reported by reviewdog 🐶
Suggested change
|
||||||
|
|
||||||
| ## Initialize the search agent | ||||||
|
|
||||||
| Calling the `initSearchAgent()` method sets up the PLuG search agent on your website. This initialization is required before performing any other actions with the PLuG widget SDK. | ||||||
|
|
||||||
| ```jsx | ||||||
| useEffect(() => { | ||||||
| window.plugSDK.init({ | ||||||
| app_id: '<your_unique_app_id>', | ||||||
| disable_plug_chat_window: true, | ||||||
| }); | ||||||
|
|
||||||
| window.plugSDK.onEvent((payload) => { | ||||||
| if (payload.type === 'ON_PLUG_WIDGET_READY') { | ||||||
| window.plugSDK.initSearchAgent(); | ||||||
| } | ||||||
| }); | ||||||
| }, []); | ||||||
| ``` | ||||||
|
|
||||||
| ## Toggle search agent | ||||||
|
|
||||||
| The `toggleSearchAgent` method allows you to control the visibility of the search agent. | ||||||
|
|
||||||
| If no input is provided, the method toggles the search bar: opening it if it's closed, and closing it if it's open. | ||||||
|
|
||||||
| ```jsx | ||||||
| window.plugSDK.toggleSearchAgent(true); | ||||||
| ``` | ||||||
|
|
||||||
| ## Prefill search query in search agent | ||||||
|
|
||||||
| Use the `prefillSearchQuery` method to prefill a search query when opening and initializing the search agent. | ||||||
|
|
||||||
| ```jsx | ||||||
| window.plugSDK.prefillSearchQuery("search_query"); | ||||||
| ``` | ||||||
|
|
||||||
| ## Add session properties | ||||||
|
|
||||||
| The `addSessionProperties` method is used to add properties to the session in the form of a key-value map. | ||||||
|
|
||||||
| ```jsx | ||||||
| window.plugSDK.addSessionProperties({ | ||||||
| city: 'Bengaluru', | ||||||
| region: 'us-east' | ||||||
| }); | ||||||
| ``` | ||||||
|
|
||||||
| ## Track events | ||||||
|
|
||||||
| To track user events using PLuG, utilize the `trackEvent` method available in the PLuG SDK. This method automatically links the event to the active user profile within the widget. For more details on user identification within the PLuG widget, refer to [Identify your users with PLuG](https://devrev.ai/docs/plug/identify-web-user). | ||||||
|
|
||||||
|
There was a problem hiding this comment. 🚫 [EkLine] reported by reviewdog 🐶 |
||||||
| ```jsx | ||||||
| window.plugSDK.trackEvent(event_name, properties) | ||||||
| ``` | ||||||
|
|
||||||
| Sample code: | ||||||
|
|
||||||
| ```jsx | ||||||
| // Sample code for the trackEvent method: | ||||||
| var properties = { | ||||||
| "name" : "John Doe", | ||||||
| "plan" : "Starter", | ||||||
| "payment_method" : "Credit Card", | ||||||
| "expiry_date" : "2024-12-12" | ||||||
| } | ||||||
| window.plugSDK.trackEvent("signed_up",properties) | ||||||
| ``` | ||||||
|
|
||||||
| To learn more about tracking events, visit [Track events](/plug-sdk/track-events). | ||||||
|
|
||||||
| ## Restart session recording | ||||||
|
|
||||||
| The `restartSessionRecording` method is used to restart session recording. | ||||||
|
|
||||||
| ```jsx | ||||||
| window.plugSDK.restartSessionRecording(); | ||||||
| ``` | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.