Identifying Users

Call identify after a user logs in to tie the widget session to a real user. This enables:

• Verified identity — prevents user spoofing via a server-side HMAC signature.
• Announcement targeting — use customer properties (plan, role, etc.) to control who sees an announcement.
• Analytics attribution — tie widget usage, article reads, and announcement events to your internal user id.
• Analytics filters — filter dashboard analytics by identify properties such as plan, role, account type, or region.

The identify call

LumioWidget('identify', {
  userId: 'user_123',         // required — your internal user id
  signature: '<hmac>',        // required — computed server-side
  name: 'Alice',              // optional
  email: 'alice@example.com', // optional
  properties: {               // optional — any key/value pairs
    plan: 'pro',
    role: 'admin',
  },
})

Call this after init, once your app knows who is logged in.

Computing the signature (server-side)

The signature is an HMAC-SHA256 of the userId, keyed with your widget's signing secret. The signing secret is shown when you create a widget, and you can reveal it again later from the widget's page in the dashboard (Reveal signing secret). Store it as a server-side environment variable — never expose it in client code.

Here's a minimal Node.js example — an endpoint your frontend calls to get the signed identity:

// server.js (Node / Express)
import crypto from 'crypto'

app.get('/api/lumio-identity', (req, res) => {
  if (!req.user) return res.status(401).end()

  const userId = req.user.id
  const signature = crypto
    .createHmac('sha256', process.env.LUMIO_SIGNING_SECRET)
    .update(userId)
    .digest('hex')

  res.json({ userId, signature })
})

Then in your frontend:

const { userId, signature } = await fetch('/api/lumio-identity').then(r => r.json())

LumioWidget('identify', {
  userId,
  signature,
  name: currentUser.name,
  email: currentUser.email,
})

Customer properties

properties is a free-form object of key/value pairs. These are used by the Announcements engine to target specific audiences — for example, show a popup only to users where plan === 'free'.

Lumio also snapshots these properties on analytics events so you can filter reporting later. Keep them stable and low-cardinality where possible, such as plan, role, companySize, or region.

Properties are not displayed to the user. Do not send secrets or sensitive personal data.

Signing secret

• Shown when you create a widget; reveal it again anytime from the widget's page (Reveal signing secret, owner/admin only).
• Set it as a server-side environment variable — never commit it or send it to the browser.