Identifying users

Users can be identified when you first load the Frill Script, or at any time using the identify command.

Important

• You must provide a valid email.

• Name is optional but recommended

• Guest authentication will fail if:

  • Your Widget/Survey has user/password or SSO authentication enabled

  • The email is associated to an existing user/password account

The simplest way to identify users is with the container command. Just define the user as part of your configuration. We recommend identifying with an SSO token when possible as it circumvents any possible edge cases (see above) that come with guest authentication.

window.Frill('container', {
  key: 'YOUR_SCRIPT_KEY',
  user: {
    email: '[email protected]',
    name: 'my user', // optional
    // You can also pass custom variables (attributes and companies) when identifying users
    // attributes: { mrr: 100 },
    // companies : [{ id: 'frill', name: "Frill.co" }] }
  },
});

Learn more about custom user attributes for segmentation.

Frill('identify')

If your app has client side authentication, you can identify the user using the identify command when they login. The identify command will identify the user for all active (and future) Widgets & Surveys.

await window.Frill('identify', {
  email: '[email protected]',
  name: 'my user'
  // You can pass custom variables here too...
  // attributes: { mrr: 100 },
  // companies : [{ id: 'frill', name: "Frill.co" }] }
});

If the user logs out, you should unidentify them:

window.Frill('unidentify');

Single Sign On (SSO)

You can identify SSO users by passing a signed SSO JWT instead of user details. Your company does not need to enable SSO in the platform for this to work.

window.Frill('container', {
  key: 'YOUR_SCRIPT_KEY',
  ssoToken: 'SSO_JWT_FROM_SERVER',
})

// Or with the identify command
await window.Frill('identify', { ssoToken: 'SSO_JWT_FROM_SERVER' });

Check out this guide for more information on setting up SSO

Identify users in iFrames

If you're embedding Frill in an iFrame (like a standalone widget page), pass user data via query parameters:

With user object (URL-encoded JSON):

https://your-widget-url.frill.co?user=%7B%22email%22%3A%22user%40example.com%22%2C%22name%22%3A%22Jane%20Doe%22%7D

With SSO token:

https://your-widget-url.frill.co?ssoToken=YOUR_JWT_TOKEN

The iFrame will automatically identify the user based on these parameters.

Guest vs. identified users

In each widget's settings, you can control what guests can do:

• Allow guests — Anyone can view and interact (vote, comment, submit ideas)

• Require login — Only identified users can access the widget

• Custom permissions — Guests can view but not interact (vote/comment restricted to identified users)

If a widget requires login and no user is identified, visitors will see a login prompt.