Android SDK Migration Guide

Android specific migration guide for the May 2025 GYP migration.

Overview

Lucra is launching a major update to the Games You Play (GYP) product. See here for the full description of the changes.

Legacy SDKs and API endpoints will continue to function. However, once a client targets the new SDK versions, all related backend interactions must be updated to the new endpoints. Legacy APIs will not be forward-compatible with the new matchup models.

Further, it is recommended to feature gate mobile version updates so that users on older builds (of iOS or Android apps) don't attempt to create and share old GYP matchups against users who have the updated version.

Migration Guide

Retrieving a Matchup

The function signature has changed for retrieving a matchup.

Before migration

fun getGamesMatchup(
    matchupId: String, 
    onResult: (LegacyMatchup) -> Unit
)

After migration

/**
 * Retrieve matchup with the given id and returns result.
 * @param matchupId id of the games matchup
 * @param onResult callback with a [GetMatchupResult]
 */
fun getMatchup(
    matchupId: String,
    onResult: (GetMatchupResult) -> Unit
)

The new result type GetMatchupResult is structured like below:

sealed interface GetMatchupResult {
    data class Success(val matchup: LucraMatchup) : GetMatchupResult
    data class Failure(val failure: FailedRetrieveMatchup) : GetMatchupResult
}

On success

data class LucraMatchup(
    val id: String,
    val updatedAt: String,
    val createdAt: String,
    val creatorId: String,
    val creator: LucraUser?,
    val participantGroups: List<ParticipantGroup>,
    val winningGroup: ParticipantGroup?,
    val isPublic: Boolean,
    val status: MatchupType.Status,
    val subtype: MatchupSubtype,
    val type: TopLevelMatchupSubType,
    val recreationGameExtension: LucraMatchupRecreationalGameExtension?
)

// Format of the game
enum class MatchupSubtype {
    GroupVsGroup,
    FreeForAll,
}

// Contains informations specific to recreational games
data class LucraMatchupRecreationalGameExtension(
    val gameId: String,
    val atStake: AtStake,
    val game: RecreationalGameDetails?,
)

On failure

/**
 * [LocationError] any error involving the current user location (ex: banned state)
 * [APIError] all other errors
 */
sealed interface FailedRetrieveMatchup {
    data class LocationError(val message: String) : FailedRetrieveMatchup
    data class APIError(val message: String) : FailedRetrieveMatchup
}

Creating a Matchup

Function signature has changed to include new parameter playStyle as well as being able to specify the type of reward this matchup offers through RewardType.

Before migration

fun createContest(
    gameTypeId: String, 
    atStake: Double, 
    onResult: (CreateGamesMatchupResult) -> Unit
)

After migration

/**
 * Create a recreational game and returns result.
 * @param gameTypeId id of the game type
 * @param atStake type of reward being wagered
 * @param playStyle style of play
 * @param onResult callback with a [CreateGamesMatchupResult]
 */
fun createRecreationalGame(
    gameTypeId: String,
    atStake: RewardType,
    playStyle: PlayStyle,
    onResult: (CreateGamesMatchupResult) -> Unit
)

/**
 * Types of rewards that can be wagered in a recreational game.
 * [Cash] is a cash amount denominated in dollars. Ex: $5 = 5.00
 * [TenantReward] is a reward that is provided by the tenant.
 */
sealed interface RewardType {
    data class Cash(val amount: Double) : RewardType
    data class TenantReward(
        val rewardId: String,
        val title: String,
        val descriptor: String,
        val iconUrl: String,
        val bannerIconUrl: String?,
        val disclaimer: String?,
        val metadata: Map<String, String>?
    ) : RewardType, Serializable
}

/**
 * Types of play styles that can be used in a recreational game.
 * [GroupVsGroup] is where 2 teams compete against each other.
 * [FreeForAll] is a free for all game.
 */
enum class PlayStyle {
    GroupVsGroup,
    FreeForAll,
}

Accepting a Matchup

We have introduced a new function to specifically accept a recreational game of respective types. Meaning, you must differentiate between Group Play and Free-for-All formats when accepting a matchup.

/**
* Accept the Group v Group contest with the given id and returns result.
* @param matchupId id of the contest
* @param teamId id of the team the user wants to join
* @param onResult callback with a [AcceptRecreationalGameResult]
*/
fun acceptVersusRecreationalGame(
   matchupId: String,
   teamId: String,
   onResult: (AcceptRecreationalGameResult) -> Unit
)

/**
* Accept the Free for All contest with the given id and returns result.
* @param matchupId id of the contest
* @param onResult callback with a [AcceptRecreationalGameResult]
*/
fun acceptFreeForAllRecreationalGame(
   matchupId: String,
   onResult: (AcceptRecreationalGameResult) -> Unit
)

Cancelling a Matchup

Function name and return type has been updated.

Before migration

fun cancelGamesYouPlayContest(
    matchupId: String,
    onResult: (MatchupActionResult) -> Unit
)

After migration

/**
* Cancels the contest with the given id and returns result.
* @param matchupId id of the contest
* @param onResult callback with a [CancelGamesMatchupResult]
*/
fun cancelRecreationalGame(
   matchupId: String,
   onResult: (CancelGamesMatchupResult) -> Unit
)

Return types for recreational games specific actions

For recreational games specific actions above (create, accept, cancel), we have new return types that is either success or failure:

sealed interface AcceptRecreationalGameResult {
    data class Success(val matchupId: String) : AcceptRecreationalGameResult
    data class Failure(val failure: LucraError) : AcceptRecreationalGameResult
}

sealed interface CreateGamesMatchupResult {
    data class Success(val matchupId: String) : CreateGamesMatchupResult
    data class Failure(val failure: LucraError) : CreateGamesMatchupResult
}

sealed interface CancelGamesMatchupResult {
    data class Success(val matchupId: String) : CancelGamesMatchupResult
    data class Failure(val failure: LucraError) : CancelGamesMatchupResult
}

/**
 * [UserStateError] any error involving the current user account status or available funds
 * [LocationError] any error involving the current user location (ex: banned state)
 * [APIError] all other errors
 */
sealed interface LucraError

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