Display Continue with Faraway button

Prerequisites

Complete the following before adding the button to your login page:

• Follow the steps described here to configure your OAuth and to obtain a Client ID.
• Install the library and customize your button as described below.

Installation

• Add thisHTML to your page inside the head element. The Faraway button uses the Inter font family and falls back to sans-serif. If you already use the Inter font family in your web page, you may skip this step.

  <link href="https://fonts.googleapis.com/css2?family=Inter:opsz,[email protected],700&display=swap" rel="stylesheet">

• Add this script tag inside your web page HTML in the head section or at the end of body tag

<script src="https://connect-v2.faraway.com/faraway-auth-latest.js" type="text/javascript"></script>

Usage

You can use either the HTML API or JavaScript API but not both at the same time. Note that if you want to use popup UX mode you should close the popup window by yourself after claiming the access token. For example, your callback endpoint can set the session cookie and return the empty html page with this script:

<script>
    window.close();
</script>

HTML

UX Mode: Redirect

<!-- This block provides initialization parameters -->
<div
  id="faraway-auth_config"
  data-auth-url="YOUR_AUTH_URL"
  data-ux-mode="redirect"
></div>
<!-- "Continue with Faraway" button will be rendered inside this block -->
<div
  class="faraway-auth_button"
  data-size="medium"
  data-theme="dark"
  data-type="standard"
>
</div>

UX Mode: Popup

<!-- This block provides initialization parameters -->
<div
  id="faraway-auth_config"
  data-auth-url="YOUR_AUTH_URL"
  data-ux-mode="popup"
  data-on-popup-close="handlePopupClose"
></div>
<!-- "Continue with Faraway" button will be rendered inside this block -->
<div
  class="faraway-auth_button"
  data-size="medium"
  data-theme="dark"
  data-type="standard"
>
<script>
  async function handlePopupClose() {
    await user = fetchUser();
    if (user) {
      // update UI or perform navigation
    }
  }
</script>

API Reference

faraway-auth_config

• data-auth-url - the URL of your authorization endpoint which starts OAuth2 authorization process. For more information please read the docs
• data-ux-mode - popup or redirect
• data-on-popup-close - Required if data-ux-mode="popup". Callback that will be called every time popup window closes. If callback returns Promise button will be in loading state until it's resolved. Note that popup can be closed by your callback page or by the user action. Currently, it's impossible to distinguish reason of closing
  faraway-auth_button
• data-size - small | medium | large
• data-theme - light | dark
• data-type - standard | icon

JavaScript

// initialization
FarawayAuth.client.init({
  authUrl: 'https://your-domain.com/login',
  uxMode: 'popup',
  onPopupClose: async () => {
    await user = fetchUser();
    if (user) {
      // update UI or perform navigation
    }
  }
})
// render button
FarawayAuth.client.renderButton(
  document.getElementById('sign-in-button'),
  {
    type: 'standard',
    size: 'medium',
    theme: 'dark',
  }
)

API Reference

FarawayAuth.client.init(InitOptions)

InitOptions

• authUrl - The URL of your authorization endpoint which starts OAuth2 authorization process. For more information please read the docs
• uxMode - popup or redirect
• onPopupClose - Required if uxMode="popup". Callback that will be called every time the popup window closes. If the callback returns Promise, the button will be in loading state until it's resolved. Note that popup can be closed by your callback page or by the user action. Currently, it's impossible to determine the exact reason of the popup closing.

FarawayAuth.client.renderButton(
  ButtonRoot,
  ButtonOptions
)

ButtonRoot - string | HTMLElement. If you pass string, method will call document.querySelector with provided value
ButtonOptions

• size - small | medium | large
• theme - light | dark
• type - standard | icon