Headless Functionality

Headless functions are API calls that do not display UI. Most require the SDK to be initialized and the user to be logged in.

• Games You Play headless APIs: see GYP headless functions

• Tournament headless APIs: see Tournament headless functions

Error handling

Headless calls surface native errors from the platform bridges:

• Common codes (iOS LucraSwiftClient.rejectLucraError / Android ErrorMapper): apiError, locationError, insufficientFunds, notAllowed, notInitialized, unverified, missingDemographicInformation, unknown / unknownError.

• Validation codes thrown before the API call (see LucraSwiftClient.createRecreationalGame and LucraClientModule.createRecreationalGame): invalidAtStake, invalidRewardType, invalidPlayStyle.

• Configure user specific (Android LucraClientModule.configureUser): invalid_username, not_logged_in, unknown_error.

Handle them explicitly:

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

function handleLucraSDKError(e: LucraSDKError) {
  switch (e.code) {
    case 'notInitialized':
      LucraSDK.present({ name: LucraSDK.FLOW.ONBOARDING });
      break;
    case 'unverified':
      LucraSDK.present({ name: LucraSDK.FLOW.VERIFY_IDENTITY });
      break;
    case 'insufficientFunds':
      LucraSDK.present({ name: LucraSDK.FLOW.ADD_FUNDS });
      break;
    case 'missingDemographicInformation':
      LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
      break;
    case 'apiError':
    case 'locationError':
      // Retry, show location permission prompt
      break;
    default:
      console.warn('Lucra error', e);
  }
}

User Configuration

Configure User Properties

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.

Provide user information so Lucra can create or update the user profile:

await LucraSDK.configureUser({
  username: 'player123',          // optional
  avatarURL: 'https://...',       // optional
  phoneNumber: '[phone]',    // optional
  email: '[email protected]',      // optional
  firstName: 'Mike',              // optional
  lastName: 'Smith',              // optional
  address: {
    address: '123 Main St',       // optional
    addressCont: 'Apt 4B',        // optional
    city: 'New York',             // optional
    state: 'NY',                  // optional
    zip: '10001',                 // optional
  },
  metadata: { "external_id": "..."}, // optional string map to help bind Lucra users to your users
});

const user = await LucraSDK.getUser();

Required/Optional Fields

Field requirements depend on your program configuration. At minimum, pass the fields you have available. The SDK will prompt for missing information when necessary.

Logout

await LucraSDK.logout();

Ends the Lucra session for the current user.

User Listener

Subscribe to user updates:

const unsubscribe = LucraSDK.addListener('user', ({ user, error }) => {
  if (error) {
    console.log('user callback error', error);
    return;
  }

  if (user == null) {
    console.log('User is null (logged out)');
  } else {
    console.log('Received user', user);
  }
});

// Call this when you no longer need the listener (e.g., on unmount).
unsubscribe();

Full Screen Flow Dismissed Listener

const unsubscribe = LucraSDK.addLucraFlowDismissedListener((flow) => {
  console.log('flow dismissed', flow);
});

// Call this when you no longer need the listener (e.g., on unmount).
unsubscribe();