Skip to main content
Unlayer Docs
Version: Latest

End-User Identification

Identifying end-users allows developers to associate actions performed in the builder with specific end-users in the host application. This is essential for personalizing the experience, tracking saved blocks, and managing uploads that belong to individual end-users.

Why Identify End-Users?​

Identifying end-users allows the builder to:

  • Save and load personalized content: Each end-user can have their own set of saved blocks, or file uploads.
  • Provide a seamless experience: Ensure that the right content is available to the right end-user.
  • Improve tracking: Keep track of who created, edited, or saved specific files for audit or reporting purposes.

Setting Up End-User Identification​

Pass the current end-user's details through the user property when initializing the builder. Use an opaque user.id from your application that stays the same across sessions. Although name and email are optional for general identification, we recommend sending both when available. The name is displayed next to comments in Team Collaboration, helping teammates recognize who is participating, and the email address enables Send Test Email.

unlayer.init({
  user: {
    id: 'user-42',
    name: 'Jane Doe',
    email: 'jane.doe@example.com',
  },
});

If your integration does not send profile details, a stable user.id is the minimum identity needed for features such as saved blocks, uploads, and AI usage attribution:

unlayer.init({
  user: {
    id: 'user-42',
  },
});

These examples show only the identity fields. If your project uses identity verification or requires end-user feature policies, also pass the appropriate signature or featurePolicyToken. See Security Settings.

Send Test Email requires a valid user.email. The test email is sent to that address. If you use this feature, include the email address and follow the other Test Email requirements.

Omitting profile fields does not clear values you previously sent for the same end-user. See Custom Properties for how stored values are merged and cleared.

User Object Properties​

  • id (required): This is the unique identifier for the end-user within your host application. It could be a number or a string.
  • name (optional, recommended): The name of the end-user. Displayed next to comments in Team Collaboration so teammates can identify the author.
  • email (optional, recommended): The email address of the end-user. Required for Send Test Email.
  • avatar (optional): URL of the end-user's profile image.

Custom Properties​

Any other property you put on user is stored with the end-user and returned to the editor with the session, so you can keep your own identifiers next to the profile:

unlayer.init({
  user: {
    id: 1,
    name: 'John Doe',
    tenantId: 'acme-eu',
    plan: 'pro',
  },
});

What you send is merged into what is already stored for that end-user. This applies to name, email, and avatar as well as to your own properties: a property you stop sending keeps its last value rather than being cleared. To clear a stored value, send the property as null. Unlayer does not interpret your own properties.

id, signature, and featurePolicyToken are credential fields, so a custom property cannot replace them. Unlayer also reserves the following names for authentication and session data:

  • projectId, customId, consoleAttestation, and entitlements
  • featurePolicy, policyExp, featurePolicyVerified, and legacySignatureVerified
  • consoleSession, _consoleSession, _consoleSessionId, _consoleSessionProof, and _consoleUserId
  • consoleContextVerified, consoleSessionExp, consoleSessionId, consoleUserId, and consoleSessionProof

A non-null featurePolicyToken and any supplied consoleAttestation are verified even when Identity Verification is off: a value Unlayer cannot verify, including an empty string, fails authentication, and the editor loads without a session. A featurePolicyToken set to null is treated as missing and uses the normal legacy-signature or unsigned flow; projects that require end-user feature policies still reject it. Any other reserved name is dropped rather than rejected. Either way, prefer names specific to your application — tenantId or acmePlan rather than generic ones.

Restricting What an End-User Can Do​

If different end-users of the same project should have different features — say full template generation on your paid tier only — pass a signed featurePolicyToken instead of a plain signature. It covers the same user id and additionally carries the features that end-user is permitted to use. See Restricting Features Per End-User.

Why the id is Required​

The id is the key property that helps the builder associate the user’s actions and saved content with their account. Without it, the builder won’t know which content belongs to which user, making it impossible to offer certain features.

The AI Assistant depends on it most directly. Without an id, the assistant doesn't appear in the editor, because AI usage is tracked per end user so you can see who consumes your credits. Recent editor versions log a console warning when the id is the only thing missing. See AI Assistant setup.

On AI Assistant plans, AI image edits in the image editor still work without an id, and so do Smart Buttons and Smart Headings when the plan includes them. That's deprecated: a future version will hide them too, and the editor warns in the console until then.

Use Cases for End-User Identification​

  • Saved Blocks: When users save blocks, they are saved under a unique id, making them available only to that specific end-user. The id helps ensure only the right person has access to their saved content. Learn More
  • File Manager: When users upload images or files, they are saved under a unique id, making them available only to that specific end-user. These files are visible to the end-user in uploads tab. Learn More
  • AI Assistant: The AI Assistant requires an identified end-user. Without an id, the assistant is hidden in the editor and AI requests are rejected. Learn More
  • End-User AI Credits: Use the same end-user id to attribute AI usage in your backend, then show that user's allowance and purchase flow in the builder. See End-User AI Credits & Upsell.

Best Practices​

  • Unique and Consistent IDs: Ensure that the id you pass is always unique and consistent for each user across different sessions.
  • Recommended Profile Fields: Send name and email when available, even though they are optional for general identification. Names help teammates recognize comment authors in Team Collaboration; a valid email address is required for Send Test Email.
  • Security: Make sure you review the Security Settings to setup identity verification. Identity verification prevents third parties from impersonating your logged-in users.
  • Per-End-User Permissions: unlayer.init feature flags configure the editor for everyone who loads it. To grant or withhold a feature for one specific end-user, use a signed feature policy.