API Module

To utilize the API layer will require both using the Frontend SDK as well as integrating several API calls on your Backend to set/fetch data to/from the Lucra system at appropriate times. View the API Integration document for more information.

Interacting with APIs

Use Lucra instance easily by invoking the class operator LucraClient().* or fetching the instance LucraClient.getInstance().*

Once you have the instance, you can interact with our headless SDK methods:

User API

Get and update the current user's properties

Methods

observeSDKUserFlow, observeSDKUser

Observe the active SDKUser based on authed status.

• Example usage:

private fun observeLoggedInUser() {
  // Or use observeSDKUser { result -> ... }
  LucraClient().observeSDKUserFlow().onEach { sdkUserResult ->
    when (sdkUserResult) {
      is SDKUserResult.Success -> {
        Log.d("Lucra SDK Sample", "Fetched latest user")
        lucraSDKUser = sdkUserResult.sdkUser
      }

      is SDKUserResult.Error -> {
        Log.e("Lucra SDK Sample", "Unable to get username ${sdkUserResult.error}")
        lucraSDKUser = null
      }

      SDKUserResult.InvalidUsername -> {
        // Shouldn't happen here
      }

      SDKUserResult.NotLoggedIn -> {
        Log.e(
          "Lucra SDK Sample",
          "User not logged in yet!"
        )
        lucraSDKUser = null
      }

      SDKUserResult.Loading -> {

      }
    }
  }.launchIn(lifecycleScope)
}

Configure User

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

Logs out the current user, if any

• Example usage:

 LucraClient().logout(context)

GamesMatchup API

The GamesMatchup interface provides methods to manage game contests. It allows users to create, accept, and cancel contests. Each method provides a callback mechanism to handle the result of the operation.

Methods

createGamesMatchup

Creates a new game contest.

• Parameters:

  • gameTypeId: ID associated with the game type.

  • atStake: Amount of money being wagered.

  • onResult: Callback with a result of type CreateGamesMatchupResult.

• Example usage:

LucraClient().createContest(
    gameTypeId = "gameTypeId",
    atStake = 25.0
) { result ->
    when (result) {
        is CreateGamesMatchupResult.Failure -> {
            // Handle failure scenario
        }
        is CreateGamesMatchupResult.GYPCreatedMatchupOutput -> {
            // Handle success scenario
        }
    }
}

acceptGamesMatchup

Accepts a contest with the given ID.

• Parameters:

  • matchupId: ID of the contest.

  • teamId: ID of the team the user wants to join.

  • onResult: Callback with a result of type MatchupActionResult.

• Example usage:

LucraClient().acceptGamesYouPlayContest(
    matchupId = "matchupId",
    teamId = "teamId"
) { result ->
    when (result) {
        is MatchupActionResult.Failure -> {
            // Handle failure scenario
        }
        MatchupActionResult.Success -> {
            // Handle success scenario
        }
    }
}

retrieveGamesMatchup

Retrieve a contest with the given ID.

• Parameters:

  • matchupId: ID of the contest.

  • onResult: Callback with a result of type RetrieveGamesMatchupResult.

• Example usage:

LucraClient().getGamesMatchup(
    matchupId = "matchupId",
) { result ->
    when (result) {
        is RetrieveGamesMatchupResult.Failure -> {
            // Handle failure scenario
        }
        RetrieveGamesMatchupResult.GYPMatchupDetailsOutput -> {
            // Handle success scenario
        }
    }
}

cancelGamesMatchup

Cancels a contest with the given ID.

• Parameters:

  • matchupId: ID of the contest.

  • onResult: Callback with a result of type MatchupActionResult.

• Example usage:

LucraClient().cancelGamesYouPlayContest(matchupId = "matchupId") { result ->
    when (result) {
        is MatchupActionResult.Failure -> {
            // Handle failure scenario
        }
        MatchupActionResult.Success -> {
            // Handle success scenario
        }
    }
}

retrieveSportsMatchup

Retrieve a sports contest with the given ID.

• Parameters:

  • matchupId: ID of the contest.

  • onResult: Callback with a result of type RetrieveGamesMatchupResult.

• Example usage:

LucraClient().getSportsMatchup(
    matchupId = "matchupId",
) { result ->
    when (result) {
        is RetrieveSportsMatchupResult.Failure -> {
            // Handle failure scenario
        }
        RetrieveSportsMatchupResult.SportsMatchupDetailsOutput -> {
            // Handle success scenario
        }
    }
}

Tournaments API

The Tournament interface provides methods to join and retrieve tournament matchups. Each method provides a callback mechanism to handle the results of the operation.

Methods

retrieveTournament

Retrieve a tournament with a given ID.

• Parameters:

  • tournamentId: ID associated with the tournament.

  • onResult: Callback with a result of type RetrieveTournamentResult

• Example usage:

LucraClient().retrieveTournament(tournamentId = "tournamentId") { result ->
    when (result) {
        is RetrieveTournamentResult.Failure -> {
            // Handle failure scenario
        }
        RetrieveTournamentResult.Success -> {
            // Handle success scenario
        }
    }
}

queryRecommendedTournaments

Retrieve a list of recommended tournaments.

• Parameters:

  • limit: The max number tournaments that will be returned.

  • offset: The starting index of the query.

  • includeCompletedTournaments: Should completed tournaments be included in the query.

  • onResult: Callback with a result of type QueryRecommendedTournamentsResult

• Example usage:

LucraClient().queryRecommendedTournaments(
  limit = 50,
  offset = 0,
  includeCompletedTournaments = true,
) { result ->
    when (result) {
        is QueryRecommendedTournamentsResult.Failure -> {
            // Handle failure scenario
        }
        QueryRecommendedTournamentsResult.Success -> {
            // Handle success scenario
        }
    }
}

joinTournament

Join a tournament with a given ID.

• Parameters:

  • tournamentId: ID associated with the tournament.

  • onResult: Callback with a result of type JoinTournamentResult

• Example usage:

LucraClient().joinTournament(tournamentId = "tournamentId") { result ->
    when (result) {
        is JoinTournamentResult.Failure -> {
            // Handle failure scenario
        }
        JoinTournamentResult.Success -> {
            // Handle success scenario
        }
    }
}

setDeeplinkTransformer

Sets lambda function that will be used to transform original lucra URI to client specific URI. Make sure to keep the original URI in the process to allow conversion into LucraFlow later.

• Parameters:

  • suspend (String) -> String: suspended string transformer lambda

• Example usage:

LucraClient().setDeeplinkTransformer { originalUri ->
    transformUriToAppLink(originalUri)
}

getLucraFlowForDeeplinkUri

Convert lucra URI (ex: lucra://...) into LucraFlow that can be launched to show a UI component.

• Parameters:

  • uri: uri string to convert into a LucraFlow

• Example usage:

LucraClient().apply {
  getLucraFlowForDeeplinkUri("uriString")?.let { lucraFlow ->
    getLucraDialogFragment(lucraFlow).also { fragment ->
      fragment.show(supportFragmentManager, lucraFlow.toString())
    }
  }
}

Result Types

MatchupActionResult

Represents the result of an operation on an existing GamesMatchup.

• Success: Represents a successful operation.

• Failure: Represents a failed operation. Contains a failure of type FailedCreateGamesMatchup.

CreateGamesMatchupResult

Represents the result of creating a GamesMatchup.

• GYPCreatedMatchupOutput: Represents a successfully created matchup. Contains matchupId, ownerTeamId, and opponentTeamId.

• Failure: Represents a failed operation. Contains a failure of type FailedCreateGamesMatchup.

Error Types

FailedCreateGamesMatchup

Represents the types of errors that can occur when creating a GamesMatchup.

• UserStateError: Errors related to the current user account status or available funds.

  • NotInitialized: User account is not initialized.

  • Unverified: User account is unverified.

  • NotAllowed: User is not allowed to perform the operation.

  • InsufficientFunds: User has insufficient funds.

• LocationError: Errors related to the user's location. Contains a message.

• APIError: All other errors. Contains a message.

Get User's KYC Status

Fetching the KYC status will determine if the current user is verified or not, allowing for money and sports contest interactions. If the user is not verified, launch the VerifyIdentity LucraFlow.

Methods

checkUsersKYCStatus

Returns the status of the current logged in user.

• Parameters:

  • userId: ID associated to the current user (see)

  • lucraKYCStatusListener: Listener to implement specific callbacks for KYC interaction

• Example usage:

    LucraClient().checkUsersKYCStatus(
        "user-id", //fetched from #getSDKUser
        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()
                if (!isVerified) 
                    launchFlow(LucraUiProvider.LucraFlow.VerifyIdentity)
            }
        })

Event listeners

setEventListener

Sets a event listener so you can listen for Lucra-specific events that occur with the SDK. A LucraEvent may hold data associated with the event (ex: LucraEvent.SportsContest.Create holds a contestId).

• Parameters:

  • LucraEventListener: listener used to receive a LucraEvent

• Example usage:

LucraClient().setEventListener(object : LucraEventListener {
  override fun onEvent(event: LucraEvent) {
    //Handle Events
  }
})

// Available LucraEvents
sealed class LucraEvent {
    sealed class GamesContest : LucraEvent() {
        data class Accepted(val contestId: String?) : GamesContest()
        data class Created(val contestId: String?) : GamesContest()
        data class Canceled(val matchupId: String?) : GamesContest()
    }

    sealed class SportsContest : LucraEvent() {
        data class Accepted(val contestId: String?) : GamesContest()
        data class Created(val contestId: String?) : SportsContest()
        data class Canceled(val matchupId: String?) : SportsContest()
    }

    sealed class Tournament : LucraEvent() {
        data class Joined(val tournamentId: String?) : Tournament()
    }
}