Identify your users with PLuG

Once you have installed PLuG, 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.

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.

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.

Generate an application access token

1. In DevRev, go to Settings > Support > PLuG Tokens through the settings icon on the top-left corner.
2. Under the Application access tokens panel, click New token and copy the token that’s displayed.

Generate a session token

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.

$
curl --location 'https://api.devrev.ai/auth-tokens.create' \
>
--header 'accept: application/json, text/plain, */*' \
>
--header 'authorization: <AAT>' \
>
--header 'content-type: application/json' \
>
--data-raw '{
>
    "rev_info": {
>
        "user_ref": "example@devrev.ai",
>
        "account_ref": "devrev.ai",
>
        "workspace_ref": "devrev-dev",
>
        "user_traits": {
>
            "email": "test-user@devrev.ai",
>
            "display_name": "Devrev Test User",
>
            "phone_numbers": ["+911122334455"],
>
            "custom_fields": {
>
               "tnt__<field1_name>": "value 1"
>
            }
>
        },
>
        "workspace_traits": {
>
            "display_name": "Devrev Dev",
>
            "custom_fields": {}
>
        },
>
        "account_traits": {
>
            "display_name": "Devrev",
>
            "domains": [
>
                "devrev.ai"
>
            ],
>
            "custom_fields": {
>
                "tnt__<field2_name>": "value x"
>
            }
>
        }
>
    }
>
}'

Attributes for users

• While email uniqueness is subjected to organization preferences, it is not recommended to mark emails as non-unique.

Attributes for workspaces

Attributes for accounts

Pass custom attributes

To create custom attributes, see Object customization.

You can pass the custom attributes that are created as shown below:

1
"custom_fields": {
2
  "tnt__custom_attribute_name1": <value>,
3
  "tnt__custom_attribute_name2": <value>,
4
}

You can pass custom traits, as shown above, not only for users but also for workspaces and accounts.

API status codes and troubleshooting

How resolution works

When you send object information to DevRev, the system automatically creates or finds existing contacts, accounts, and workspaces.

DevRev offers three ways to structure your customer’s data:

What happens when you send different combinations:

User reference:

• A user reference is mandatory, ensuring its constant presence.
• If a user with the provided reference doesn’t exist, the system automatically creates the user.

This approach ensures efficient management and integration of objects within the DevOrg.

Best practices

• Populate user traits like email and display name to make users identifiable and to prevent duplicate users across integrations.
• Maintain consistent unique identifiers across your system.
• Follow the specified formats for phone numbers and domains.
• Keep your application access token secure.

Pass the session token

While initializing the PLuG widget you pass the session token for DevRev to identify this user and thereby make the widget more customized for the user and their context.

1
// You can generate this session token using the above API in your backend
2
const sessionToken = '<SESSION_TOKEN>'
3
<script type="text/javascript" src="https://plug-platform.devrev.ai/static/plug.js"></script>
4
<script>
5
  (() => {
6
    window.plugSDK.init({
7
      app_id: '<your_unique_app_id>',
8
      session_token: sessionToken
9
    })
10
  })();
11
</script>

Identify users without session token

You can also pass the identifiers in the plugSDK.init option without generating the session token.

1
window.plugSDK.init({
2
  app_id: appId,
3
  identity: {
4
    user_ref: userRef,
5
    user_traits: { // Optional user details
6
      custom_fields?: object,
7
      display_name: 'John Doe',
8
      email: 'john@example.com',
9
      phone_numbers: ['+1234567890']
10
    }
11
  }
12
});

You can add or update the data in user_traits by using the updateIdentity method on the PLuG SDK. Attached is a sample code snippet for the same.

1
window.plugSDK.updateIdentity({
2
  user_traits: {
3
    custom_fields?: object; // optional
4
    display_name?: string; // optional
5
    email?: string; // optional
6
    phone_numbers?: string[]; // optional
7
  }
8
})

Changing the user identity

As described in the above sections, to identify a user, you need to initialize the PLuG SDK with the relevant user information. PLuG can only be initialized once per page load.

In most cases, this works as expected—user identification typically happens after login or signup, which causes a page reload and clears any previous PLuG instance.

However, if your application needs to update the user identity without a full page refresh, you need to explicitly delete the existing PLuG instance before initializing it again with the new user information.

1
// Delete the existing PLuG instance if it exists
2
if (window.plugSDK.isPlugInitialized) {
3
  window.plugSDK.shutdown();
4
}
5
6
// Re-initialize PLuG
7
window.plugSDK.init({
8
  app_id: appId,
9
10
  // With session token
11
  session_token: sessionToken,
12
13
  // Or without session token
14
  identity: {},
15
});

If you’re using the PLuG SDK for recording user sessions, calling the shutdown() method will stop the ongoing session recording. Re-initializing with the init() method will then start a new session recording. To avoid losing continuity, you can pass the details of the ongoing session recording when re-initializing PLuG.

1
// Get the ongoing session details
2
const { sessionId, tabId } = window.plugSDK.getSessionDetails();
3
4
if (window.plugSDK.isPlugInitialized) {
5
  window.plugSDK.shutdown();
6
}
7
window.plugSDK.init({
8
  app_id: appId,
9
  
10
  // Pass the session details
11
  session_recording_options: {
12
    sessionDetails: {
13
      sessionId: sessionId,
14
      tabId: tabId,
15
    },
16
  },
17
18
  // With session token
19
  session_token: sessionToken,
20
  // Or without session token
21
  identity: {},
22
});