SDK Provider Profile¶

The Scorbit SDK requires specific device information for proper initialization and authentication. This information establishes the identity and configuration of your game installation. Every unique manufacturer or developer of games is assigned a platform-wide identity string known as a provider. This identity tells Scorbit what it needs to know to properly provision and authenticate. When combined with a UUID and machineId, we know everything required to pair the machine to the platform.

Provider

The provider is a unique identifier for your organization, and is assigned by Scorbit. For example, your provider may be "scorbitron", "vpin", or "sternpinball".

Why Is a UUID Required?¶

UUID of the machine represents a physical machine in the Scorbit ecosystem. It is a unique identifier that allows Scorbit to track and authenticate the machine.

There are two ways to set UUID:

Machine uses TPM and has UUID stored in it. In this case the UUID is read from TPM and passed to the SDK.
Machine does not have TPM, so the UUID is generated by the SDK based on the MAC address of the machine. In this case use the defauilt value (empty string) for UUID in the device info. For languages such as C++, Python, just omit setting the UUID field and it will be by default empty so the SDK will generate it.

A machine with a UUID can change its owner, its network address, and its game code, but the UUID remains the same. This is important when you're securing connections to authorized devices and guaranteeing that a leaderboard score posted by a machine is associated with the correct player and machine.

How Scorbit Uses UUIDs¶

When a SDK authenticates with a brand new UUID for the first time, Scorbit creates a unique record in the Scorbit database for that UUID. You can think of this as a representation of the unique identity of the network client, and is often permanently associated with each unique game manufactured off the line, known on the Scorbit platform as a VenueMachineId, a record that represents a single instance of a game title, or MachineId.

In some cases, this is coming from a physical machine using a TPM or an embedded key, staying with the machine wherever it may go. In other cases, this UUID floats between different VenueMachineIds, such as the case with VPINs.

Storing a UUID on removable storage, such as an SD card or hard drive, is not advisable because the UUID could be lost if the storage device is replaced or disconnected. Instead, it is preferable to store the UUID in non-volatile memory like EEPROM or TPM. If the device does not have non-volatile memory, a viable alternative is to generate the UUID based on a unique hardware identifier, such as the MAC address. In cases where no UUID is provided, the SDK will automatically generate one using the MAC address combined with the provider's name. This approach ensures the UUID remains consistent regardless of changes to the storage device.

In order for pairing between this record and a player-created virtual version of the game, this identifier has to be passed to the player's Scorbit account. Usually this is done in the app through the scanning of a deeplink QR code, other times through entry of a six-digit alphanumeric code provided by the SDK. VPINs and Spike 2 machines are the exception, their process is more automated using a Scorbit Desktop Utility. Regardless, pairing then establishes the relationship to the singular instance of the that game title in Scorbit, owned by a Scorbit user.

Since the game code on the machine may change and with it features available to the player, we also ask for the Game Code Version to be provided along with the game title's MachineId.

Finally, if the manufacfurer has a serial numbering system, this is optional data that can be provided to associate with the UUID record. This is really useful for supporting the user remotely or identifying issues specific to a machine.

Device Information¶

Optional fields can be left empty or set to zero if not applicable. Only in C it has to be set explicitly.

The SDK requires a DeviceInfo structure with the following fields:

CC++Python

// UUID can be NULL if you want it to be generated automatically from MAC address
// serial_number can be 0 if you don't have a serial number

sb_device_info_t device_info = {
    .provider = "scorbitron",           // Mandatory: provider name
    .machine_id = 4419,                 // Mandatory: Scorbit-assigned Machine ID
    .game_code_version = "1.12.3",      // Mandatory: your game version
    .hostname = "production",           // Optional: server hostname
    .uuid = NULL,                       // Optional: device UUID
    .serial_number = 0                  // Optional: device serial number
};

scorbit::DeviceInfo device_info;
device_info.provider = "scorbitron";          // Mandatory: provider name
device_info.machineId = 4419;                 // Mandatory: Scorbit-assigned Machine ID
device_info.gameCodeVersion = "1.12.3";       // Mandatory: your game version
device_info.hostname = "production";          // Optional: server hostname
device_info.uuid = "";                        // Optional: device UUID
device_info.serialNumber = 0;                 // Optional: device serial number

from scorbit import scorbit

info = scorbit.DeviceInfo()
info.provider = "scorbitron"           # Mandatory: provider name
info.machine_id = 4419                 # Mandatory: Scorbit-assigned Machine ID
info.game_code_version = "1.12.3"      # Mandatory: your game version
info.hostname = "production"           # Optional: server hostname
info.uuid = ""                         # Optional: device UUID
info.serial_number = 0                 # Optional: device serial number

Required Fields¶

Field	Type	Description	Example
provider	string	Identifies your platform	`"scorbitron"`, `"vpin"`
machineId	integer	Scorbit-assigned unique identifier	`4419`
gameCodeVersion	string	Your game's version string	`"1.12.3"`

Optional Fields¶

For optional fields, the SDK will use default values if none are provided. To use the default values, you can set these fields to an empty string, NULL, or zero where appropriate.

Field	Type	Description	Default	Notes
hostname	string	Server connection endpoint	`"production"`	Options: `"production"`, `"staging"`, or custom URL
uuid	string	Device's unique identifier	Generated from MAC	Format: `"f0b188f8-9f2d-4f8d-abe4-c3107516e7ce"`
serialNumber	integer	Device's serial number	`0`	Used for device tracking

UUID Generation

If UUID is not provided, the SDK will automatically generate one based on the device's MAC address.

Required Fields

Provider name, machine ID, and game code version are mandatory. The SDK will not initialize properly without these fields.

Hostname Selection

Use "production" for release builds and "staging" for development and testing.

UUID Management¶

Retrieving the UUID¶

After initializing the SDK with device info, you can retrieve the machine's UUID:

CC++Python

const char* uuid = sb_get_machine_uuid(state);

std::string uuid = gs.getMachineUuid();

uuid = gs.get_machine_uuid()

The returned UUID will be either: - The value provided in device_info.uuid during initialization - An automatically generated value based on the device's MAC address if no UUID was provided

Source	Format	Example
Provided	UUID string	`"f0b188f8-9f2d-4f8d-abe4-c3107516e7ce"`
Generated	MAC-based UUID	`"c7f1fd0b-82f7-5504-8fbe-740c09bc7dab"`

UUID Persistence

Once generated, a UUID remains constant for a device unless explicitly changed in the device info. For paired devices, changing the UUID will require re-pairing.

Support

The UUID is essential for support and troubleshooting. Keep it accessible for when you need to identify your machine to Scorbit support.

Best Practices¶

1. Version Management¶

Use semantic versioning for game_code_version
Update version number with each release
Track version changes in logs

2. UUID Handling¶

Store generated UUIDs for consistency
Use consistent format across installations
Consider hardware-tied UUID generation, such as the MAC address

3. Environment Selection¶

Use staging for development
Test with production before release
Log environment in debugging