Best Practice

Interact with Popup or Redirect?

You may prefer to use Popup over Redirect, as Popup is superior in several ways:

  • Better User Experience. The user doesn't need to leave the current page, and it doesn't break UI continuity. Popup also listens when a user closes a popup, whereas Redirect cannot handle when a user closes the page.
  • Better Development Experience. You don't need to deal with routing-related logic or callback logic after Redirect. The way Popup is called is an asynchronous function, which is very less invasive to existing code.
  • A wider range of usage scenarios. For example, Live Demo in this docs, some browsers won't allow biometric authentication in iframe for security reasons, which is not a problem with popup because the popup window doesn't run inside an iframe.

There are two scenarios where only Redirect can be used.

  1. Some In-app Browsers, such as WeChat, imToken, Telegram;
  2. Native Mobile applications

For In-app Browsers you may consider directing users to open your app in a normal browser like Safari, Chrome. For native mobile apps, you may consider using low-level APIs like generateAuthURL/ generateSignURL to implement in your own way to interact with JoyID App.

Keep redirectURL clean

A common mistake is to pass location.href directly into redirectURL: in most cases, this will not cause any problems. However, location.href may include url queries that are not useful to JoyID, resulting in URLs that are too long for browsers to parse. Also note that the JoyID App resets some of the contents of redirectURL

We recommend using new URL() to construct your redirectURL parameters.

// use location.origin as URL base
const url = new URL(location.origin);
// your current pathname in Popup mode, or redirected pathname in Redirect mode
url.pathname = "/login";
const redirectURL = url.href;

In addition, the JoyID App checks to see if the origin of the redirectURL matches the origin of the document.referrer, and if it does not, it cannot be authenticated. This means that if you call the JoyID App SDK from https://google.com, you will not be able to jump to https://twitter.com to get the results.

Authentication State Persistence

After authentication is complete, you will get the user's authorized JoyID information. You should consider storing this information persistently so that you don't need to request JoyID authentication again when you need to sign. There are many ways to store information persistently in a web application, you can save it to localStorage/Cookies, or your server-side database.

What we really need to discuss is the expiration date of the persistent storage. In the JoyID App, if a user creates a JoyID Account on his device, that JoyID Account never expires. If the user manually clears all the data from the JoyID App website in the browser settings, the user can still log in to the same JoyID Account on the same device.

If you do not need to sign challenge during authentication, then we recommend that you do not set an expiration time for the authentication information either. If you need to sign a challenge during authentication, you can set the expiration time as part of the challenge, the expiration time depends on the validator.

Caveats

A popup window must be trigger by ACTUAL user interaction. For example, the following code will not work, some browsers may block the popup window:

// open popup window in useEffect or other lifecycle function
useEffect(() => {
    await authWithPopup({
        redirectURL: location.href,
        name: 'Awesome App',
        challenge: 'Sign this for me',
        logo: 'https://vuejs.org/images/logo.png',
    });
}, [])

We recommend to use a HTML Element and listen to the click or touchstart event to open the popup window. Before calling authWithPopup function, you should also NOT calling any async function, otherwise the popup window may be blocked by the browser as well.

Edit this page on GitHub
Table of Contents