iOS 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

getRecommendedTournaments

Retrieve a list of recommended tournaments.

Parameters:

• includeClosed (Bool, default: true): Whether to include tournaments that have already ended.

• limit (Int, default: 50): The maximum number of tournaments to return.

Return:

An array of type [TournamentsMatchup].

Errors:

• Throws an error if the network request fails or data is unavailable.

Example Usage:

do {
    let tournaments = try await lucraClient.api.getRecommendedTournaments(includeClosed: false, limit: 25)
    // Process the tournaments list
} catch {
    // Handle error
    print("Failed to fetch recommended tournaments: \(error)")
}

---

tournamentsMatchup(for:)

Retrieve a tournament matchup by its unique ID.

Parameters:

• matchupID (String): The ID of the tournament matchup to retrieve.

Return:

An optional TournamentsMatchup instance, which contains details about the specific tournament.

Errors:

• Throws an error if the network request fails or the tournament cannot be found.

Example Usage:

do {
    if let tournament = try await lucraClient.api.tournamentsMatchup(for: "matchupId") {
        // Process the tournament details
    } else {
        print("Tournament not found.")
    }
} catch {
    // Handle error
    print("Failed to retrieve tournament matchup: \(error)")
}

---

submitUserScore(_:tournamentID:metadata:isFinal:)

Update the logged-in user’s score for a specific tournament matchup.

Parameters

• score (Integer): The numeric score to record for the current attempt.

• tournamentID (String): The identifier of the tournament matchup receiving the score.

• metadata (Dictionary of String to String): Additional key-value data to attach to the score submission.

• isFinal (Boolean): Indicates whether this attempt should be treated as the user’s final score.

Return An optional TournamentsMatchup reflecting the updated matchup state returned by the mutation.

Errors Throws when the user’s account status disallows submissions, when location or compliance checks fail, or when the score update mutation cannot be completed.

Example Usage

do { 
if let updatedMatchup = try await lucraClient.api.submitUserScore(42,
 tournamentID: "matchupId", 
 metadata: ["round": "1"], 
 isFinal: false) {
  // Handle updated matchup details
   }
 } catch { 
 // Handle error path print("Score submission failed: \(error)") 
 }

---

joinTournament

Join a tournament with a given ID.

Parameters:

• id (String): The ID of the tournament to join.

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.

public enum JoinTournamentError: Error {
    case userNotInitialized
    case userBlockedOrSuspended
    case demographicCollectionPending
    case unverified
    case insufficientFunds
    case unableToDetermineLocation(error: Error)
    case coreLocationError(clError: CLError)
    case unauthorizedLocationError
    case customError(message: String)
    case unknown
}

Example Usage:

Simple headless join by ID

do {
    try await lucraClient.api.joinTournament(id: "matchupId")
    print("Successfully joined the tournament.")
} catch UserStateError.insufficientFunds {
    print("Unable to join: Insufficient funds.")
} catch {
    // Handle other errors
    print("Failed to join tournament: \(error)")
}

Headless join with handling for missing demographic info.

Task { @MainActor in
    let result = await lucraClient.api.joinTournament(id: "matchupId")

    switch result {
    case .success(let success):
        showMessage("Successfully joined tournament!")
    case .failure(let failure):
        switch failure {
        case .demographicCollectionPending:
            showAlert(title: "Demographic Information Required",
                      message: "Please complete your demographic information to join free tournaments.",
                      action: {
                let flow: some View = lucraClient.ui.flow(.demographicCollection)
                launchFlow(flow)
            })
            
        // Handle other failure cases as appropriate.
        case .unverified:
            ...
        default:
            ...
        }
    }
}

Launching Demographic Form Independently

This feature was introduced in SDK version 4.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.

The SDK supports integration with both UIKit and SwiftUI. The following examples demonstrate how to launch the flow independently in each environment.

import UIKit

class ViewController: UIViewController {
    @IBAction func startDemographicFlow() {
        // Returns a UIViewController
        let controller = lucraClient.ui.flow(.demographicCollection)
        present(controller, animated: true)
    }
}

import SwiftUI

struct ContentView: View {
    @State private var isPresented = false

    var body: some View {
        Button("Start Demographic Flow") {
            isPresented = true
        }
        .fullScreenCover(isPresented: $isPresented) {
            // Returns a SwiftUI View
            lucraClient.ui.flow(.demographicCollection)
        }
    }
}

3. Manual Demographic Data Validation

Used internally by the SDK to verify whether all required demographic data has been provided.

public struct PrivateInfo: Codable {
    ...
    public let email: String?
    public let zip: String?
    ...
    
    internal var isMissingDemographicData: Bool {
        guard let email,
              let zip,
              !email.isEmpty,
              !zip.isEmpty
        else {
            return false
        }
        
        return true
    }
}

Migration Guide

For Existing Integrators

If you're updating from an older SDK version:

1. Breaking change - Existing tournament joining is no longer supported. The function has been updated to use Swift.Result instead of throwing errors.

2. New error handling - add handling for JoinTournamentError error

public enum JoinTournamentError: Error {
    ...
    case demographicCollectionPending
    ...
}

Example Migration

Before:

Task { @MainActor in 
    do {
        try await lucraClient.api.joinTournament(id: "my_tournament_id")
        print("Success!")
    } catch let error as UserStateError {
        switch error {
            ...
        }
    } catch ... {
        ...
    }
}

After:

Task { @MainActor in
    let result = await lucraClient.api.joinTournament(id: "my_tournament_id")
    
    switch result {
    case .success(let success):
        print("success: \(success)")
    case .failure(let failure): // failure is of type JoinTournamentError
        self.errorDetails = failure.localizedDescription
        switch failure {
        case .demographicCollectionPending:
            print("missing data!")
            ...
        }
    }
}

Common Issues

Issue: Demographic form not launching for free tournaments Solution: Ensure user authentication is complete before attempting to join tournaments.

Issue: Form not auto-filling previously entered data Solution: The form should auto-fill based on saved user data. If not working, check user authentication state.

Issue: .demographicCollectionPending error not being handled Solution: Iterate through the newly added JoinTournamentError cases to properly handle any relevant errors.