# Custom customer authentication

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

Breadcrumb: Integrations › Custom customer auth · Updated: 2026-10-17
Docs index: https://docs.cevoid.com/llms.txt

Custom customer authentication lets you authenticate customers 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: for the rest of their setup, see [General implementation](https://docs.cevoid.com/integrations/ecommerce/general-implementation.md). In the app, the method is called **Custom store authentication**.

> [!NOTE]
> This setup needs server-side code. If you don't write it yourself, share these steps with your developer.

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

> [!WARNING]
> Never expose the encryption key to the client or share it with anyone.

## How custom customer authentication works

1. You retrieve customer information from your authenticated session
2. You create a digest on the server: an HMAC-SHA256 signature of the customer's ID and email
3. You pass the digest, the customer info, and your tracking ID to the Cevoid widget div code
4. Cevoid finds your workspace by the tracking ID, verifies the digest, and authenticates the customer

## Set up custom customer authentication

### Enable custom customer authentication

Set _Authentication_ to **Custom store authentication** in [Settings → Loyalty → General](https://app.cevoid.com/settings/loyalty/general). For the steps, see [Change the authentication method](https://docs.cevoid.com/loyalty/setup/general-program-settings.md#change-the-authentication-method).

The next steps need your workspace's encryption key and tracking ID. Copy both from [Settings → Loyalty → General](https://app.cevoid.com/settings/loyalty/general).

### Get your widget embed code

Copy the widget's code from the embed dialog, under _Embed with code_: see [Embed with code](https://docs.cevoid.com/loyalty/setup/embed-program-widgets.md#embed-with-code). The page also needs the Cevoid script for program widgets: see [Add the Cevoid script for program widgets](https://docs.cevoid.com/integrations/ecommerce/general-implementation.md#add-the-cevoid-script-for-program-widgets).

The copied embed code looks like this. For a single section, it also has `data-section`:

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

Add your tracking ID as `data-tracking-id`:

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

### Add customer information to the embed code

Add the following data attributes with your authenticated customer's information:

| Attribute | Required | Description |
| --- | --- | --- |
| `data-tracking-id` | Yes | Your workspace's tracking ID. Cevoid finds your workspace by it |
| `data-user-email` | Yes | The customer's email address |
| `data-user-id` | Yes | The customer's ID in your system |
| `data-user-name` | No | The customer'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>
```

### Create the digest

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

**Payload format:** `{{ EXTERNAL_USER_ID }},{{ EMAIL }}`, with the same ID you use in `data-user-id`

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

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

**Signature method:** HMAC with SHA256 algorithm, signed with your encryption key, as a hex string.

**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');
```

### 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 customer with:

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

The final embed code looks like this:

```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>
```

## Opt-in rules with custom authentication

Custom customer authentication works with the opt-in rules **All customers**, **Widget opt-in**, and **Invite only**. A logged-in customer who isn't a member sees **Join now** in your program widgets: visiting a widget doesn't enroll them automatically. With **Invite only**, they can't join from a widget. See [How opt-in rules work](https://docs.cevoid.com/loyalty/setup/general-program-settings.md#how-opt-in-rules-work).

## Related articles

- [General program settings](https://docs.cevoid.com/loyalty/setup/general-program-settings.md)
- [General implementation](https://docs.cevoid.com/integrations/ecommerce/general-implementation.md)
- [On-site widgets](https://docs.cevoid.com/loyalty/setup/on-site-widgets.md)

---

Canonical: https://docs.cevoid.com/integrations/ecommerce/custom-customer-authentication