Integrating Appsalt SDK with Linux applications

info

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

On Linux, the Appsalt SDK service is provided for ARM64, ARMv7, X64, and X86 architectures using bionic, GNU, or musl C libraries.

Extract the Archive

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

tar -xzf appsalt.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., libappsalt.so → libappsalt.so.1).
• include/: Contains public header file (.h extensions), used by applications to compile against the Appsalt SDK’s function definitions.
• lib/pkgconfig/: Contains the appsalt.pc file, which pkg-config uses to expose compiler (--cflags) and linker (--libs) flags.
• lib/cmake/appsalt/: Contains appsaltConfig.cmake and version file, enabling CMake’s find_package(appsalt CONFIG) to locate Appsalt 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 libappsalt.so.* at runtime.

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

cp -a . ~/.local/appsalt/
export LD_LIBRARY_PATH="$HOME/.local/appsalt/lib:$LD_LIBRARY_PATH"
export CPATH="$HOME/.local/appsalt/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 Appsalt SDK service by explicitly specifying the correct compiler and linker flags:

gcc main.c -I/usr/local/include -L/usr/local/lib -lappsalt -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 Appsalt SDK service you can use pkg-config to read appsalt.pc and provide the correct compiler and linker flags:

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

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

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

CMake

Using CMake (Config mode)

To locate Appsalt SDK service, add the following line to your project's CMakeLists.txt file:

find_package(appsalt REQUIRED CONFIG)

To build your application with Appsalt SDK service, add the following line to your project's CMakeLists.txt file:

target_link_libraries(app PRIVATE appsalt::appsalt)

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

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

Running the Sample Application

The archive has also a sample included. After installing the Appsalt 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 -lappsalt -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

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

---

appsalt_init

Initialize the SDK service.

int32_t appsalt_init(const char *api_key);

Parameters

Name	Type	Description
api_key	const char*	Your API key provided by Appsalt SDK.

Returns

0 on success; otherwise a negative error code.

Remarks

• If the service is already initialized and a different API key is provided, the old instance is terminated and a new one is initialized.
• If the service is already initialized and the same API key is provided, the function call effectively does nothing.
• api_key is copied by the SDK; its memory does not need to remain valid after the call returns.

note

It is required to call this function before any other SDK service function.

---

appsalt_start

Start the SDK service.

int32_t appsalt_start(int32_t *state);

Parameters

Name	Type	Description
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 function call effectively does nothing.

note

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

---

appsalt_stop

Stop the SDK service.

int32_t appsalt_stop(void);

Returns

0 on success; otherwise a negative error code.

Remarks

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

note

It is recommended to stop the SDK service before closing your application so the service shuts down cleanly.

---

appsalt_identify

Get the SDK service identifier.

int32_t appsalt_identify(char *data, size_t *size);

Parameters

Name	Type	Description
data	char*	Buffer to receive a NUL-terminated ASCII string. If not NULL, the function writes up to *size bytes and sets *size to the number of bytes actually written.
size	size_t*	In/out. If data is NULL, on return *size is set to the number of bytes required to store the full NUL-terminated string. If data is not NULL, on return *size is set to the number of bytes actually written.

Returns

0 on success; otherwise a negative error code.

Remarks

• The identifier is stable across runs on the device.
• Use the two-call pattern to retrieve the full value: call with data == NULL to get required size (in bytes), allocate that many bytes, then call again with data and size.
• The returned string is NUL-terminated and plain ASCII.
• If the provided buffer (data/*size) is smaller than required, the string is truncated to fit (ensuring NUL termination when *size > 0), *size is set to the number of bytes actually written, and the function returns 0.

---

appsalt_is_running

Check if the SDK service is running.

int32_t appsalt_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.

---

appsalt_opt_in

Provide user consent.

int32_t appsalt_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 appsalt_start() will be allowed to start the service.

---

appsalt_opt_out

Revoke user consent.

int32_t appsalt_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 appsalt_start() will not be allowed to start the service.

---

appsalt_is_opted_in

Check whether user consent was given.

int32_t appsalt_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.

---

appsalt_log

Enable logging for the SDK service.

int32_t appsalt_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 appsalt_log() create a new log file in the specified directory.

---

appsalt_mute

Disable logging for the SDK service.

int32_t appsalt_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.