> Legacy approach
>
> For new integrations, use the [Widget SDK with Access Key Embed](https://docs.returning.ai/widget-sdk/auth-access-key.md).

# Auth - Attribute

Identify users by passing identity attributes directly on the widget element. No backend required, but the identifier remains visible in the browser.

## How it works

The widget reads `data-*` attributes from its HTML element and sends them to Returning.AI to identify the user. No server-side code is needed.

Use lowercase hyphenated attribute names in docs and production HTML examples, such as `data-customer-id`. The SDK forwards non-reserved `data-*` keys as user identifiers.

```html
<script
  src="https://unpkg.com/@returningai/widget-sdk@1.8.11/dist/rai-widget.iife.js"
  data-community-id="YOUR_COMMUNITY_ID"
  data-widget-type="store"
  data-container="returning-ai-widget-YOUR_COMMUNITY_ID"
  data-api-url="https://prod-widgets.returning.ai"
  data-widget-url="YOUR_WIDGET_URL"
  data-customer-id="CUST-10482"
></script>
```

## Common attributes

| Attribute | Description |
| --- | --- |
| `data-customer-id` | Preferred stable broker-owned customer ID. |
| `data-user-id` | Fallback internal user ID if that field already exists in your platform. |
| `data-email` | Use only if email is already your canonical identifier and you do not have a better stable ID. |
| `data-firstname / data-lastname` | Optional display fields. Do not treat names as your primary identifier. |

## Custom attributes

Any field that exists on both the client side and the Returning.AI platform can be used as an identity attribute. Custom fields can be created in the Returning.AI admin panel so you can key off a stable broker-owned ID like `data-customer-id` instead of email.

## Legacy fallback guidance

If you do not have a backend, prefer a stable broker-owned identifier like `data-customer-id`. In most integrations, one stable identifier is enough. Only add a second identifier if your registration setup explicitly relies on it. This mode still exposes identity in the browser.

```html
<script
  src="https://unpkg.com/@returningai/widget-sdk@1.8.11/dist/rai-widget.iife.js"
  data-community-id="YOUR_COMMUNITY_ID"
  data-widget-type="store"
  data-container="returning-ai-widget-YOUR_COMMUNITY_ID"
  data-api-url="https://prod-widgets.returning.ai"
  data-widget-url="YOUR_WIDGET_URL"
  data-customer-id="CUST-10482"
  data-custom-tier="gold"
></script>
```

> Browser-visible fallback
>
> For most legacy integrations, `data-customer-id` is the cleanest default. Only add `data-user-id` or email if your existing registration mapping depends on them and you accept that they will be visible in the page markup.

## Web Component usage

The same attributes work on the Web Component tag:

```html
<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  widget-type="channel"
  api-url="https://prod-widgets.returning.ai"
  v2-api-url="https://api-v2.returning.ai"
  widget-url="YOUR_WIDGET_URL"
  data-customer-id="CUST-10482"
></rai-channel-widget>
```

## Framework examples

### React

`LoyaltyWidget.tsx`

```tsx
import '@returningai/widget-sdk'

export function LoyaltyWidget({ user }: { user: { customerId: string } }) {
  return (
    <rai-store-widget
      community-id="YOUR_COMMUNITY_ID"
      api-url="https://prod-widgets.returning.ai"
      v2-api-url="https://api-v2.returning.ai"
      widget-url="YOUR_WIDGET_URL"
      data-customer-id={user.customerId}
    />
  )
}
```

### Vue

`LoyaltyWidget.vue`

```vue
<script setup>
import '@returningai/widget-sdk'

const user = inject('user')
</script>

<template>
  <rai-store-widget
    community-id="YOUR_COMMUNITY_ID"
    api-url="https://prod-widgets.returning.ai"
    v2-api-url="https://api-v2.returning.ai"
    widget-url="YOUR_WIDGET_URL"
    :data-customer-id="user.customerId"
  />
</template>
```

## When to use

- Quick integrations where you already know the user on the client side.
- Internal tools and admin dashboards.
- Environments where you control who accesses the page.
- Prototyping and development before implementing Access Key Embed.

Need server-verified identity? [See Auth - Access Key](https://docs.returning.ai/widget-sdk/auth-access-key.md) for server-verified authentication with short-lived JWTs.