Skip to content

Add identify and person property helpers #152

Description

@marandaneto

Summary

Add first-class user identification and person property helper APIs to the Rust SDK, matching the ergonomics of other backend SDKs.

Motivation

The Rust SDK can already capture identified events by passing a distinct_id to Event::new, and users can manually set person properties by adding $set, $set_once, or $unset properties to an event.

However, compared with other backend SDKs, this is less discoverable and makes the SDK look like it does not support user identification well. For example:

  • PHP exposes PostHog::identify(...) for setting person properties.
  • Node exposes setPersonProperties(...), unsetPersonProperties(...), and helper capture APIs.
  • Python documents identify_context(...) and uses $set / $set_once in capture(...).
  • Ruby exposes identify(...).

Rust users currently need to know the raw PostHog event/property protocol and construct those payloads manually.

Proposed API

Exact naming can be adjusted to fit Rust conventions, but something like:

client.identify(
    "user_distinct_id",
    IdentifyOptions::new()
        .set("email", "max@example.com")?
        .set("name", "Max Hedgehog")?
        .set_once("initial_url", "/blog")?,
).await?;

And/or explicit person property helpers:

client.set_person_properties(
    "user_distinct_id",
    PersonProperties::new()
        .set("name", "Max Hedgehog")?
        .set_once("initial_url", "/blog")?,
).await?;

client.unset_person_properties("user_distinct_id", ["email"]).await?;

Blocking client equivalents should be available too:

client.identify("user_distinct_id", options)?;
client.set_person_properties("user_distinct_id", properties)?;
client.unset_person_properties("user_distinct_id", ["email"])?;

Under the hood, these can send the same $set event / $set, $set_once, and $unset payloads that users can send manually today.

Acceptance criteria

  • Async and blocking clients expose helpers for identifying a user and setting person properties.
  • Helpers support $set and $set_once values.
  • A helper exists for unsetting person properties ($unset) or there is a documented reason to leave it out.
  • Helpers accept serializable values and surface serialization errors clearly.
  • Tests cover the generated event payloads.
  • Rust docs can show the helper APIs instead of requiring manual $set, $set_once, and $unset event construction.

Related issues

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions