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

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" }] }
  },
});

To pass custom user attributes you must turn on the "Allow custom attributes when identifying users with JS" option from the Frill Script setup identification settings. Using SSO? Check out this guide.

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:

await window.Frill('unidentify');

Single Sign On (SSO)

You can identify SSO users by passing a signed SSO JWT.

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

iFrames

If you're loading your Widget in an iFrame you can still identify users (including SSO) by passing the user details as a query parameter.

Guest users

You can authenticate guest users by passing their details as the user query parameter. The object should be encoded and must have a valid email.

// In javascript you would do
const user = encodeURIComponent(JSON.stringify({ name: 'Mitch Guest', email: '[email protected]' }))
// And it should look like this
// %7B%22name%22%3A%22Mitch%20Guest%22%2C%22email%22%3A%22mitch%2Bguest%40frill.co%22%7D

// Then load the Widget iframe
<iframe src="https://YOUR_FRILL_DOMAIN/embed/widget/YOUR_WIDGET_KEY?user=%7B%22name%22%3A%22Mitch%20Guest%22%2C%22email%22%3A%22mitch%2Bguest%40frill.co%22%7D" sandbox="allow-same-origin allow-scripts allow-top-navigation allow-popups allow-forms allow-popups-to-escape-sandbox" style="border: 0px; outline: 0px; width: 680px; height: 460px;"></iframe>
// It also works for Surveys
<iframe src="https://YOUR_FRILL_DOMAIN/embed/survey/YOUR_SURVEY_KEY?user=%7B%22name%22%3A%22Mitch%20Guest%22%2C%22email%22%3A%22mitch%2Bguest%40frill.co%22%7D" sandbox="allow-same-origin allow-scripts allow-top-navigation allow-popups allow-forms allow-popups-to-escape-sandbox" style="border: 0px; outline: 0px; width: 680px; height: 460px;"></iframe>

SSO users

To identify SSO users in an iFrame, pass your signed SSO JWT as the ssoToken query parameter.

// Then load the Widget iframe
<iframe src="https://YOUR_FRILL_DOMAIN/embed/widget/YOUR_WIDGET_KEY?ssoToken=SSO_JWT_FROM_SERVER" sandbox="allow-same-origin allow-scripts allow-top-navigation allow-popups allow-forms allow-popups-to-escape-sandbox" style="border: 0px; outline: 0px; width: 680px; height: 460px;"></iframe>
// It also works for Surveys
<iframe src="https://YOUR_FRILL_DOMAIN/embed/survey/YOUR_SURVEY_KEY?ssoToken=SSO_JWT_FROM_SERVER" sandbox="allow-same-origin allow-scripts allow-top-navigation allow-popups allow-forms allow-popups-to-escape-sandbox" style="border: 0px; outline: 0px; width: 680px; height: 460px;"></iframe>