Android SDK (Tournaments)

Overview

The Pool Tournament feature allows end users to join pre-created tournaments and earn rewards based on their ranking at the end of the matchup.

The outcome and payout structure of each pool must be provided to Lucra using these API endpoints

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
        }
    }
}

submitUserScore

Submit a tournament score for a user.

• Parameters:

  • score: The score for the given attempt.

  • tournamentId: The unique ID of the tournament.

  • isFinal: If this is the user's final attempt.

  • metadata: The metadata to include with the payload.

  • onResult: Callback with a result of type SubmitTournamentScoreResult;

• Example usage:

LucraClient().submitUserScore(
  score = 25,
  tournamentId = "tournamentId",
  isFinal = false,
  metadata = mapOf("key" to "value"),
) { result ->
    when (result) {
        is SubmitTournamentScoreResult.Failure -> {
            // Handle failure scenario
        }
        SubmitTournamentScoreResult.Success -> {
            // Handle success scenario
        }
    }
}

Errors:

• Throws an error if:

  • The user is not in a valid state to submit a score.

  • Request is has invalid data

  • Location services fail to provide coordinates.

  • A general network or API error occurs.

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

Errors:

• Throws an error if:

  • The user is not in a valid state to join.

  • Location services fail to provide coordinates.

  • Compliance validation fails.

    • If free buy in tournament, user demographic info is missing

  • Insufficient funds prevent the user from joining.

  • A general network or API error occurs.

User State Errors (account-related issues):

• NotInitialized - User session not properly set up or account data missing

• Unverified - User hasn't completed identity verification (KYC) for real-money tournaments

• NotAllowed - User account restricted, suspended, or ineligible

• InsufficientFunds - Not enough balance for paid tournament entry

• DemographicInformationMissing - Missing email/zip code for free tournaments

Location Errors:

• LocationError - Geographic restrictions (banned states, location services disabled, GeoComply failures)

API Errors:

• APIError - Network issues, server errors, invalid responses, rate limits

These errors occur during tournament operations (retrieve, join, query) and help determine the appropriate user-facing message and recovery action.

sealed interface FailedTournamentCall {
    sealed interface UserStateError : FailedTournamentCall {
        data object NotInitialized : UserStateError
        data object Unverified : UserStateError
        data object NotAllowed : UserStateError
        data object InsufficientFunds : UserStateError
        data object DemographicInformationMissing : FailedTournamentCall
    }
    data class LocationError(val message: String) : FailedTournamentCall
    data class APIError(val message: String) : FailedTournamentCall
}

Example usage:

Simple headless join by ID

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

Headless join with handling for missing demographic info.

LucraClient().joinTournament(tournamentId = "tournament_123") { result ->
    when (result) {
        is JoinTournamentResult.Success -> {
            // Tournament joined successfully
            showMessage("Successfully joined tournament!")
        }

        is JoinTournamentResult.Failure -> {
            when (val error = result.failure) {
                ...
                // Handle free tournament demographic requirement
                is DemographicInformationMissing -> {
                    showDialog(
                        title = "Demographic Information Required",
                        message = "Please complete your demographic information to join free tournaments.",
                        positiveAction = {
                            launchFlow(LucraUiProvider.LucraFlow.DemographicForm)
                        }
                    )
                }
                ...
            }
        }
    }
}

Launching Demographic Form Independently

This feature was introduced in SDK version 5.0.0 and enhances the free buy-in tournament joining experience by ensuring users provide minimum necessary demographic information for compliance and improved user experience.

// Launch demographic collection form as a standalone flow
val demographicFlow = LucraUiProvider.LucraFlow.DemographicForm

// Using DialogFragment (recommended for full-screen experience)
val dialogFragment = LucraClient().getLucraDialogFragment(demographicFlow)
dialogFragment.show(supportFragmentManager, "DemographicForm")

3. Manual Demographic Data Validation

// Check if user has required demographic data before tournament operations
LucraClient().observeSDKUserFlow().collect { userResult ->
    when (userResult) {
        is SDKUserResult.Success -> {
            val user = userResult.sdkUser
            val hasRequiredData = !isMissingDemographicData(user)
            updateUI(hasRequiredData)
        }
        // Handle other states...
    }
}

private fun isMissingDemographicData(user: SDKUser): Boolean {
    return user.email.isNullOrEmpty() || user.zip.isNullOrEmpty()
}

Migration Guide

For Existing Integrators

If you're updating from an older SDK version:

1. Additive change - existing tournament joining code continues to work

2. New error handling - add handling for DemographicInformationMissing error

Example Migration

Before:

LucraClient().joinTournament(tournamentId) { result ->
    when (result) {
        is JoinTournamentResult.Success -> { /* handle success */ }
        is JoinTournamentResult.Failure -> {
            // Only handled KYC errors before
            if (result.failure is FailedTournamentCall.UserStateError.Unverified) {
                launchFlow(LucraUiProvider.LucraFlow.VerifyIdentity)
            }
            ...
        }
    }
}

After:

LucraClient().joinTournament(tournamentId) { result ->
    when (result) {
        is JoinTournamentResult.Success -> { /* handle success */ }
        is JoinTournamentResult.Failure -> {
            when (result.failure) {
                is FailedTournamentCall.UserStateError.Unverified -> {
                    launchFlow(LucraUiProvider.LucraFlow.VerifyIdentity)
                }
                is FailedTournamentCall.DemographicInformationMissing -> {
                    launchFlow(LucraUiProvider.LucraFlow.DemographicForm)
                }
                ...
            }
        }
    }
}

Troubleshooting

Common Issues

• Demographic form not launching for free tournaments.

  • Ensure user authentication is complete before attempting to join tournaments

• Form not auto-filling previously entered data

  • The form should auto-fill based on saved user data. If not working, check user authentication state

• DemographicInformationMissing error not being handled.

  • Add the new error case to your tournament joining error handling