Web Widgets
Web Widgets are embeddable UI elements for common user management interactions including register, sign in, user settings and account recovery. The widgets are configurable to your needs.
Widgets are embedded elements that use iframes. Your app is required to add
frame-src exception in content security policy if the domain of Authcore is not on the same origin domain.Installation
The packages will be published to npm when v1.0 is released
Install via npm:
1
$ npm install authcore-js
Copied!
Install via yarn:
1
$ yarn add authcore-js
Copied!
Usage
User Registration
1
<!-- Element for the widget to be injected -->
2
<div id="authcore-register-container"></div>
3
​
4
<script>
5
let privateStore = {};
6
​
7
// Instantiate Register widget
8
new AuthCoreWidgets.Login({
9
container: 'authcore-register-container', // Id of the HTML element for the widget
10
root: 'https://authcore.example.com/widgets', // Authcore is hosted on the sub-domain of example.com,
11
initialScreen: 'register', // Set initial screen to register
12
logo: 'default', // Default to show Authcore logo
13
company: 'Authcore',
14
successRedirectUrl: 'https://application.example.com',
15
analyticsHook: (type, data) => {
16
// type is a string describing the event. It is contained in the event list. All Authcore events are typed with prefix `Authcore_`.
17
// data is a object which is the associated data of an event. By default, if no data is associated, it will be a empty object `{}`.
18
​
19
// code for analytics
20
}
21
});
22
</script>
Copied!
User Profile
1
<!-- Element for the widget to be injected -->
2
<div id="authcore-profile-container"></div>
3
​
4
<script>
5
// Instantiate Profile widget
6
new AuthCoreWidgets.Profile({
7
container: 'authcore-profile-container', // Id of the HTML element for the widget
8
root: 'https://authcore.example.com/widgets', // Authcore is hosted on the sub-domain of example.com
9
accessToken: 'ACCESS_TOKEN_TO_BE_PROVIDED',
10
callbacks: {
11
// Handle the unauthenticated case returns from the widget
12
unauthenticated: () => {};
13
}
14
});
15
</script>
Copied!
API
Constructor Parameters
Parameter
Type
Description
container
REQUIRED, string
The
id of the HTML element where the widget will be rendered.root
OPTIONAL, string
The domain where the Authcore widgets hosts, if it is not set it will refer to the window origin location with
/widgets.logo
OPTIONAL, string
The logo shown in the widget. If no value is passed this section is hidden. Should be in absolute path format, also accept value "default" to serve as showcase of the widget style for
Login widget.company
OPTIONAL, string
The company name shown in the widget. If no value is passed this section is hidden.
accessToken
REQUIRED except for
Login or RefreshTokenwidget, stringThe access token for API request requires authentication. This is done by using authorization code returned with
successRedirectUrlfrom Login widget to get access token from create access token API.primaryColour
OPTIONAL, string
The primary colour of the widget. Primary colour mainly consists of general button colour, link colour and border colour when the field box is in focus. Allow colour code, RGB colour value or named colour.
successColour
OPTIONAL, string
The success colour of the widget. Success colour mainly consists of verified message and icon. Allow colour code, RGB colour value or named colour.
dangerColour
OPTIONAL, string
The danger colour of the widget. Danger colour mainly consists of error message, button colour for destructive action (e.g. Remove contact) and invalid field box border. Allow colour code, RGB colour value or named colour.
requireUsername
OPTIONAL, boolean
The flag whether username is included in registration and sign in.
language
OPTIONAL, string
Widget language when it is loaded, default to be English when it is not set or the value is invalid or unavailable.
onSuccess
OPTIONAL, function
Callback hook after the certain action from widgets is success. Return the result including
action as key in object format, use destructing assignment to get the data required.onLoaded
OPTIONAL, function
Callback after the widgets is loaded and mounted to the site.
analyticsHook
OPTIONAL, function
Hooks for analytics to recieve events. Two parameters describing the event are given for the hook, including
type and data.unauthenticated
OPTIONAL, function
Callback when the widget returns unauthenticated error.
Action list for
onSuccess callback:Success callback is now DEPRECATED, use successRedirectUrl for registration or sign in flow.
Login Widgets
These widgets provides a simple UI widget for authenticating or registering users.
AuthCoreWidgets.Login
For register page, the field with
Email or mobile label refer as contact field. For sign in page, the input field refer as handle field.Parameter
Type
Description
successRedirectUrl
REQUIRED, string
The URL to be redirected with authorization code when registration or sign in flow is success.
contact
OPTIONAL, string
The pre-fill contact(Register screen) or handle field value for Signin widget.
fixedContact
OPTIONAL, boolean
The flag indicates contact(Register screen) or handle field is fixed or not. If it is set to be fixed value should be provided on
contact param, otherwise error will be throwed as it is impossible for user to sign in.initialScreen
OPTIONAL, string
The flag indicates the initial screen, either
register or signin, default to be signin.socialLoginPaneStyle
OPTIONAL, string
The flag to decide position where social login pane should located, either
topor bottom, default to be bottom.socialLoginPaneOption
OPTIONAL, string
The flag to decide option where social login pane in grid or list stye, either
grid or list, default to be grid.buttonSize
OPTIONAL, string
The flag to decide button size, either
normal or large, default to be large.For
register as initialScreen:
When registration is completed, the screen will show loading spinner and redirect to
successRedirectUrl set in widget instance.For
signin as initialScreen:
Social login pane list:
Normal button size:
User Widgets
Authcore provides some user widgets for updating a logged in user. These widgets require the
accessToken parameter, which can be obtained from the access_token parameter from onSuccess callback in login widgets.AuthCoreWidgets.Settings
Show the settings of current login user, including password, 2-steps verification, devices (i.e. sessions) and social login sections.
AuthCoreWidgets.SettingPass
Show the page to create Pass as 2-steps verification factor. It shows a QR code to be scanned for registration, once the process is successful it triggers
onSuccess callback.Follow the setting below to configure the page:
1
<!-- Element for the widget to be injected -->
2
<div id="authcore-pass-container"></div>
3
​
4
<script>
5
// Instantiate Pass widget
6
new AuthCoreWidgets.SettingPass({
7
container: 'authcore-pass-container', // Id of the HTML element for the widget
8
root: 'https://authcore.example.com/widgets', // Authcore is hosted on the sub-domain of example.com
9
accessToken: 'ACCESS_TOKEN_TO_BE_PROVIDED',
10
internal: true,
11
onSuccess: () => {
12
// Handle the case after the factor registration is successful.
13
}
14
});
15
</script>
Copied!
Analytics
We provide multiple events for analytics purpose. All events shown below are prefixed with
Authcore_.The events are show below:
Type
Data (if any)
Description
loginWidgetLoaded
-
When a login widget (e.g. register / login) page is loaded
registerStarted
contactType: "email" / "phone"
When a user triggered register
oauthStarted
service: "google" / "facebook" / "matters" / "twitter" / "apple"
When a user triggered oauth from social platform
loginStarted
method: "password"
When a user login using password
navigation
from/to: Page name("Register"/"SignIn")
When a user switch between register/sign in page within Login widget
Because of page reload in redirection, the widget cannot emit loginSuccess and registerSuccess events to the original page. Therefore, it is advised to record the success events manually in the redirected pages (from
successRedirectUrl), and pages after signin.Last modified 1yr ago