Custom customer authentication for program widgets

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

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.

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

How it works

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

Set up custom customer authentication

Step 1: Enable custom customer authentication

Navigate to Settings → Loyalty → General⁠
Under Access and enrollment, set Authentication to Custom customer authentication
Copy your encryption key and tracking ID from this page

Navigate to Loyalty → On-site widgets⁠
Select the widget you want to embed
Click Embed in the top right corner
Copy the div code

The div code from the Embed dialog looks like this:

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

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

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

1234,viktor@cevoid.com

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

Node.js example:

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:

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

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