Set up identity using the SDK & JWT

Identity integration using JWT and built-in identity management features

In this use-case, the Monterosa Experience is embedded into a site or app that requires the user to be signed-in.

If a non-signed-in user attempts to use the Experience, they will be prompted to sign in before continuing.

All users accessing the embedded Experience will therefore have a JWT token available to pass to the Monterosa SDK.

Note, this guide assumes the SDK is already in use in your systems, if it isn’t please follow the instructions you’ll find here, or contact Sales or your Account Manager if you need any further guidance.

The SDK offers a standardised approach to this integration, reducing the effort involved on your side to a two step process:

1. Sign in your user in order to obtain the JWT token

2. Provide to the SDK the JWT token

Make sure that the JWT includes a key id (kid) in its header so that we know which key to use from your JWKS.

The SDK allows you to set the JWT token via a call to the setCredentials method:

iOS

let identify = Identify.default
let credentials = UserCredentials(token: "...")
identify.setCredentials(credentials: credentials)

Android

val identifyKit: IdentifyKit = IdentifyKit.default() 
identifyKit.credentials = Credentials(token = "...")

// If you are embedding an Experience also set Identify in 
// ExperienceView when creating the experience:
experienceView.identify = identifyKit

JavaScript

These docs have been created referencing our core App, FanKit. Some settings may differ if you are using your own custom App. For any custom App questions please use your dedicated customer hub.

import {
  onReady,
} from "@monterosa/sdk-launcher-kit";
import {
  getIdentify,
  setCredentials,
} from "@monterosa/sdk-identify-kit";

const identify = getIdentify({
  // Make sure to store this id and re-use it in future sessions.
  deviceId: UUID()
  // Always use email
  strategy: 'email',
});

// experience was configured previously
onReady(experience, async () => {
  await setCredentials(identify, { token: '...' });
});

You can then follow the instructions to embed the Experience into your page using the SDK as described here.

See also our SSO Integration guidelines for more general information on this integration

Get user data

JavaScript

import { getUserData } from '@monterosa/sdk-identify-kit';
import { MonterosaError } from '@monterosa/sdk-util';

try {
  const userData = await getUserData(identify);

  console.log(userData);
} catch (err) {
  if (err instanceof MonterosaError) {
    // Inspect err.code to handle each case, see Error handling below.
    console.error(err.code, err.message);
  }

Update user data

updateUserData() lets you send a data object to the Identify API to update the user's information. The fields you can update depend on your SSO provider. The SDK does not change the data, it sends it as you provide. If the update is successful, the returned value will update the cached user data in the SDK.

JavaScript

import { updateUserData } from '@monterosa/sdk-identify-kit';
import { MonterosaError } from '@monterosa/sdk-util';

try {
  const userData = await updateUserData(identify, {
    username: 'John Doe',
    appProfile: {
      favouriteTeam: 'lakers',
      notifications: { push: true },
    },
  });

  console.log(userData);
} catch (err) {
  if (err instanceof MonterosaError) {
    // Inspect err.code to handle each case, see Error handling below.
    console.error(err.code, err.message);
  }
}

Real-world example: Fan profile onboarding

Here is a concrete scenario in the fan engagement context:

A football Experience asks a fan to complete a short profile step before their first prediction. The fan chooses a display name, favourite team, and notification preference. The app saves this data using updateUserData:

JavaScript

import { getIdentify, updateUserData } from '@monterosa/sdk-identify-kit';
import { MonterosaError } from '@monterosa/sdk-util';

const identify = getIdentify();

async function saveProfile({ displayName, favouriteTeam, pushOptIn }) {
  try {
    const userData = await updateUserData(identify, {
      username: displayName,
      appProfile: {
        favouriteTeam,
        notifications: { push: pushOptIn },
        onboardingComplete: true,
        marketingConsent: { granted: pushOptIn, updatedAt: Date.now() },
      },
    });

    renderProfileBadge(userData.username, userData.appProfile.favouriteTeam);
  } catch (err) {
    if (err instanceof MonterosaError) {
      showRetryPrompt();
    }
  }
}

Access Gating: listening for login requests and triggering your login flow

Some Experiences may require login upfront and others may support login-gated content at a specific point in the user journey, for example a "Login or Register" call to action when the user tries to access restricted content.

When the user reaches that point, a request to login is sent from the Experience, via the SDK, to your parent app or site. Your code will be listening for those messages and from there, you will trigger the same login flow in your application.

In order to capture that notification and integrate your own login flow, you’ll need to implement listeners to onLoginRequestedByExperience:

iOS

let delegate = IdentifyViewController()
Identify.default.add(delegate: delegate)

class IdentifyViewController: IdentifyKitAPIDelegate {
    func didRequestLoginByExperience() {
        // Implement here
    }
}

Android

identifyKit.add(object : IdentifyKitListener {
    override fun onLoginRequestedByExperience() {
        // your code here
    }
})

JavaScript

import { 
  getIdentify,
  onLoginRequestedByExperience,
} from "@monterosa/sdk-identify-kit";

const identify = getIdentify();
const unsub = onLoginRequestedByExperience(identify, () => {
  // Implement here
});

Listening to credentials validation failure

The onCredentialsValidationFailed() function enables you to set up an event listener that is triggered when a credential validation failure occurs. This listener is invoked regardless of who initiates the call to Identify (whether the Experience or the App) and who is subscribed to it, as well as the kind of error.

iOS

let delegate = IdentifyViewController()
Identify.default.add(delegate: delegate)

class IdentifyViewController: IdentifyKitAPIDelegate {
    func didFailCredentialsValidation(error: Error) {
        // Implement here
    }
}

Android

Android snippet

identifyKit.add(object : IdentifyKitListener {
    override fun onCredentialsValidationFailed(exception: Exception) {
        // your code here
    }
})

JavaScript

import {
  getIdentify,
  onCredentialsValidationFailed,
} from "@monterosa/sdk-identify-kit";

const identify = getIdentify();
const unsub = onCredentialsValidationFailed(identify, (error) => {
  console.log(error);
});

Is there support for Open ID Connect (OIDC)

Yes, our platform supports Open ID Connect (OIDC) for seamless identity management. Connect with any OIDC-compliant provider to enable secure single sign-on, maintain consistent user identities across platforms, and leverage your existing authentication infrastructure.