Skip to main content

Integrating Honeygain SDK with Linux application

info

Don't forget to generate your Honeygain SDK API Key and download the SDK from 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​

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.

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 sample/linux

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

Using gcc only​

In the terminal run:

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

Functions​

note

Note that hgsdk_start() and hgsdk_stop() function calls are non-blocking operations. Internally SDK service starting and stopping are asynchronous operations and there might be a slight delay before action actually happens.

hgsdk_start​

To start the SDK service call hgsdk_start() function:

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

Parameters​

api_key - Your API Key provided by Honeygain SDK.

state - Pointer to the variable where SDK service consent state will be stored. If user consent was given previously *state will be set to 1, otherwise *state will be set to 0.

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

It will check if explicit user consent was given before. Information about current state of user consent is stored in *state variable. If user consent was given previously, SDK service will start immediately. If user consent was not given previously, SDK service will not start and *state will be set to 0.

If SDK service is already running, the old instance will be stopped and new instance will be started with specified API key.

note

It is recommended to get user consent before starting SDK service.

hgsdk_stop​

To stop the SDK service call hgsdk_stop() function:

int32_t hgsdk_stop(void);

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

Stop the SDK service. If SDK service is not running, this function will do nothing. If SDK service is running, it will be stopped and all resources will be released.

note

It is recommended to stop SDK service before closing your application. This will ensure that all resources are released and SDK service is stopped properly.

hgsdk_is_running​

To verify if SDK service is running call hgsdk_is_running() function:

int32_t hgsdk_is_running(int32_t *state);

Parameters​

state - Pointer to the variable where SDK service state will be stored. If SDK service is running *state will be set to 1, otherwise *state will be set to 0.

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

hgsdk_opt_in​

To provide user consent call hgsdk_opt_in() function:

int32_t hgsdk_opt_in(void);

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

Store information that user consent was given and inform SDK service that it can start. Subsequent calls to hgsdk_start() will be allowed to start SDK service.

hgsdk_opt_out​

To revoke user consent call hgsdk_opt_out() function:

int32_t hgsdk_opt_out(void);

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

Store information that user consent was revoked and inform SDK service that it should stop if it is running. Subsequent calls to hgsdk_start() will not be allowed to start SDK service.

hgsdk_is_opted_in​

To verify if user consent was given call hgsdk_is_opted_in() function:

int32_t hgsdk_is_opted_in(int32_t *state);

Parameters​

state - Pointer to the variable where user consent state will be stored. If user consent was given *state will be set to 1, otherwise *state will be set to 0.

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

Stored information about user consent state is provided in *state variable.

hgsdk_log​

To enable logging for SDK service call hgsdk_log() function:

int32_t hgsdk_log(const char *dir);

Parameters​

dir - Path to the directory where log files will be stored.

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

Enable logging for SDK service. Log files will be stored in the specified directory. If directory does not exist, it will be created. If dir parameter is NULL or empty string, then log files will be created in the current working directory of your application. Log is also writen to standard output. Subsequent calls to hgsdk_log() will create a new log file in the specified directory.

hgsdk_mute​

To disable logging for SDK service call hgsdk_mute() function:

int32_t hgsdk_mute(void);

Return value​

Returns 0 if function call was successful, otherwise returns negative error code.

Remarks​

Disable logging for SDK service. Any log file is closed and writing to standard output is stopped. Log files are not deleted and can be used for debugging purposes. If you want to delete log files, you can do it manually.