# Custom customer authentication for program widgets

> Implement custom authentication to connect your store's user system with Cevoid program widgets.

Breadcrumb: Widget › Customer authentication · Updated: 2026-10-17
Docs index: https://docs.cevoid.com/developers/llms.txt

Custom customer authentication allows you to authenticate users with your own system instead of using Shopify accounts or Cevoid email authentication. This is useful for headless setups or stores running on platforms other than Shopify.

The implementation involves encrypting a payload with a key provided by Cevoid and attaching the result to your widget embed code.

> [!WARNING]
> This implementation requires server-side code. The encryption key must never be exposed to the client or shared with anyone.

## How it works

1. You retrieve user information from your authenticated session
2. You create an encrypted digest on the server using the user's ID and email
3. You pass the digest and user info to the Cevoid widget div code
4. Cevoid verifies the digest and authenticates the user

## Set up custom customer authentication

### Step 1: Enable custom customer authentication

1. Navigate to [Settings → Loyalty → General](https://app.cevoid.com/settings/loyalty/general)
2. Under _Access and enrollment_, set **Authentication** to **Custom customer authentication**
3. Copy your **encryption key** and **tracking ID** from this page

### Step 2: Get your widget embed code

1. Navigate to [Loyalty → On-site widgets](https://app.cevoid.com/program/widgets)
2. Select the widget you want to embed
3. Click **Embed** in the top right corner
4. Copy the div code

The div code from the Embed dialog looks like this:

```html
<div class="cevoid-widget" data-id="ew-3qGflV" data-type="engage"></div>
```

Keep `data-type="engage"`: the autoloader loads the loyalty widget only for elements that have it. For a single section, the dialog also adds `data-section`, which renders only that section; keep it too. Add the autoloader script from the same dialog once per page, as described in [Cevoid widgets](https://docs.cevoid.com/developers/widget.md).

### Step 3: Add user information to the embed code

Add your tracking ID and the following data attributes with your authenticated user's information:

| Attribute | Required | Description |
| --- | --- | --- |
| `data-tracking-id` | Yes | The tracking ID from step 1. Cevoid uses it to find the encryption key that checks the digest |
| `data-user-email` | Yes | The user's email address |
| `data-user-id` | Yes | The user's ID in your system |
| `data-user-name` | No | The user's display name |

```html
<div
  class="cevoid-widget"
  data-id="ew-3qGflV"
  data-type="engage"
  data-tracking-id="cv-1234-1"
  data-user-email="{{ EMAIL }}"
  data-user-id="{{ EXTERNAL_USER_ID }}"
  data-user-name="{{ NAME }}"
></div>
```

### Step 4: Create the digest

The digest authenticates the user and must be generated server-side.

**Payload format:** `{{ USER_ID }},{{ EMAIL }}`

For example, for a user with ID `1234` and email `viktor@cevoid.com`, the payload is:

```text
1234,viktor@cevoid.com
```

**Encryption method:** HMAC with SHA256 algorithm, signed with your encryption key.

**Node.js example:**

```javascript
const crypto = require('crypto');

const encryptionKey = 'YOUR_ENCRYPTION_KEY';
const userId = '1234';
const email = 'viktor@cevoid.com';

const digest = crypto
  .createHmac('sha256', encryptionKey)
  .update(`${userId},${email}`)
  .digest('hex');
```

### Step 5: Add the digest to the embed code

Add the generated digest as `data-digest`:

```html
<div
  class="cevoid-widget"
  data-id="ew-3qGflV"
  data-type="engage"
  data-tracking-id="cv-1234-1"
  data-digest="{{ DIGEST }}"
  data-user-email="{{ EMAIL }}"
  data-user-id="{{ EXTERNAL_USER_ID }}"
  data-user-name="{{ NAME }}"
></div>
```

## Complete example

For a user with:

- ID: `1234`
- Email: `viktor@cevoid.com`
- Name: `Viktor`

The final embed code would look like:

```html
<div
  class="cevoid-widget"
  data-id="ew-3qGflV"
  data-type="engage"
  data-tracking-id="cv-1234-1"
  data-digest="a1b2c3d4e5f6..."
  data-user-email="viktor@cevoid.com"
  data-user-id="1234"
  data-user-name="Viktor"
></div>
```

## Related articles

- [General program settings](https://docs.cevoid.com/loyalty/setup/general-program-settings.md)
- [How opt-in rules work](https://docs.cevoid.com/loyalty/setup/general-program-settings.md#how-opt-in-rules-work)
- [On-site widgets](https://docs.cevoid.com/loyalty/setup/on-site-widgets.md)

---

Canonical: https://docs.cevoid.com/developers/widget/customer-authentication