Integrating Appsalt SDK with Windows C/C++ applications

This guide will go through the process of integrating and using Appsalt SDK in your C/C++ Windows application. It can also be integrated with any technology that supports the C ABI on Windows.

info

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

Integration

On Windows, the SDK service is provided for x64, x86, and arm64 architectures. Depending on your target architecture, use x64\bin\appsalt.dll, x86\bin\appsalt.dll, or arm64\bin\appsalt.dll as appropriate; it must be loadable by your application's executable. It is recommended to place it in the same directory as your application's executable file.

note

You cannot mix architectures (e.g., an x64 app cannot load an arm64 DLL and vice-versa).

With Visual Studio

If you are using Visual Studio, use the following steps to integrate the SDK service:

Right-click on your project in Solution Explorer and select Properties.
Go to Configuration Properties > C/C++ > General.
- Make sure Configuration is set to All Configurations.
- When targeting x64, set Platform to x64 and in Additional Include Directories add x64\include\appsalt.h.
- When targeting x86, set Platform to Win32 and in Additional Include Directories add x86\include\appsalt.h.
- When targeting arm64, set Platform to ARM64 and in Additional Include Directories add arm64\include\appsalt.h.
Go to Configuration Properties > Linker > General.
- Make sure Configuration is set to All Configurations.
- For x64, set Additional Library Directories to x64\lib.
- For x86, set Additional Library Directories to x86\lib.
- For arm64, set Additional Library Directories to arm64\lib.
Go to Configuration Properties > Linker > Input.
- Make sure Configuration is set to All Configurations and Platform is set to All Platforms.
- In Additional Dependencies add appsalt.dll.lib.
Go to Configuration Properties > Build Events > Post-Build Event.
- Make sure Configuration is set to All Configurations.
- When targeting x64, set Platform to x64 and in Command Line add:
```
copy /Y "<path to>\x64\bin\appsalt.dll" "$(OutDir)"
```
- When targeting x86, set Platform to Win32 and in Command Line add:
```
copy /Y "<path to>\x86\bin\appsalt.dll" "$(OutDir)"
```
- When targeting arm64, set Platform to ARM64 and in Command Line add:
```
copy /Y "<path to>\arm64\bin\appsalt.dll" "$(OutDir)"
```
- Replace <path to> with the directory where the SDK is located.

info

Full working example can be found in the samples/windows directory of the downloaded Appsalt SDK.

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_request_consent`

Display the default user agreement window and capture consent.

int32_t appsalt_request_consent(int32_t *state);

Parameters

Name	Type	Description
`state`	`int32_t*`	Out: set to `1` if the user accepts, otherwise `0`.

Returns

0 on success; otherwise a negative error code.

Remarks

Shows the default user agreement UI.
If the user accepts, consent is stored and the SDK service may start. Subsequent appsalt_start() calls are allowed.
If the user declines or closes the window, subsequent appsalt_start() calls are not allowed unless consent was previously given.

note

This function is blocking and returns only after the user accepts or declines the agreement.

`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.

Integration​

With Visual Studio​

Function reference​

appsalt_init​

Parameters​

Returns​

Remarks​

appsalt_start​

Parameters​

Returns​

Remarks​

appsalt_stop​

Returns​

Remarks​

appsalt_identify​

Parameters​

Returns​

Remarks​

appsalt_is_running​

Parameters​

Returns​

appsalt_opt_in​

Returns​

Remarks​

appsalt_opt_out​

Returns​

Remarks​

appsalt_is_opted_in​

Parameters​

Returns​

Remarks​

appsalt_request_consent​

Parameters​

Returns​

Remarks​

appsalt_log​

Parameters​

Returns​

Remarks​

appsalt_mute​

Returns​

Remarks​

Integration

With Visual Studio

Function reference

`appsalt_init`

Parameters

Returns

Remarks

`appsalt_start`

Parameters

Returns

Remarks

`appsalt_stop`

Returns

Remarks

`appsalt_identify`

Parameters

Returns

Remarks

`appsalt_is_running`

Parameters

Returns

`appsalt_opt_in`

Returns

Remarks

`appsalt_opt_out`

Returns

Remarks

`appsalt_is_opted_in`

Parameters

Returns

Remarks

`appsalt_request_consent`

Parameters

Returns

Remarks

`appsalt_log`

Parameters

Returns

Remarks

`appsalt_mute`

Returns

Remarks