User Linking & Score Ingestion
A streamlined approach for connecting your users to Lucra tournaments and delivering scores.
Overview
Lucra's user linking system removes the overhead of linking Lucra users with your users as well as managing the requirements of when a user can receive a score. Your system identifies users with metadata and sends scores. Lucra takes care of finding the right user, matching them to active matchups, and applying scores automatically.
The flow becomes a simple two-step process:
Link your user to Lucra using your own metadata.
Send scores whenever they play.
Lucra handles everything else in the background.
While User Linking is globally registered within Lucra, Score Ingestion by User Metadata only supports Tournaments at the moment, if you're looking for Games You Play remote outcome submission, visit our GYP implementation guide
How It Works
1. User Linking
When a user signs into the Lucra SDK, your application can provide a metadata object representing your internal user. Lucra stores this metadata on the Lucra user's account.
Once linked, you do not need to keep track of the ID that Lucra generates upon account creation.
Example payload
An ID-like identifier keyed as externalId will allow us to quickly identify the user, otherwise, any other key value Strings can be supplied.
{
"externalId" :"...",
"bookingId": "...",
"storeId": "..."
//...
}While metadata is not enforced to be unique, we do recommend maintaining uniqueness on the key(s) and value(s) provided for the Lucra user.
We recommend keeping identifiers simple and consistent across your entire ecosystem of platforms.
User Metadata Technical Setup
2. Score Submission
When your user earns a score in your platform, you send Lucra a score payload that contains:
Lucra Matchup ID or Matchup metadata
Lucra User ID or your User Metadata
GameID
LocationId
The score
We will require at minimum, one matchup related identifier.
Any score provided will continue to overwrite the prior score registered for a user unless attemptFinished=true is passed within the userScore shape, unless the tournament is closed via API, closed via the Console, or the user has paid for another attempt.
Read more about attemptFinished logic and it's implications, here
Lucra will:
Find the Lucra user associated with the provided User metadata.
Match any open tournaments given the matchup metadata that this user is a part of and can accept this user's score.
Apply the score to all tournaments that qualify
Return a list of tournaments that accepted or rejected the submission
Score Submission by Metadata Technical Setup:
Backend Metadata Driven Score SubmissionScenarios
Let's walk through a few examples of how this pans out end-to-end
Set the stage
When a user named Jerry, a frequent visitor of the FooBar platform, logs into FooBar after the successful integration of Lucra, they decide to join tournaments both for free and for real money. Jerry logs into Lucra using their phone number, and FooBar submits metadata identifying Jerry, providing an externalId that corresponds to Jerry's ID in the FooBar system.
If externalId is provided for score submission, all other keys will be ignored for identification
User Scores Points in a Game
Once FooBar knows Jerry scored, say 100 points, in a game identified as FOO_BAR_QUIZ FooBar doesn't need to know if Jerry is in any open tournaments, a score can simply be sent over to Lucra
FOO_BAR_QUIZ Is a GameID that Lucra creates and links to FooBar. GameIDs must be registered with Lucra before integration. React out to your Implementation Manager for more details.
Match any open tournaments with a game ID of FOO_BAR_QUIZ that this user has joined and can accept this user's score.
User Scores Points in a Controlled Tournament
FooBar sets up a tournament to be in a controlled environment, where scores registered on their machines will strictly apply to one tournament. Jerry joins this tournament and scores 100. In this case, FooBar wants to make sure this score is only registered for a specific tournament. FooBar will only need to pass matchup identifying metadata and again, the user metadata and score.
matchupMetadata refers to a custom set of metadata specified by the client for a newly created tournament.
It's currently supported through our Tournament creation API, learn more here
The score of 100 will only apply to Jerry in the open tournament(s) identified from the metadata
User Scores Points at a specific location
FooBar sets up a tournament to be ran only at a specific location, say their Atlanta location, where scores registered on their machines will strictly apply to tournaments at this location. Jerry joins this tournament and scores 100. In this case, FooBar wants to make sure this score is only registered for tournaments at this location. FooBar will only need to pass matchup identifying locationId, the GameID and again, the user metadata and score.
locationId Is a LocationID that Lucra creates and links to FooBar. LocationIDs can be registered with Lucra to have more control over tournament visibility. Learn more here (TODO)
The score of 100 will only apply to Jerry's attempts for tournaments at that location with that gameId
Customization
The ideal flow isn't always flexible enough for the level of control you're looking for. That's OK! Our systems expose and support an array of other options to be total in control of what the user is doing within Lucra, allowing you to build a more thorough system.
These alternate approaches require manual linking Lucra user and Lucra matchup IDs
Last updated