C and C++
Note: This SDK is in beta. Before version 1.0, a minor version can change the API.
The PostHog C/C++ SDK (posthog-rs-ffi) is a C API for the PostHog Rust SDK. You can use it from C and C++ applications, such as servers, desktop apps, CLIs, and games. It uses the same code as the Rust SDK for batching, retries, Feature Flags, and local evaluation.
- Capture adds events to a queue and returns immediately. A background thread batches, retries, and sends them.
- Feature flag evaluation blocks the calling thread while it gets flags, or evaluates them locally when you enable local evaluation.
Installation
Download the archive for your platform from the posthog-rs-ffi GitHub Releases. Each release has the tag posthog-rs-ffi-v<version> and these archives:
| Platform | Targets |
|---|---|
| Linux (glibc 2.35 or newer) | x86_64, arm64 |
| macOS | Intel, Apple silicon |
| Windows (MSVC) | x86_64 |
Each archive has the name posthog-rs-ffi-<version>-<target> and a .sha256 checksum file. It contains:
CMake
Unpack the archive, set CMAKE_PREFIX_PATH to its directory, and link the imported target:
posthog-rs-ffi::posthog-rs-ffi links the shared library. To link the static library and the system libraries that it needs, set POSTHOG_RS_FFI_STATIC=ON before find_package. You can also link posthog-rs-ffi::shared or posthog-rs-ffi::static directly.
find_package(posthog-rs-ffi 0.1) accepts 0.1.x and rejects 0.2, because a minor version can change the API before 1.0.
pkg-config
On Linux and macOS, add the lib/pkgconfig directory of the archive to PKG_CONFIG_PATH:
Manual linking
To link the shared library on Linux or macOS:
On Windows, link the import library of the DLL, posthog_ffi.dll.lib. Do not link posthog_ffi.lib, because that is the static library:
To link the static library, add the flags from lib/native-static-libs.txt. For example, on Linux:
On Windows, compile with /MD, because the static library uses the DLL C runtime. Put the library and the flags from native-static-libs.txt after /link, because the flags include linker options such as /defaultlib:
Ship the shared library
Your app must find the shared library at run time. Ship the library with your app and tell the loader where it is:
- Linux: link with an rpath, such as
-Wl,-rpath,'$ORIGIN', or install the library in a system library directory. - macOS: the install name of the library is
@rpath/libposthog_ffi.dylib. Link with an rpath, such as-Wl,-rpath,@executable_path. - Windows: put
posthog_ffi.dllin the same directory as your executable, or in a directory onPATH.
If you link the static library, you do not need to ship a shared library, but your binary is larger.
Initialization
Create options with your project token, then create a client:
posthog_client_new copies the options, so you can free them after you create the client. Create one client and use it for the full life of your app.
Before your app exits, free the client. This sends the events in the queue, then frees the client:
Configuration options
Set these options on PostHogOptions before you call posthog_client_new:
| Function | Default | Description |
|---|---|---|
posthog_options_set_host | https://us.i.posthog.com | PostHog host, such as https://eu.i.posthog.com or your reverse proxy. |
posthog_options_set_is_server | true | Set to false for desktop and CLI apps. |
posthog_options_set_disabled | false | Stops all capture and feature flag requests. A blank API key also disables the client. |
posthog_options_set_disable_geoip | false | Disables GeoIP enrichment of events and feature flag requests. |
posthog_options_set_flush_at | 100 | Number of events in the queue that starts a flush. |
posthog_options_set_flush_interval_ms | 5000 | Time between automatic flushes, in milliseconds. |
posthog_options_set_max_batch_size | 100 | Maximum number of events in one request. |
posthog_options_set_max_queue_size | 10000 | Maximum number of events in the queue. When the queue is full, the SDK drops new events. |
posthog_options_set_max_capture_attempts | 4 | Attempts for each capture batch, including the first attempt. |
posthog_options_set_request_timeout_seconds | 30 | Timeout for capture and flag definition requests. |
posthog_options_set_feature_flags_request_timeout_seconds | 3 | Timeout for remote /flags requests. |
posthog_options_set_feature_flags_request_max_retries | 1 | Retries after a temporary /flags failure. |
posthog_options_set_shutdown_timeout_ms | 30000 | Maximum time that shutdown uses to send the events in the queue, in milliseconds. |
posthog_options_set_secret_key | None | Project secret API key (phs_...) for local evaluation. |
posthog_options_set_enable_local_evaluation | false | Evaluates Feature Flags locally. Requires a secret API key. |
posthog_options_set_local_evaluation_only | false | Never uses remote /flags when local evaluation cannot give a result. |
posthog_options_set_poll_interval_seconds | 30 | Time between requests for local evaluation flag definitions. |
Capturing events
Create an event, set its properties, and capture it. posthog_capture adds a copy of the event to the queue, so you must free the event after you capture it:
You can also set these values on an event:
posthog_event_set_timestamp_ms(event, unix_ms)sets the time of the event, in milliseconds since the Unix epoch.posthog_event_set_uuid(event, uuid)sets the event UUID. PostHog uses it to remove duplicate events.posthog_event_set_option_json(event, key, json)sets a capture option, such asprocess_person_profile.
Anonymous events
To capture an event that does not create a person profile, use posthog_event_new_anon:
For more information, see anonymous vs identified events.
Flush and shutdown
The SDK sends events in the background. To send the events in the queue immediately, call posthog_flush. It blocks until the SDK sends the events or the requests fail:
posthog_shutdown sends the events in the queue within the shutdown timeout and stops the client. The client drops events that you capture after shutdown. posthog_client_free also does a shutdown.
Identifying users
To set person properties, add $set or $set_once to an event:
Alias
To link a previous ID, such as an anonymous ID, to a distinct ID, use posthog_alias:
Group analytics
To associate an event with a group, use posthog_event_add_group:
To set properties on a group, use posthog_group_identify. The properties must be a JSON object or NULL:
Feature Flags
posthog_evaluate_flags evaluates the Feature Flags for a user and gives a snapshot. The snapshot does not send more requests when you read flags from it. Free the snapshot with posthog_flags_free:
| Function | Description |
|---|---|
posthog_flags_is_enabled | Writes if the flag is enabled. Captures a $feature_flag_called event. |
posthog_flags_get_flag | Writes the flag state: NOT_FOUND, DISABLED, ENABLED, or VARIANT. For VARIANT, it also writes the variant. Captures a $feature_flag_called event. |
posthog_flags_get_payload | Writes the JSON payload of the flag, or NULL if the flag has no payload. Does not capture an event. |
posthog_flags_keys | Writes the flag keys in the snapshot as a JSON array. |
posthog_flags_only_accessed | Gives a new snapshot with only the flags that you read. |
Evaluation options
The third argument of posthog_evaluate_flags is NULL or a JSON object. Each field is optional. The SDK rejects null values and unknown fields:
Add flags to events
To add $feature/<key> and $active_feature_flags properties to an event, use posthog_event_set_flags. This uses the snapshot and does not send a /flags request. To add only the flags that you read, use posthog_flags_only_accessed:
Experiments
Use posthog_flags_get_flag to get the variant for a user in an Experiment. This captures the $feature_flag_called event that Experiments use for exposures.
Local evaluation
Local evaluation is for servers that you control. Set a project secret API key and enable local evaluation:
The SDK gets flag definitions at the poll interval. To get them immediately, call posthog_reload_feature_flags(client).
Warning: Do not put a secret API key in an app that you distribute, such as a desktop app or CLI. Anyone with the binary or its configuration can extract the key and read your flag definitions. Distributed apps must use only the project token, which evaluates flags remotely.
Errors
Functions return a PostHogStatus. Constructors, such as posthog_client_new, return NULL when they fail. posthog_last_error() gives a description of the last error on the calling thread:
| Status | Description |
|---|---|
POSTHOG_STATUS_OK | The call was successful. |
POSTHOG_STATUS_NULL_ARGUMENT | A required argument is NULL. |
POSTHOG_STATUS_INVALID_UTF8 | A string is not valid UTF-8. |
POSTHOG_STATUS_INVALID_JSON | A JSON argument is not valid. |
POSTHOG_STATUS_INVALID_ARGUMENT | An argument is not valid. |
POSTHOG_STATUS_REQUEST | A request to PostHog failed. |
POSTHOG_STATUS_PANIC | The SDK had an internal error. The call possibly did only part of its work. |
The SDK never unwinds into your code.
Memory and threads
- Handles: free each handle from a
*_newfunction with the related*_freefunction. The*_freefunctions ignoreNULL. - Strings: free each
char *that the SDK writes to an_outargument withposthog_string_free. Do not change the string before you free it. - Inputs: the SDK borrows input strings only during the call. They must be NUL-terminated UTF-8.
- Threads: you can share a
PostHogClientorPostHogFlagsbetween threads. Use eachPostHogOptionsandPostHogEventfrom only one thread at a time.
C++
The SDK has a C API. You can call it from C++ directly. The capture.cpp example shows a C++17 wrapper that puts the handles in std::unique_ptr and changes error statuses into exceptions. You can copy this pattern into your app:
For a full C program, see capture.c.





