Skip to main content

Guide: User Analytics

Introduction​

In this guide we'll talk about what behaviour is recorded as part of our user analytics feature, how to configure it and how to make use of the data recorded.

Understanding who, when and how often people are using your product is key to understanding the effectiveness of your product, marketing, or sales strategy. Additionally, these same metrics can help you to understand the effectiveness of SlashID as an identity provider, or how a specific configuration of SlashID is performing for your use case.

We've built user analytics right into SlashID. We automatically track user activity surrounding sign-up & log-in so we can give you metrics like monthly active users (MAU), returning users, and new users.

Further, we record how people are choosing to authenticate with SlashID and expose this data to you so you can understand user preferences regarding authentication methods, and crucially: any friction caused by requiring that a particular authentication method or combination of authentication methods (MFA) be used.

This information is conveniently visualised for you in the SlashID Console analytics dashboard.

Disclaimer

User analytics are enabled by default, that means if you are uncomfortable with this feature you need to opt-out. Opting-out will cause some parts of the analytics dashboard to stop working.

See React: opting-out or JavaScript: opting-out.

Configuration​

The configuration complexity for user analytics depends on your implementation. The SlashID React SDK is our most high-level API, and as such user analytics come mostly for free. If you're using our React hooks without the UI components, or our Core SDK directly, then the implementation complexity will vary.

In this section you'll learn how to get the most out of the SlashID Console analytics dashboard.

React​

This section assumes you're using @slashid/react.

info

If you're using the React SDK hooks but not the UI components like <Form>, please see: Hooks only

Good news! Provided you use <Form>, <SlashIDProvider> and useSlashID(): all user analytics apart from virtual page views come for free - our design philosophy is for user analytics to be as close to zero-config as possible. We'll honor this when implementing future metrics, so you don't have to.

When logging a user out it's important to use logOut() from useSlashID().

import { useSlashID } from '@slashid/react'const Component = () => {  const { logOut } = useSlashID()  return (    <button onClick={logOut}>      Log out    </button>  )}

Besides this, just implement the SDK following our Quickstart Tutorial. Analytics are enabled by default.

Hooks only​

As of version 1.16.0 of @slashid/react the majority of user analytics only require you to implement the <SlashIDProvider> and consume functions exposed via the useSlashID() hook.

In this section we'll cover this in a little more detail.

User activity & authentication metrics​
Login​

Use logIn() from useSlashID() to authenticate users.

import { useSlashID } from '@slashid/react'const Component = () => {  const { logIn } = useSlashID()  // ...  return (    <button onClick={() => logIn({ ... })}>      Log in    </button>  )}
Resuming a session​

Resuming a session from a stored token is done automatically when <SlashIDProvider> is instantiated, activity tracking happens automatically.

Login via Direct-ID​

Provided the challenges query parameter is set correctly, login via Direct-ID is done automatically when <SlashIDProvider> is instantited, and activity tracking happens automatically.

Logout​

Use logOut() from useSlashID() to log out users.

import { useSlashID } from '@slashid/react'const Component = () => {  const { logOut } = useSlashID()  return (    <button onClick={logOut}>      Log out    </button>  )}

Virtual Page Views​

info

If you're unfamiliar with this concept see: What is a virtual page view?

You can track a virtual page view using the trackVirtualPageView() function. This is available on the Analytics object of the Core SDK, you can get a reference via the sid property of useSlashID().

import { useSlashID } from '@slashid/react'const Page = () => {  const { sid } = useSlashID()  useEffect(() => {    try {      sid.getAnalytics().trackVirtualPageView()    } catch {      // an error will be thrown if analytics is disabled    }  }, [])}

You might implement it within your page components, or as a side-effect when your router navigates. You should only call this function once per "view".

Opting out​

here be dragons

The SlashID Console analytics dashboard depends on user analytics.

By opting-out of user analytics some metrics will be miscounted, or simply display zero.

Opting out is done with the analyticsEnabled prop of the <SlashIDProvider> component.

import { SlashIDProvider } from '@slashid/react'

function Component() {
  return (
    <SlashIDProvider
      analyticsEnabled={false}
      // ...
    >
      {/* ... */}
    </SlashIDProvider>
  )
}

JavaScript​

This section assumes you're using @slashid/slashid.

While some tracking is baked into the Core SDK, due to the SDKs stateless design it isn't possible to automatically track all user behaviours automatically.

In this section you'll learn how to implement user analytics using @slashid/slashid.

Setup​

In order to enable user analytics you must set the oid (organization id) property when instantiating SlashID(), besides this analytics are enabled by default.

import { SlashID } from '@slashid/slashid'const sid = new SlashID({  oid: '{YOUR_ORG_ID}'  // ...})

User activity & authentication metrics​

Login​

For most factors authentication behaviours are automatically tracked, simply use the id() method of SlashID().

For OTP in particular it's important to correctly implement the SDK events as described in Register a new user with an OTP code via SMS. This applies to both email OTP and SMS OTP.

Resuming a session​

Any time you allow the user to login using a stored token you need to record this action using the identify() method of the Analytics object. Since this action happens outside of the SDKs control we are unable to track this automatically.

import { SlashID, User } from '@slashid/slashid'const sid = new SlashID()// get token from wherever you store itconst token = globalThis.localStorage.getItem('some-storage-key')const user = new User(token)const tokenValidation = await user.validateToken()if (tokenValidation.valid) {  try {    sid.getAnalytics().identify(user)  } catch {    // error is thrown if analytics is disabled  }}
Login via Direct-ID​

Use the getUserFromURL() method of SlashID() to exchange a Direct-ID for an access token, activity tracking happens automatically.

import { SlashID } from '@slashid/slashid'const sid = new SlashID()const user = await sid.getUserFromURL();

See Login a user with Direct-ID for more information about Direct-ID.

Logout​

Any time the user is logged out (i.e. you clear the user token from storage) you need to record this action using the logout() method of the Analytics object.

The user must have been identified prior to you calling logout().

import { SlashID } from '@slashid/slashid'const sid = new SlashID()sid.getAnalytics().logout()

Virtual Page Views​

What is this?

If you're unfamiliar with this concept see: What is a virtual page view?

You can track a virtual page view using the trackVirtualPageView() method of the Analytics object. You can get a reference to Analytics via the getAnalytics() method of SlashID().

import { SlashID } from '@slashid/slashid'const sid = new SlashID()try {  sid.getAnalytics().trackVirtualPageView()} catch {  // an error will be thrown if analytics is disabled}

You might implement it within your page components, or as a side-effect when your router navigates. You should only call this function once per "view".

Opting out​

here be dragons

The SlashID Console analytics dashboard depends on user analytics.

By opting-out of user analytics some metrics will be miscounted, or simply display zero.

Opting out is done with the analyticsEnabled property of the SlashID constructor.

import { SlashID } from '@slashid/slashid'const sid = new SlashID({  analyticsEnabled: false})

Programatically subscribing to events​

If you wish you can subscribe to our user analytics events to build your own dashboard or build integrations, we expose these to you through webhooks.

You can learn more about this in Webhooks guide.

Events​

AuthenticationSucceeded_v1​

A user authentication succeeded for any one factor.

AuthenticationFailed_v1​

A user authentication failed for any one factor.

PersonCreated_v1​

A user was created within a person pool.

PersonDeleted_v1​

A user was deleted from a person pool.

PersonIdentified_v1​

A user logged in or resumed a session by parsing a stored access token. This is the primary event for user activity tracking.

PersonLoggedOut_v1​

A user logged out.

SlashIDSDKLoaded_v1​

The @slashid/slashid SDK was instantiated. This fires for both authenticated and anonymous users, events are deduped across a single browser session only. These events should not be considered as unique user interactions with the SDK.

VirtualPageLoaded_v1​

A "virtual page view" occurred, the definition of virtual page view is defined by you.

What is a virtual page view?

A virtual page view allows you to track a page view, even when a page is not physically loaded in the browser. For example, when navigating using a client-side router in a single page application, or navigating within a sub-section of a page (like a tabbed pane, or navigation drawer) without changing the page itself.

The exact meaning of a virtual page view will vary by implementation, it depends on your routing paradigm and what you're trying to track. You will need to implement this event in a way which makes sense for your product.

That said, this hands-off approach means the same tracking event could also be used for a "standard" page view, it's compeletely up to you.

Conclusion​

In this guide you learned about SlashID user analytics, how to configure them and how to implement the data gathering for React, React (hook only), and JavaScript use cases.