Installation & Setup

Requirements

To begin using the SDK, you need:

  1. The Beam Eye Tracker application version 2.6.3 or later installed and set up on your system.

  2. The SDK package downloaded and unzipped on your system (Download) . If using Python, this is optional when installing from PyPI.

  3. A development environment for your chosen programming language or framework.

The C and C++ SDKs ship native client libraries for Windows, Linux, and macOS. Python bindings are available for the same platforms through PyPI and through the python/package folder in the SDK archive. These native client libraries are thin loaders: your application ships or loads the SDK client library, while the Beam Eye Tracker installation provides the platform runtime library containing the implementation. The loader locates the Beam-provided runtime and verifies supported runtime candidates before loading them. The beta JavaScript SDK is provided as a WebAssembly-backed ES module package in the javascript folder; its WebAssembly module contains the JavaScript runtime implementation. The C# wrapper can be used from desktop .NET applications when the matching native client library for the target platform is available to the application. The Unity package and beta Godot plugin included in the archive are Windows-only.

Project configuration

Depending on your specific project and language, you need to follow the steps below to integrate the SDK.

  1. Add the beam_eye_tracker_sdk-2.2.0/include directory to your project’s include paths.

    Note

    In case of using CMake, you can use the target_include_directories command.

  2. Add the platform-specific library directory to your project’s library directories:

    • Windows: beam_eye_tracker_sdk-2.2.0/lib/win64

    • Linux: beam_eye_tracker_sdk-2.2.0/lib/linux64

    • macOS: beam_eye_tracker_sdk-2.2.0/lib/macos

    Note

    In case of using CMake, you can use the target_link_directories command.

  3. Link against the platform library:

    • Windows: beam_eye_tracker_client.lib

    • Linux: libbeam_eye_tracker_client.so

    • macOS: libbeam_eye_tracker_client.dylib

    Note

    In case of using CMake, you can use the target_link_libraries command.

  4. Make the SDK client library available next to your application or through the platform’s normal loader path:

    • Windows: copy beam_eye_tracker_client.dll from beam_eye_tracker_sdk-2.2.0/bin/win64 to your output directory.

    • Linux: deploy libbeam_eye_tracker_client.so from beam_eye_tracker_sdk-2.2.0/lib/linux64 with your application or configure rpath/LD_LIBRARY_PATH.

    • macOS: deploy libbeam_eye_tracker_client.dylib from beam_eye_tracker_sdk-2.2.0/lib/macos with your application or configure rpath/DYLD_LIBRARY_PATH.

Note

On Windows, we also provide an alternative library build with /MT (beam_eye_tracker_client_MT.lib and beam_eye_tracker_client_MT.dll), which does not require the Visual C++ Redistributable on the host machine. In most cases, the default /MD build is preferred.

  1. Install the beam-eye-tracker package:

    pip install beam-eye-tracker==2.2.0

    Note

    Alternatively, you can download the SDK, unzip it and add the beam_eye_tracker_sdk-2.2.0/python/package directory to your PYTHONPATH.

  2. Test your installation:

    # This should not raise an import error:
from eyeware.beam_eye_tracker import API

The beta JavaScript package is in beam_eye_tracker_sdk-2.2.0/javascript. It includes the public ES module entry point, TypeScript declarations, the WebAssembly runtime files, and browser samples. The package can be used from browsers, Electron renderer processes, Electron main processes, and Node.js.

  1. Install from the SDK package directory or copy it into your web app:

    npm install ./beam_eye_tracker_sdk-2.2.0/javascript

  2. Import the package entry point:

    import { createSession } from "@eyeware/beam-eye-tracker";

const api = await createSession("My JavaScript Client");
console.log(api.getTrackingDataReceptionStatusName());
api.destroy();

  3. If you copy files manually, keep the javascript/lib directory next to javascript/index.js. The generated WebAssembly runtime loads its module and worker files from that relative layout.

Note

Browser hosts must serve the application and SDK files with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp so SharedArrayBuffer is available to the WebAssembly pthread runtime.

Note

For latency-critical desktop integrations, prefer the native C, C++, C#, or Python SDK clients for the target platform.

This assumes the project platform target is x64. The C# wrapper uses DllImport("beam_eye_tracker_client") and loads the native Beam SDK client through the platform’s normal native-library resolution rules.

Note

The SDK archive provides the C# wrapper source file and the native libraries, not a NuGet package or project file that copies native libraries automatically. Your application build or packaging process must deploy the matching native library for each target desktop platform.

  1. Copy beam_eye_tracker_sdk-2.2.0/csharp/src/Eyeware/BeamEyeTracker.cs into your project directory (e.g., root or a subfolder like Eyeware/).

  2. Include the BeamEyeTracker.cs file in your project.

    Note

    For Visual Studio: Right-click the project in Solution Explorer, select Add > Existing Item, and add BeamEyeTracker.cs.

  3. Make the matching native SDK client library available next to your application or through the platform’s normal loader path:

    • Windows: copy beam_eye_tracker_client.dll from beam_eye_tracker_sdk-2.2.0/bin/win64 to your output directory.

    • Linux: deploy libbeam_eye_tracker_client.so from beam_eye_tracker_sdk-2.2.0/lib/linux64 with your application or configure rpath/LD_LIBRARY_PATH.

    • macOS: deploy libbeam_eye_tracker_client.dylib from beam_eye_tracker_sdk-2.2.0/lib/macos with your application or configure rpath/DYLD_LIBRARY_PATH.

    Note

    For Visual Studio: Add it to the project (Add > Existing Item), then set Properties > Copy to Output Directory to Copy always.

  4. Add the using directive in your code:

    using Eyeware.BeamEyeTracker;

Note

A ready to use Windows Unity package is available. See Unity Package Installation for more information.

Note

A beta Windows Godot plugin is included in godot/addons/beam_eye_tracker. See Godot Plugin Installation for more information.

Now that you have the SDK integrated into your project, you can continue to the next section to get a general explanation of how the API is structured.