Skip to main content

License Management Guide

Scope​

This document describes how to generate fingerprints, install and replace licenses, and diagnose common licensing issues for the Vantor Raptor Guide SDK and the Raptor Guide Server.

Concepts​

  • License file
    A file distributed by Vantor that grants the right to use the SDK or server on a specific machine or set of machines. Depending on the license, different features may be enabled.
  • Fingerprint
    A device identifier generated on the target machine and sent to Vantor when requesting a license. It is represented as an opaque string; its internal structure is private and may change between versions. Treat it only as a token.

Generating a fingerprint​

C++ Raptor Guide SDK​

To generate a fingerprint directly from the SDK, call:

  • raptor::Guide::generateFingerprint()

Notes:

  • Returns std::optional<std::string>.
  • On success, the string identifies the current machine for licensing purposes.
    • The value is opaque; do not parse, modify, or validate it yourself.
    • If the SDK cannot determine a valid machine identifier on this platform, the function returns std::nullopt.

Recommended workflow

  1. Build a small provisioning tool that calls raptor::Guide::generateFingerprint().
  2. Run it on the target system and capture the returned string.
  3. Provide that string to Vantor when requesting a license.
  4. Store the license file you receive at a stable location on the target system.

Raptor Guide Server​

When using the Guide Server, the server can expose the fingerprint through its status API:

  • The GetStatusResponse message includes a fingerprint_b64 field that, when present, contains the server's fingerprint.
  • Use this value in the same way as the C++ SDK fingerprint when requesting a license for the server.

Installing a license​

C++ Raptor Guide applications​

  1. Choose a location for the license file
  • Use a stable, readable path.
  1. Configure the license path
  • In C++:
    • Set config.licensePath in raptor::guide::Config before constructing raptor::Guide.
  • From JSON:
    • Set the licensePath field in the configuration JSON that you parse with parseConfigFromJson().
  1. Handling license issues
  • If the license file is missing, invalid, expired, or not intended for Raptor Guide, license-related errors will be reported.
  • See the Troubleshooting section below for common messages and recommended actions.

Raptor Guide Server​

For the Guide Server, the license path is typically configured in the server's JSON configuration:

  • Use the license field in the deployment configuration to point to the license file.
  • The server uses this file to determine its license status, which is exposed via the status API.

Replacing or updating a license​

When you receive a new license file (for example, after renewal or adding features):

  1. Generate a fingerprint for the target machine if required and request a new license.
  2. Copy the new license file to the configured path, replacing the old file or updating the path in your configuration.
  3. Restart the application or server:
    • For C++ applications, destroy any existing raptor::Guide instances and create a new one, or restart the process.
    • For the Guide Server, restart the server process.

Troubleshooting​

Initialization errors​

If you encounter an exception related to licensing, the message typically indicates the cause. Common messages and actions:

  • "License file not found or invalid path"
    • Check that the path in licensePath exists and is readable by the application.
  • "Invalid license"
    • The file is present but not a valid Raptor Guide license. Verify that the correct file was installed.
  • "Expired license"
    • The license has passed its expiration date. Request an updated license.
  • "License ApplicationId does not match Raptor Guide"
    • The license targets a different product. Install a license specifically issued for Raptor Guide.
  • Fingerprint-related messages (for example, fingerprint mismatch or invalid fingerprint data)
    • Ensure that the license was issued for the fingerprint of the current machine.
    • Regenerate the fingerprint on this machine and request a new license if necessary.

Runtime "InvalidLicense" results​

If updatePose() or updatePosition() returns Result::InvalidLicense:

  • There is a problem with the license (for example, expired or missing required features).
  • Check the license expiry and the licensed feature set, and install an updated license if needed.

For detailed integration steps and configuration examples, see: