Skip to content

Commit ead3e62

Browse files
Atul-Butolanikhiltidke101bc-devrev
authored
Update methods.mdx (#86)
* Update methods.mdx ISS-94327 * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx Spelling. * fixed spelling and capitalization * Fern upgrade * tagged code phrase * Revert "Fern upgrade" This reverts commit 60736a4. * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx * Update methods.mdx --------- Co-authored-by: Nikhil <[email protected]> Co-authored-by: Ben Colborn <[email protected]> Co-authored-by: Ben Colborn <[email protected]>
1 parent ee90ac0 commit ead3e62

File tree

1 file changed

+134
-83
lines changed

1 file changed

+134
-83
lines changed

‎fern/docs/pages/plug-sdk/methods.mdx

Lines changed: 134 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,197 @@
1-
Our PLuG widget SDK is a powerful tool to further enhance our widget on your website or application. With our SDK, you are empowered to create a dynamic and personalized user experience. Let's get started.
1+
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.
22

3-
## Methods
3+
## Initialize SDK
44

5-
- `plugSDK.init()` Initialize the PLuG chat widget.
5+
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.
66

7-
- `plugSDK.initSearchAgent()` Initialize PLuG search agent.
7+
```jsx
8+
useEffect(() => {
9+
window.plugSDK.init({
10+
app_id: <your_unique_app_id>,
11+
});
12+
}, []);
13+
```
14+
The `init()` method can accept multiple inputs, which are explained below:
15+
16+
|Input parameter |Description |Values |
17+
|---|---|---|
18+
|`app_id` |The unique identifier for your PLuG SDK. This parameter is required. |String |
19+
|`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) |
20+
|`enable_default_launcher` |Show/hide the default PLuG widget launcher. |Boolean (True or False) |
21+
|`session_recording_key` |Identifies your session recording account and is required to enable the SDK session recording features. |String |
22+
|`enable_session_recording` |Instructs the widget to determine whether to start the session recording. |Boolean (True or False) |
23+
|`session_token` |Identifies the user interacting with your app. |String |
24+
|`primary_text_color` |The color of the launcher, button text for new tickets and conversations, conversation user text, and more. It must be a valid hex color code, such as `#f0f0f0`. |String |
25+
|`session_recording_options` |Options for recording observability sessions. |Refer to [Session recording options](https://devrev.ai/docs/plug/session-recording) |
26+
|`accent_color` |The accent color of the PLuG affects the launcher, new ticket and conversation buttons, conversation user text, and more. |String |
27+
|`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) |
28+
|`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;}` |
29+
|`theme` |The color scheme for the launcher and widget. |`light` or `dark` |
30+
|`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 |
31+
32+
<Callout intent="note">
33+
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.
34+
</Callout>
835

9-
- `plugSDK.shutdown()` End the user session which is currently initialized in PLuG widget.
36+
## Toggle widget theme
1037

11-
- `plugSDK.toggleWidget()` Open/close the chat widget.
38+
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.
1239

13-
- `plugSDK.toggleSearchAgent()` Open/close the search agent.
40+
The method accepts the input options: `light` and `dark`.
1441

15-
- `plugSDK.onEvent()` Perform specific actions based on the payload type received from the PLuG widget.
42+
```jsx
43+
window.plugSDK.toggleTheme('light | dark');
44+
```
1645

17-
- `plugSDK.toggleTheme('light/dark')` Toggle PLuG widget theme.
46+
Calling `toggleTheme()` switches between the current themes. Specifying a theme as a parameter allows you to toggle directly to that specific theme.
1847

19-
- `plugSDK.toggleWidget(true, 'create_conversation', {startConversationContent: 'Hi',});` Start a conversation.
48+
<Callout intent="note">
49+
The theme specified in this method takes precedence over the theme configured in the PLuG settings in your DevRev app.
50+
</Callout>
2051

21-
- `plugSDK.prefillSearchQuery(query:"string")` Prefill the search input of the search agent.
52+
## Toggle widget
2253

23-
## Initialize chat
54+
The `toggleWidget` method allows you to control the visibility of the PLuG chat widget.
2455

25-
Calling the `init()` method initializes the PLuG chat widget on your website. Initializing the PLuG widget is necessary for you to perform any other actions on the PLuG widget SDK.
56+
Passing `true` opens the chat widget.
2657

27-
```jsx
28-
useEffect(() => {
29-
window.plugSDK.init({
30-
app_id: <your_unique_app_id>,
31-
});
32-
}, []);
33-
```
58+
Passing `false` closes the chat widget.
3459

35-
<Callout intent="info">
36-
When React is using `Strict` mode, you might get a warning message from `window.plugSDK.init()` being called multiple times. These errors won't impact the installation and functioning of the widget.
37-
</Callout>
60+
```jsx
61+
window.plugSDK.toggleWidget(true);
62+
```
3863

39-
## Initialize search
64+
## Take action from PLuG chat events
4065

41-
Calling the `initSearchAgent()` method initializes the PLuG Search agent on your website. Initializing search is necessary for you to perform any other actions on the PLuG widget SDK.
66+
This method allows you to listen for events from the PLuG widget. Below are the available values for `PAYLOAD_TYPE`.
67+
- `ON_PLUG_WIDGET_CLOSED`: Triggered when the PLuG widget is closed.
68+
- `ON_PLUG_WIDGET_OPENED`: Triggered when the PLuG widget is opened.
69+
- `ON_PLUG_WIDGET_READY`: Triggered when the PLuG widget is ready.
70+
- `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.
71+
- `ON_CONVERSATION_START`: Indicates that the user has started a new conversation.
72+
- `ON_SEARCH_AGENT_QUERY`: Indicates that a new search query has been made in the PLuG search agent.
73+
- `ON_OBSERVABILITY_READY`: Triggered when the session analytics capabilities of PLuG are initialized.
4274

4375
```jsx
4476
useEffect(() => {
45-
window.plugSDK.init({
46-
app_id: '<your_unique_app_id>',
47-
disable_plug_chat_window: true,
48-
});
49-
5077
window.plugSDK.onEvent((payload) => {
51-
if (payload.type === 'ON_PLUG_WIDGET_READY') {
52-
window.plugSDK.initSearchAgent();
78+
if (payload.type === PAYLOAD_TYPE) {
79+
//Your logic goes here
5380
}
5481
});
5582
}, []);
5683
```
5784

58-
## Shutdown the widget
85+
## Check widget status
5986

60-
The `shutdown()` method is helpful when you want to end the user session which is currently initialized in the PLuG widget. You can use this method to clear your users' conversations and tickets when they log out of your application.
87+
Use `isWidgetOpen` to determine whether your chat widget is currently open or closed.
6188

6289
```jsx
63-
await window.plugSDK.shutdown();
90+
window.plugSDK.isWidgetOpen
6491
```
6592

66-
After calling the `shutdown()` method, you can call the `init()` method to reinitialize PLuG widget on your website if you wish to showcase the PLuG widget again in the logged out version of your application.
93+
This returns true if the chat widget is open and false if it is closed.
6794

68-
<Callout intent="info">
69-
Once the `shutdown()` method is called, all the other functionality in the widget such as session recording or Nudges is also be stopped. You need to reinitialize the widget again to have these features active.
70-
</Callout>
71-
72-
<iframe src="https://codesandbox.io/embed/shutdown-plug-sdk-sstn8g?fontsize=14&hidenavigation=1&theme=dark"
73-
style={{width:'100%', height:'600px', border:'0', borderRadius: '4px', overflow:'hidden',}}
74-
title="Toggle_Plug_with_Button"
75-
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
76-
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
77-
></iframe>
95+
## Start conversation
7896

79-
## Open or close the widget
97+
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.
8098

81-
To control whether the PLuG widget launcher screen is open, you should use either the `togglewidget()` method with a boolean value or the `toggleSearchAgent()` method, depending on which PLuG instance you are using.
99+
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.
82100

83101
```jsx
84-
window.plugSDK.toggleWidget(true);
85-
window.plugSDK.toggleSearchAgent(true);
102+
plugSDK.toggleWidget(true, 'create_conversation', {
103+
startConversationContent: 'Hi',
104+
});
86105
```
87106

88-
<iframe src="https://codesandbox.io/embed/toggle-plug-with-button-nnkmk3?fontsize=14&hidenavigation=1&module=%2Fsrc%2FTogglePlug.js&theme=dark&view=preview&hidedevtools=1"
89-
style={{width:'100%', height:'600px', border:'0', borderRadius: '4px', overflow:'hidden',}}
90-
title="Toggle_Plug_with_Button"
91-
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
92-
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
93-
></iframe>
107+
## Shutdown
94108

95-
## Take actions from events
109+
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.
96110

97-
This method can be used to listen to events coming from the PLuG widget. The following are the different `PAYLOAD_TYPES`.
111+
```jsx
112+
await window.plugSDK.shutdown();
113+
```
114+
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.
98115

99-
- `ON_PLUG_WIDGET_CLOSED` The PLuG widget is closed.
116+
<Callout intent="note">
117+
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.
118+
</Callout>
100119

101-
- `ON_PLUG_WIDGET_OPENED` The PLuG widget is opened.
120+
## Initialize the search agent
102121

103-
- `ON_PLUG_WIDGET_READY` The PLuG widget is ready.
104-
-
105-
- `ON_PLUG_WIDGET_UNREAD_COUNT_CHANGE` The user receives a new message to their PLuG. You can also listen to the number of unread messages and display that to your user.
122+
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.
106123

107124
```jsx
108125
useEffect(() => {
126+
window.plugSDK.init({
127+
app_id: '<your_unique_app_id>',
128+
disable_plug_chat_window: true,
129+
});
130+
109131
window.plugSDK.onEvent((payload) => {
110-
if (payload.type === PAYLOAD_TYPE) {
111-
//Your logic goes here
132+
if (payload.type === 'ON_PLUG_WIDGET_READY') {
133+
window.plugSDK.initSearchAgent();
112134
}
113135
});
114136
}, []);
115137
```
116138

117-
<iframe src="https://codesandbox.io/embed/events-rendered-7rhzj7?fontsize=14&hidenavigation=1&module=%2Fsrc%2FOnEvents.js&theme=dark&view=preview&hidedevtools=1"
118-
style={{width:'100%', height:'600px', border:'0', borderRadius: '4px', overflow:'hidden',}}
119-
title="Events_Rendered"
120-
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
121-
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
122-
></iframe>
139+
## Toggle search agent
123140

124-
## Toggle theme
141+
The `toggleSearchAgent` method allows you to control the visibility of the search agent.
125142

126-
The toggle theme method allows you to dynamically modify the PLuG SDK's theme, even after initializing the PLuG widget. This functionality enables real-time adjustments to the PLuG widget's theme based on diverse themes preferred by your users.
143+
If no input is provided, the method toggles the search bar: opening it if it's closed, and closing it if it's open.
127144

128-
The method accepts two inputs: `light` and `dark`.
129145
```jsx
130-
window.plugSDK.toggleTheme('light | dark');
146+
window.plugSDK.toggleSearchAgent(true);
131147
```
132-
The parameter is optional; calling `toggleTheme()` toggles the current theme, and specifying a theme as a parameter allows toggling for that specific theme.
133148

134-
## Start conversation
149+
## Prefill search query in search agent
150+
151+
Use the `prefillSearchQuery` method to prefill a search query when opening and initializing the search agent.
135152

136-
This method is utilized to open the PLuG widget with the conversation creation view activated. It essentially replicates the action of clicking the **Send us a message** button, launching the widget directly to the conversation initiation screen.
153+
```jsx
154+
window.plugSDK.prefillSearchQuery("search_query");
155+
```
156+
157+
## Add session properties
137158

138-
The method also accepts an optional input parameter, allowing you to pre-fill a message in the conversation creation screen. This provides your users with a prompt to initiate a conversation with your team.
159+
The `addSessionProperties` method is used to add properties to the session in the form of a key-value map.
139160

140161
```jsx
141-
plugSDK.toggleWidget(true, 'create_conversation', {
142-
startConversationContent: 'Hi',
143-
});
162+
window.plugSDK.addSessionProperties({
163+
city: 'Bengaluru',
164+
region: 'us-east'
165+
});
166+
```
167+
168+
## Track events
169+
170+
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).
171+
172+
```jsx
173+
window.plugSDK.trackEvent(event_name, properties)
144174
```
145175

146-
Looking for something more? Reach out to us through our own PLuG widget in the bottom right of this screen and we would be happy to assist you.
176+
Sample code:
177+
178+
```jsx
179+
// Sample code for the trackEvent method:
180+
var properties = {
181+
"name" : "John Doe",
182+
"plan" : "Starter",
183+
"payment_method" : "Credit Card",
184+
"expiry_date" : "2024-12-12"
185+
}
186+
window.plugSDK.trackEvent("signed_up",properties)
187+
```
188+
189+
To learn more about tracking events, visit [Track events](/plug-sdk/track-events).
190+
191+
## Restart session recording
192+
193+
The `restartSessionRecording` method is used to restart session recording.
194+
195+
```jsx
196+
window.plugSDK.restartSessionRecording();
197+
```

0 commit comments

Comments
 (0)