User Identification

The Lovina Chat SDK supports both anonymous and identified users. This guide explains how each works and when to use them.

Anonymous Users (Default)

When no user is identified, the widget creates an anonymous session:

• A session token is auto-generated on the first message
• The token is saved to localStorage for session persistence
• On page reload, the conversation resumes via the stored token
• The user appears as "Guest" in the CRM dashboard
• No personal data is collected

// No setUser() call needed — widget works out of the box
window.lovinaChatSDK.run({
  websiteToken: 'YOUR_TOKEN',
  baseUrl: 'https://chat.ailovina.com',
});

:::tip When to use anonymous mode

• Public-facing websites where visitors aren't logged in
• Landing pages, marketing sites, help centers
• Quick support without requiring sign-in :::

Identified Users

When your app knows who the user is (e.g., after login), call setUser() to link the chat session to their identity:

Web

window.$lovina.setUser('user-123', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  avatarUrl: 'https://example.com/jane.jpg',
  phoneNumber: '+628123456789',
  customAttributes: {
    plan: 'pro',
    company: 'Acme Inc',
  },
});

Android

val widget = LovinaChatWidget(this)
widget.configure(LovinaChatConfig(
    websiteToken = "YOUR_TOKEN",
    baseUrl = "https://chat.ailovina.com",
    user = LovinaChatUser(
        identifier = "user-123",
        name = "Jane Doe",
        email = "jane@example.com",
    )
))

iOS

let config = LovinaChatConfig(
    websiteToken: "YOUR_TOKEN",
    baseUrl: "https://chat.ailovina.com",
    user: LovinaChatUser(
        identifier: "user-123",
        name: "Jane Doe",
        email: "jane@example.com"
    )
)

React Native

<LovinaChatWidget
  config={{
    websiteToken: 'YOUR_TOKEN',
    baseUrl: 'https://chat.ailovina.com',
    user: {
      identifier: 'user-123',
      name: 'Jane Doe',
      email: 'jane@example.com',
    },
  }}
/>

Flutter

LovinaChatWidget(
  config: LovinaChatConfig(
    websiteToken: 'YOUR_TOKEN',
    baseUrl: 'https://chat.ailovina.com',
    user: LovinaChatUser(
      identifier: 'user-123',
      name: 'Jane Doe',
      email: 'jane@example.com',
    ),
  ),
)

User Data Fields

Field	Type	Required	Description
identifier	string	Yes	Unique user ID from your system
name	string	No	Display name shown to agents
email	string	No	Email address
avatarUrl	string	No	Profile image URL
phoneNumber	string	No	Phone number
identifierHash	string	No	HMAC hash for identity verification (see below)
customAttributes	object	No	Any extra metadata (plan, company, etc.)

What Agents See

Mode	CRM Dashboard Shows
Anonymous	"Guest User" — no name, email, or history across sessions
Identified	User's name, email, avatar, custom attributes, full conversation history

Identity Verification (HMAC)

To prevent users from impersonating others, you can enable HMAC identity verification. The server generates a hash of the user identifier using a secret key, and the SDK sends it for verification.

Generate the Hash (Server-Side)

// Node.js
const crypto = require('crypto');
const identifierHash = crypto
  .createHmac('sha256', 'YOUR_IDENTITY_VERIFICATION_SECRET')
  .update('user-123')
  .digest('hex');

# Python
import hmac
import hashlib
identifier_hash = hmac.new(
    b'YOUR_IDENTITY_VERIFICATION_SECRET',
    b'user-123',
    hashlib.sha256
).hexdigest()

Pass the Hash to the SDK

window.$lovina.setUser('user-123', {
  name: 'Jane Doe',
  identifierHash: 'computed-hmac-hash',
});

warning

Never expose your identity verification secret in client-side code. Always compute the HMAC on your server.

Updating User Data

You can call setUser() multiple times — subsequent calls update the user's profile:

// Initial identification
window.$lovina.setUser('user-123', { name: 'Jane' });

// Later: update with more data
window.$lovina.setUser('user-123', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  customAttributes: { plan: 'enterprise' },
});

Resetting Identity

To log out the user and start a fresh anonymous session:

window.$lovina.reset();

On native SDKs:

// Android
widget.clearSession()

// iOS
widget.clearSession()

This clears the stored session token and conversation history. The next interaction starts as a new anonymous user.