Integrating the Honeygain SDK with Linux applications

info

Don't forget to generate your Honeygain SDK API Key and download the SDK from the Developers dashboard first.

On Linux operating systems Honeygain SDK service is provided for ARM64, ARMv7, X64 and X86 architectures using GNU or musl C libraries.

Extract the Archive

After downloading hgsdk.tar.gz, open a terminal in its directory and run:

tar -xzf hgsdk.tar.gz

This command recreates the top-level directory structure as it was archived, including one folder per architecture (e.g., arm64-musl/, x64-glibc/). It also preserves symbolic links by default, so SONAME symlinks remain intact.

Archive Contents

Inside each architecture directory, you will find:

• lib/: Contains shared object files (.so extensions) and their associated SONAME symlinks (e.g., libhgsdk.so → libhgsdk.so.1).
• include/: Contains public header file (.h extensions), used by applications to compile against the Honeygain SDK’s function definitions.
• lib/pkgconfig/: Contains the hgsdk.pc file, which pkg-config uses to expose compiler (--cflags) and linker (--libs) flags.
• lib/cmake/hgsdk/: Contains hgsdkConfig.cmake and version file, enabling CMake’s find_package(hgsdk CONFIG) to locate Honeygain SDK targets.

Install into Your Prefix

From inside the chosen architecture folder, install all components to the standard system prefix with:

sudo cp -a . /usr/local/

With this command you recursively copy files and directories, preserving symbolic links. /usr/local is defined by the Filesystem Hierarchy Standard as the location for administrator-installed software.

After copying shared libraries into /usr/local/lib, update the dynamic linker cache:

sudo ldconfig

ldconfig scans directories in /etc/ld.so.conf (including /usr/local/lib), rebuilds /etc/ld.so.cache, and sets up necessary links so applications can locate libhgsdk.so.* at runtime.

If you prefer to install under a non-standard prefix like a directory under your home (for example, $HOME/.local/hgsdk), then after copying the files you need to export following variables so your system and build tools still locate the SDK service:

cp -a . ~/.local/hgsdk/
export LD_LIBRARY_PATH="$HOME/.local/hgsdk/lib:$LD_LIBRARY_PATH"
export CPATH="$HOME/.local/hgsdk/include:$CPATH"

• LD_LIBRARY_PATH tells the dynamic linker where to look for shared libraries.
• CPATH adds include directories for GCC/Clang compilers.

Building with the SDK service

gcc

Using gcc only

You can build your application with Honeygain SDK service by explicitly specifying the correct compiler and linker flags:

gcc main.c -I/usr/local/include -L/usr/local/lib -lhgsdk -o app

-I adds header search directories, -L adds library paths, and -l links the shared library.

pkg-config

Using pkg-config

To build your application with Honeygain SDK service you can use pkg-config to read hgsdk.pc and provide the correct compiler and linker flags:

gcc main.c $(pkg-config --cflags --libs hgsdk) -o app

If Honeygain SDK service was installed under a non-standard prefix (for example, $HOME/.local/hgsdk) export following variable:

export PKG_CONFIG_PATH="$HOME/.local/hgsdk/lib/pkgconfig:$PKG_CONFIG_PATH"

CMake

Using CMake (Config mode)

To locate Honeygain SDK service add following line to your projects CMakeLists.txt file:

find_package(hgsdk REQUIRED CONFIG)

To build your application with Honeygain SDK service add following line to your projects CMakeLists.txt file:

target_link_libraries(app PRIVATE hgsdk::hgsdk)

If Honeygain SDK service was installed under a non-standard prefix (for example, $HOME/.local/hgsdk) export following variable:

export CMAKE_PREFIX_PATH="$HOME/.local/hgsdk:$CMAKE_PREFIX_PATH"

Running the Sample Application

The archive has also a sample included. After installing the Honeygain SDK service as described above, change into this directory:

cd samples/linux

Choose your preferred build method below and make sure you have build tools installed.

Manual

Using gcc only

In the terminal run:

gcc -pthread main.c -lhgsdk -o app
./app

Make

Using Makefile

In the terminal run:

make
./app

The Makefile internally uses pkg-config, so make sure you have it installed.

CMake

Using CMake (Config mode)

In the terminal run:

mkdir build
cmake -S . -B build
cmake --build build
./build/app

CMake must be installed on your system.

Function reference

note

hgsdk_start() and hgsdk_stop() are non-blocking. Internally, starting and stopping the Honeygain SDK service are asynchronous operations, so there can be a slight delay before the action takes effect.

---

hgsdk_start

Start the SDK service.

int32_t hgsdk_start(const char *api_key, int32_t *state);

Parameters

Name	Type	Description
api_key	const char*	Your API key provided by Honeygain SDK.
state	int32_t*	Out: consent state. Set to 1 if user consent was previously given, otherwise 0.

Returns

0 on success; otherwise a negative error code.

Remarks

• Checks whether explicit user consent was given before. The current consent state is returned via *state.
• If consent was previously given, the SDK service starts. If not, the service does not start and *state is set to 0.
• If the service is already running, the old instance is stopped and a new one is started with the provided API key.
• api_key is copied by the SDK; its memory does not need to remain valid after the call returns.

note

It is recommended to obtain user consent before starting the SDK service.

---

hgsdk_stop

Stop the SDK service.

int32_t hgsdk_stop(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Stops the SDK service if it is running and releases all resources.
• If the service is not running, this function does nothing.

note

It is recommended to stop the SDK service before closing your application to ensure all resources are released properly.

---

hgsdk_is_running

Check if the SDK service is running.

int32_t hgsdk_is_running(int32_t *state);

Parameters

Name	Type	Description
state	int32_t*	Out: set to 1 if the service is running, otherwise 0.

Returns

0 on success; otherwise a negative error code.

---

hgsdk_opt_in

Provide user consent.

int32_t hgsdk_opt_in(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Persists that user consent was given and informs the SDK service that it may start.
• Subsequent calls to hgsdk_start() will be allowed to start the service.

---

hgsdk_opt_out

Revoke user consent.

int32_t hgsdk_opt_out(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Persists that user consent was revoked and informs the SDK service that it should stop if running.
• Subsequent calls to hgsdk_start() will not be allowed to start the service.

---

hgsdk_is_opted_in

Check whether user consent was given.

int32_t hgsdk_is_opted_in(int32_t *state);

Parameters

Name	Type	Description
state	int32_t*	Out: set to 1 if consent was given, otherwise 0.

Returns

0 on success; otherwise a negative error code.

Remarks

• Returns the stored consent state via *state.

---

hgsdk_log

Enable logging for the SDK service.

int32_t hgsdk_log(const char *dir);

Parameters

Name	Type	Description
dir	const char*	Directory where log files will be stored. If NULL or empty, logs are created in the current working directory.

Returns

0 on success; otherwise a negative error code.

Remarks

• Enables logging and writes logs to the specified directory (created if it does not exist).
• Logs are also written to standard output.
• Subsequent calls to hgsdk_log() create a new log file in the specified directory.

---

hgsdk_mute

Disable logging for the SDK service.

int32_t hgsdk_mute(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Disables logging: closes any open log file and stops writing to standard output.
• Existing log files are not deleted and can be inspected for debugging.