🔐 REL-ID SDK Event: activateUserOption

🧭 Overview

The activateUserOption event is triggered by the REL-ID SDK during the device activation process. It provides the application with a list of authentication methods that the user can choose from to complete the device activation.

Once an option is selected by the user (e.g., Password, Fingerprint, Pattern), the app must invoke the corresponding activateUsing(<AUTHENTICATION_TYPE>) API to initiate the challenge for that method.

🧪 Purpose

• To prompt the user to select their preferred authentication method.
• To launch the proper challenge screen (password input, biometric, etc.)
• Ensures secure user consent during first or additional device activation.

🧭 When is activateUserOption Triggered?

It typically occurs:

1. After the user's identity has been verified through a primary method (e.g., setPassword or performVerifyAuth)
2. Before device registration is finalized (before getDeviceName / onDeviceActivated)
3. When the SDK wants the user to confirm their authentication method for enabling LDA (Local Device Authentication) — like Fingerprint, Pattern, or Password for future unlocks

🧩 Sample Payload

{
  "userID": "testuser",
  "newUserOptions": ["FingerPrint", "Pattern", "Password"],
  "challengeInfo": [
    { "key": "Response label", "value": "Password" },
    { "key": "description", "value": "Enter password of length 8-10 characters" },
    { "key": "SDK_CHLNG", "value": "YES" },
    { "key": "SDK_CHLNG_MODE", "value": "SEMIAUTO" },
    { "key": "PASSWORD_POLICY", "value": "{"minL":8,"maxL":16,"minLc":1,"minDg":1,"minUc":1,"minSc":1,"Repetition":2,"UserIDcheck":"true","msg":"Password must contain 8-16 characters, including at least 1 uppercase, 1 lowercase, 1 number and special characters"}" },
    { "key": "IS_USER_PASS", "value": "true" },
    { "key": "ENABLE_FORGOT_PASSWORD", "value": "true" },
    { "key": "PASS_EXP_TS", "value": "1643291663000" },
    { "key": "MIN_PASS_AGE_TS", "value": "" },
    { "key": "DEV_MGMT_COOL_TS", "value": "-1" }
  ]
}

🧠 Fields Explained

Challenge Info Keys

🛠️ Developer Responsibilities

1. Listen to activateUserOption event in your app.
2. Display newUserOptions to the user.
3. Upon selection, call the API activateUsing

RdnaClient.activateUsing("Password"); // or FingerPrint, Pattern

🛠️ REL-ID SDK API: activateUsing

🧭 Overview

The activateUsing API is used in response to the activateUserOption event. It initiates a local challenge such as password, fingerprint, or pattern based on the user’s selection. This step is crucial for configuring Local Device Authentication (LDA) for the current device during the activation process.

🎯 Purpose

• Finalizes the authentication method the user wants to use on this device.
• Ensures secure local unlock for future sessions.
• Completes user consent for enabling on-device authentication.

🔁 When to Use

1. After receiving the activateUserOption event.
2. Once the user selects an option from newUserOptions (e.g., "Password", "FingerPrint", "Pattern").
3. App calls activateUsing("option") to confirm and activate that challenge type.

🧩 Supported Authentication Types

These are determined by the values present in newUserOptions.

🔧 API: activateUsing(optionType)

📥 Parameter

💻 Code Snippets

RdnaClient.activateUsing("Password", (response) => {
  console.log("Activated using selected option:", response);
});

rdnaClient.activateUsing("FingerPrint");

com.uniken.rdnaplugin.RdnaClient.activateUsing(
  () => console.log("Activated"),
  (err) => console.error("Failed", err),
  ["Pattern"]
);

rdnaClient.activateUsing("Password");

[client activateUsing:@"Password"];

✅ On Success

• Selected LDA method is stored and configured for the device.
• SDK proceeds to the next activation step (getDeviceName → setDeviceName).

❌ On Failure

• SDK may re-emit activateUserOption to let user retry or choose a different method.
• App should inform the user and allow a fallback path.

💻 Code Snippets

rdnaEventRegistery.addListener('activateUserOption', (event) => {
  const options = event.newUserOptions;
  const challengeInfo = event.challengeInfo;
  // Show these options to user, then on selection:
  RdnaClient.activateUsing("Password");
});

rdnaClient.on(RdnaClient.activateUserOptions, (response) {
  final options = response.newUserOptions;
  rdnaClient.activateUsing("Password");
});

document.addEventListener('activateUserOption', function(event) {
  const options = event.newUserOptions;
  activateUsing("Password");
});

[rdnaClient activateUserOptions:userID options:options info:info];

rdnaClient.activateUsing("Password");

✅ On Success

• SDK moves to corresponding challenge screen.
• User completes authentication and proceeds with device activation.

❌ On Failure

• If authentication fails, SDK may re-trigger activateUserOption or fail activation.
• App should allow retry or show fallback options.