Interacting with Lucra Headless Functionality

After the user logs into the Lucra SDK through the experience, the following headless methods are available to interact with user configuration, Games, Tournaments, Sports Matchups, and more.

Begin interacting with headless functions by obtaining an instance of LucraClient via its singleton reference LucraClient() or LucraClient.getInstance(). Both are functionally equivalent; getInstance() may be more convenient for Java consumers.

All headless functions return a sealed class type, enforcing exhaustive when statements to ensure all outcomes—including errors—are handled predictably.

⚠️ Initialize first: Headless calls will fail if invoked before the SDK finishes initializing. Gate your calls with waitForLucraClient:

• Coroutine (Kotlin):

  CoroutineScope(Dispatchers.Main).launch {
    val lucraClient = LucraClient.waitForLucraClient()
    // now safe to make headless calls
  }

• Callback (Java/Kotlin):

  LucraClient.waitForLucraClient(
      () -> {
        // now safe to make headless calls
      },
      throwable -> {
        // optional failure handling
      }
  );

See initialization details in Initialize the LucraClient.

---

Games Related Headless Methods

See here

Tournaments Related Headless Methods

See here

User Related Headless Methods

Observe the Lucra SDK User

Description: Observe the active SDKUser based on authentication status. Useful for determining when the user is logged in.

Methods:

• observeSDKUserFlow() — coroutine-based

• observeSDKUser(callback) — callback-based

Example:

private fun observeLoggedInUser() {
  LucraClient().observeSDKUserFlow().onEach { sdkUserResult ->
    when (sdkUserResult) {
      is SDKUserResult.Success -> {
        Log.d("Lucra SDK Sample", "Fetched latest user")
      }
      is SDKUserResult.Error -> {
        Log.e("Lucra SDK Sample", "Unable to determine authed in status ${sdkUserResult.error}")
      }
      SDKUserResult.InvalidUsername -> {
        // Only returned from username update flow
      }
      SDKUserResult.NotLoggedIn -> {}
      SDKUserResult.Loading -> {}
    }
  }.launchIn(lifecycleScope)
}

Response Type: SDKUserResult

---

Configure User Properties

Description: Pushes profile attributes into Lucra for the currently authenticated user. Only non-null values on the supplied SDKUser are submitted.

If configure is invoked before the Lucra session is established, the request is queued and automatically retried after login. Deprecated properties such as birthday are ignored. Any values sent here are also surfaced inside LucraFlow.VerifyIdentity, minimizing what the user must re-enter during KYC.

Phone number implications

• Provide phoneNumber only when you intend to bind the Lucra account to that value. After the number is verified, the SDK login flow requires the same phone for future authentications.

• Skip the field (or pass null) if you prefer Lucra to collect and manage the phone number directly.

• Whatever value you send appears pre-filled in the Verify Identity flow.

User metadata implications

• Use metadata to pass identifiers and traits from your system. This is a Map of Strings to Strings, an external_id entry (example: "external_id" to clientUserId) is recommended at minimum to bind your users to Lucra users. Which will help for score submission and other identifying properties from Lucra systems.

Method:

• configure(SDKUser, onResult: (SDKUserResult) -> Unit)

Example:

LucraClient().configure(
  SDKUser(
      username = "lucra_champ23",
      email = "[email protected]",
      phoneNumber = "[phone]",
      firstName = "Jamie",
      lastName = "Rivera",
      address = "123 Main Street",
      city = "Austin",
      state = "TX",
      zip = "78701",
      avatarUrl = "https://cdn.example.com/avatars/jamie.png",
      metadata = mapOf(
        "external_id" to "...",
        "store" to "dallas",
      )
  )
) { result ->
  when (result) {
    is SDKUserResult.Success -> {
      Log.d("Lucra SDK Sample", "Profile updated")
    }
    is SDKUserResult.WaitingForLogin -> {
      Log.d("Lucra SDK Sample", "Queued profile update until Lucra login completes")
    }
    SDKUserResult.InvalidUsername -> {
      Log.w("Lucra SDK Sample", "Username failed validation")
    }
    is SDKUserResult.Error -> {
      Log.e("Lucra SDK Sample", "Profile update failed", result.error)
    }
    SDKUserResult.NotLoggedIn -> {
      // configure waits for login, so this state is unlikely
    }
    SDKUserResult.Loading -> {
      // no-op: configure never returns Loading, but maintain exhaustiveness
    }
  }
}

Response Type: SDKUserResult

---

Logout User

Description: Logs out the current user if one is authenticated.

Method:

• logout(context)

Example:

LucraClient().logout(context)

Response Type: Unit

---

Get User's KYC Status

Description: Returns whether the current user is KYC-verified. Useful for checking ahead of launching money or matchup interactions. Most flows will automatically handle verification.

Method:

• checkUsersKYCStatus(userId: String, lucraKYCStatusListener: LucraKYCStatusListener)

Example:

LucraClient().checkUsersKYCStatus(
  "user-id",
  object : LucraClient.LucraKYCStatusListener {
    override fun onKYCStatusCheckFailed(exception: Exception) {
      Toast.makeText(
        this@MainActivitySdk,
        "Verified Failed ${exception}",
        Toast.LENGTH_LONG
      ).show()
    }

    override fun onKYCStatusAvailable(isVerified: Boolean) {
      Toast.makeText(this@MainActivitySdk, "Verified Success", Toast.LENGTH_LONG).show()
      launchFlow(LucraUiProvider.LucraFlow.VerifyIdentity)
    }
  }
)

Response Type:

• onKYCStatusAvailable(isVerified: Boolean)

• onKYCStatusCheckFailed(exception: Exception)

---

Update Username

Description: Updates the username for the current SDKUser. If the new username is the same as the current one, the operation will return InvalidUsername. Throws IllegalStateException if the Lucra SDK has not been properly initialized.

Method:

• updateUsername(sdkUser: SDKUser, newUsername: String, onResult: (SDKUserResult) -> Unit)

Example:

LucraClient().updateUsername(currentUser, "newUsername") { result ->
  when (result) {
    is SDKUserResult.Success -> {
      // Username updated successfully
    }
    SDKUserResult.InvalidUsername -> {
      // New username is the same as the current one
    }
    is SDKUserResult.Error -> {
      // An error occurred
    }
    else -> {
      // Handle other states if needed
    }
  }
}