You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: fern/docs/pages/sdks/web/user-identity.mdx
+88-41Lines changed: 88 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,24 +1,22 @@
1
1
Once you have [installed PLuG](./installation), all your users who interact with the widget are created as anonymous users in the DevRev app with a random name since there is no information about the user.
2
2
3
-
For users who are logged into your website, you can identify them in PLuG so they can view their past conversations. Identifying your users also enables more personalized engagement.
3
+
For users who are logged into your website, you can identify them in PLuG to enable them to view their conversation history and receive more personalized engagement.
4
4
5
-
In this flow, you have to generate a session token for every user who visits your website. The session token identifies the customer when they interact with the widget. The session token is generated using the application access token and customer information. It should be generated on your website's back end since the app token needs to be kept hidden.
6
-
7
-
To identify logged-in users, follow these steps:
5
+
To implement user identification, you need to generate a session token for each user who visits your website. This token is created using your application access token combined with customer information, and must be generated on your backend to keep the application token secure.
8
6
9
7
## Generate an application access token
10
8
11
-
1. In DevRev, go to**Settings > Support > PLuG Tokens**through the settings icon on the top-left corner.
12
-
2. Under the **Application access tokens** panel, click**New token**and copy the token that's displayed.
9
+
1. In DevRev, go to**Settings > Support > PLuG Tokens**through the settings icon on the top-left corner.
10
+
2. Under the **Application access tokens** panel, click**New token**and copy the token that's displayed.
13
11
14
12
<Calloutintent="note">
15
-
Ensure you copy your access token, as you will not be able to view it again.
13
+
Ensure you copy your access token, as you cannot view it again.
16
14
</Callout>
17
15
18
16
## Generate a session token
19
17
20
18
<Calloutintent="note">
21
-
For security reasons, this call should be made from the server side so that your AAT isn't exposed.
19
+
For security reasons, this API call must be made from the server side to prevent exposing your application access token (AAT).
22
20
</Callout>
23
21
24
22
Using the `rev_info` method, you can generate and recognize a user within the DevRev system by providing relevant user details. This method enables you to convey information systematically, ensuring alignment between your DevRev CRM and the structured data model. For information regarding terminologies, click [here](https://devrev.ai/docs/product/grow).
|`workspace_ref`| A unique reference for the user's workspace. If not provided, and an account reference is passed, the user is directly attached to the account. | string | ❌ | ✅ |
77
+
|`display_name`| The name of the workspace that's shown on the widget. | string | ❌ | ✅ |
78
+
79
+
**Attributes for [accounts](https://developer.devrev.ai/public/api-reference/accounts/accounts)**
|`account_ref`| A unique reference for the account. | string | ❌ | ✅ |
84
+
|`display_name`| The name of the account that's shown on the widget. | string | ❌ | ✅ |
85
+
|`domains`| The attribute must be unique. Use a format like `devrev.ai`. Inputs like `https://devrev.ai` or `www.devrev.ai` are invalid. | array | ❌ | ✅ |
86
+
|`phone_numbers`| The phone number associated with the account must be in E.164 format. | array | ❌ | ❌ |
60
87
61
88
<Calloutintent="note">
62
-
Ensure that you follow the specified format when providing your phone number.
89
+
Ensure that you follow the specified format when populating phone numbers and domains in the request body.
63
90
</Callout>
64
91
65
92
## Pass custom attributes
@@ -77,32 +104,53 @@ You can pass the custom attributes that are created as shown below:
77
104
78
105
You can pass custom traits, as shown above, not only for `users` but also for `workspaces` and `accounts`.
79
106
80
-
If you prefer a two-level structure, where users are directly associated with an account instead of a workspace, you can provide the `user_ref` and details along with the `account_ref` and details.
107
+
### API status codes and troubleshooting
108
+
109
+
| Status code| Description | Troubleshooting |
110
+
|----------|----------|----------|
111
+
| 200 OK | The request was successful and the session token would be returned in the response. | No troubleshooting required. |
112
+
| 400 Bad Request | The request was invalid. | Check the request body for errors. For fields like domain and phone number, check on their format. |
113
+
| 401 Unauthorized | The request was unauthorized. | Check if the AAT is valid and not expired. |
114
+
| 403 Forbidden | The request was forbidden. | Check the authorization header for errors and make sure the token is a valid AAT. |
115
+
| 404 Not Found | The requested resource could not be found. | Verify the endpoint URL is correct. |
116
+
| 429 Too Many Requests | Rate limit exceeded. | Implement request throttling or wait before retrying. |
117
+
| 500 Internal Server Error | Server encounters an unexpected error. | Wait and try again later. If the issue persists, contact support with the request details and timestamp. |
118
+
119
+
### How resolution works
120
+
121
+
When you send object information to DevRev, the system automatically creates or finds existing contacts, accounts, and workspaces.
122
+
123
+
DevRev offers three ways to structure your customer's data:
81
124
82
-
**Attributes for users**
125
+
| Hierarchy Type | Documents Created | What to Include | Use Case |
|**Single-level**| Contacts only | Only user information | Recommended for most B2C cases |
128
+
|**Two-level**| Accounts and Contacts linked to the account | User and account information | Recommended for most B2B cases |
129
+
|**Three-level**| Account with linked workspaces and contacts | User, workspace and account information | Used for B2B cases but only recommended if your business model requires workspace organization |
83
130
84
-
|Attributes |Description |Type |
85
-
|---|---|---|
86
-
|`user_ref`|A unique user reference that the DevRev app uses for identifying your users. This parameter is required. |string |
87
-
|`email`|The email address of the customer. It's used for sending email notifications of any support messages. |string |
88
-
|`display_name`|The name of the user that's shown on the widget. |string |
89
-
|`phone_numbers`|The mobile number of the customer. |array |
131
+
**What happens when you send different combinations:**
90
132
91
-
**Attributes for workspaces**
133
+
User reference:
134
+
- A user reference is mandatory, ensuring its constant presence.
135
+
- If a user with the provided reference doesn't exist, the system automatically creates the user.
92
136
93
-
|Attributes |Description |Type |
94
-
|---|---|---|
95
-
|`workspace_ref`|A unique reference for the user's workspace. If not provided, and an account reference is passed, the user is directly attached to the account. |string |
96
-
|`display_name`|The name of the workspace that's shown on the widget. |string |
137
+
This approach ensures efficient management and integration of objects within the DevOrg.
| ❌ | ✅ | (Most common Usage) \nIf the account doesn't exist: An account is created, and the user is linked with the account. |
142
+
| ❌ | ❌ | No action on account or workspace. The user is returned. |
143
+
| ✅ | ✅ | If neither exists: System creates the account first, then creates the workspace. User is linked to both.<br />If account exists but workspace doesn't: System creates the workspace under the existing account. User is linked to both.<br />If workspace exists under different account: System returns an error, as workspaces cannot be a part of 2 accounts. |
144
+
| ✅ | ❌ | If workspace doesn't exist: System creates a new account and workspace (if needed). User is linked to both. |
99
145
100
-
|Attributes |Description |Type |
101
-
|---|---|---|
102
-
|`account_ref`|A unique reference for the account. |string |
103
-
|`display_name`| The name of the account that's shown on the widget. |string |
104
-
|`domains`|The domain names of the accounts that the users belongs to. |array |
105
-
|`phone_numbers`|The phone number associated with the account. |array |
146
+
147
+
148
+
### Best practices
149
+
150
+
- Populate user traits like email and display name to make users identifiable and to prevent duplicate users across integrations.
151
+
- Maintain consistent unique identifiers across your system.
152
+
- Follow the specified formats for phone numbers and domains.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments