React Native SDK (Tournaments)

Headless Demographic Form usage examples for the ReactNative SDK

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.

This React Native wrapper exposes the tournament functionality from the underlying Android and iOS native SDKs.

Methods

getRecomendedTournaments

Retrieve a list of recommended tournaments.

Parameters:

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

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

Returns: Promise<PoolTournament[]>

Example usage:

import { LucraSDK } from 'lucra-react-native-sdk';

try {
  const tournaments = await LucraSDK.getRecomendedTournaments({
    limit: 50,
    includeClosed: true,
  });
  
  tournaments.forEach(tournament => {
    console.log(`Tournament: ${tournament.title}`);
  });
} catch (error) {
  // Handle error scenario
  console.error('Failed to fetch tournaments:', error);
}

tournamentMatchup

Retrieve a tournament with a given ID.

Parameters:

• tournamentId: ID associated with the tournament.

Returns: Promise<PoolTournament>

Example usage:

import { LucraSDK } from 'lucra-react-native-sdk';

try {
  const tournament = await LucraSDK.tournamentMatchup('tournamentId');
  console.log(`Tournament: ${tournament.title}, Fee: ${tournament.fee}`);
} catch (error) {
  // Handle error scenario
  console.error('Failed to retrieve tournament:', error);
}

joinTournament

Join a tournament with a given ID.

Parameters:

• tournamentId: ID associated with the tournament.

Returns: Promise<void>

Example usage:

import { LucraSDK } from 'lucra-react-native-sdk';

try {
  await LucraSDK.joinTournament('tournamentId');
  console.log('Successfully joined tournament');
} catch (error) {
  // Handle error scenario
  console.error('Failed to join tournament:', error);
}

Errors

Errors thrown during tournament operations (getRecomendedTournaments, tournamentMatchup, joinTournament) follow a consistent error structure to help determine the appropriate user-facing message and recovery action.

Error Types

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 banned

• insufficientFunds - Not enough balance for paid tournament entry

• missingDemographicInformation - Missing email/zip code for free tournaments

Location Errors:

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

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 response and error handling strategy.

Error Handling Example

import { LucraSDK, type LucraSDKError } from 'lucra-react-native-sdk';

try {
  await LucraSDK.joinTournament('tournamentId');
} catch (error) {
  const sdkError = error as LucraSDKError;
  
  switch (sdkError.code) {
    case 'notInitialized':
      // User session not set up
      console.error('User not initialized');
      break;
    case 'unverified':
      // Prompt user to complete KYC
      console.error('User needs to complete verification');
      break;
    case 'insufficientFunds':
      // Prompt user to add funds
      console.error('Insufficient balance');
      break;
    case 'missingDemographicInformation':
      // Collect required user information
      console.error('Missing demographic information');
      break;
    case 'LocationError':
      // Handle location-related issues
      console.error('Location verification failed');
      break;
    case 'APIError':
      // Network or server error
      console.error('API error occurred');
      break;
    default:
      console.error('Unknown error:', sdkError);
  }
}

Type Definitions

PoolTournament

type PoolTournament = {
  id: string;
  title: string;
  type: string;
  fee: number;
  buyInAmount: number;
  description?: string;
  participants: PoolTournamentParticipant[];
  status: string;
  metadata?: string;
  iconUrl?: string;
  expiresAt?: string;
  potTotal: number;
};

PoolTournamentParticipant

type PoolTournamentParticipant = {
  id: string;
  username: string;
  place?: number;
  rewardValue?: number;
};

Events

Tournament Joined Event

Subscribe to tournament join events to track when users successfully join tournaments:

import { LucraSDK } from 'lucra-react-native-sdk';

const unsubscribe = LucraSDK.addContestListener({
  onTournamentJoined: (tournamentId: string) => {
    console.log(`User joined tournament: ${tournamentId}`);
    // Update UI, track analytics, etc.
  },
  // ... other contest listeners
});

// Clean up when component unmounts
return () => unsubscribe();

The onTournamentJoined callback is triggered after a user successfully joins a tournament, providing the tournament ID for tracking and UI updates.

Usage Examples

1. Joining Tournaments with Automatic Error Handling

try {
  await LucraSDK.joinTournament('<tournament-id>');
} catch (e) {
  // If the user is missing demographic information, missingDemographicInformation error will be returned in the result
  console.warn('Missing demographic information', e);
  LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
}

2. Launching Demographic Form Independently

LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });

3. Manual Demographic Data Validation

Check if user has required demographic data before tournament operations:

// Subscribe to user updates
LucraSDK.addListener('user', (payload) => {
  if (payload.user) {
    const hasRequiredData = !isMissingDemographicData(payload.user);
    // Do something with `hasRequiredData`
  }
});

// Or check current user synchronously
const user = await LucraSDK.getUser();
const hasRequiredData = !isMissingDemographicData(user);

function isMissingDemographicData(user: LucraUser): boolean {
  return !user.email || !user.zip;
}

Migration Guide

For Existing Integrators

If you're updating from an older SDK version:

• Additive change - existing tournament joining code continues to work

• New error handling - add handling for missingDemographicInformation error

Example Migration

Before:

try {
  await LucraSDK.joinTournament(tournamentId);
  // handle success
} catch (e) {
  // Only handled KYC errors before
  if (e.code === 'unverified') {
    await LucraSDK.present({ name: LucraSDK.FLOW.VERIFY_IDENTITY });
  }
  // ...
}

After:

try {
  await LucraSDK.joinTournament(tournamentId);
  // handle success
} catch (e: LucraSDKError) {
  if (e.code === 'unverified') {
    await LucraSDK.present({ name: LucraSDK.FLOW.VERIFY_IDENTITY });
  } else if (e.code === 'missingDemographicInformation') {
    await LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
  }
  // ...
}

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

missingDemographicInformation error not being handled

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