Skip to content

Actors

An Actor represents an entity in your application that receives feature flag values. In most cases, an Actor is a person — but it can also be an organisation, an AI agent, an API client, or any other entity that your app uses.

What Is an Actor?

If you're not storing your actor Feature Flags on your platform (locally), you can use our Actor feature to store them remotely on our servers. Imagine this a remote database that saves your provided list of features together with your user's identifier.

Actor Properties

Each Actor has:

Reference

A unique identifier for this actor in your system. This is how FlagPal tells actors apart.

Examples:

  • A user ID: user_12345
  • An email address: [email protected]

    IMPORTANT: it is your reponsibility to enforce privacy of your users. For security and privacy purposes, we request using a hashed version of any user-identifying information. FlagPal does not handle this for you!

  • A session token: sess_abc123

The reference is set by your development team when they integrate FlagPal. Typically, it's your internal user ID.

Features

FlagPal stores the current set of Feature Flag values for each Actor. You can update these values at any time using the API.

Your application can then retrieve this Actor's feature values at any time using the API.

Project

Every Actor belongs to a specific project. Different projects have different actors. Actors are automatically assigned to a Project which is interacting with the API.

When to use Actors

In case you are not able to store your user/actor Feature Flags on your platform, you can use our Actor feature to store them remotely on our servers. Think of it as offloading this responsibility to a remote database that saves your provided list of features together with your user's identifier. Usually, it is not necessary to use actors in your application.

A Concrete Example

Here's how actors flow through FlagPal:

  1. User Alice logs in to your app
  2. Your app calls FlagPal's API with Alice's properties reference Identifier user_alice_456.
  3. FlagPal returns the current set of Feature Flags for Alice:
    • Country: "DE" (Germany)
    • Plan: "premium"
  4. Your Application (FlagPal SDK) checks all active Experiences and Experiments for your project
  5. It finds an Experience with the rule: "Apply to users where country = DE"
  6. Alice matches, so FlagPal assigns her the Experience's Feature Set: { "show_german_homepage": true, "new_checkout": true }
  7. Your app sends a second API request to store these Agent feature flag values (new ones and old ones) for Alice.
  8. Your app sees these values and shows Alice the German homepage and new checkout

Storing vs. Evaluating Actors

There are two ways your application can work with actors in FlagPal:

Your app sends an actor's properties (Feature Flag values) to the FlagPal SDK and immediately receives the correct feature values. This is the most common and efficient approach, as it ensures data governance within your application and dramatically increases performance as it does not rely on API requests.

Stored Actor

Acting as an external database, FlagPal can store the evaluated feature values for an actor. This means a simpler implementation in your app as it can retrieve an actor's feature values from the API instead of creating a data structure internally. Usually, such a data storage solution is not a concern as our SDKs already provide this functionality out of the box. You should only consider this when implementing FlagPal manually and use this approach if you are unable to store your actor Feature Flags on your platform.

This approach also means FlagPal keeps a record of which features each actor has been assigned.

What Actor Information Can Be Used in Targeting Rules?

An Actor stores a set of Feature Flag values, so you can use any of these values in targeting rules, just like you would use any other feature flag value.

Privacy Considerations

FlagPal stores actor references and their feature values. You should:

  • Use some internal user ID as the reference (not personally identifiable information if possible)
  • Make sure your use of FlagPal complies with your privacy policy and any applicable regulations (GDPR, CCPA, etc.)

For non-developers As a non-technical user, you don't need to worry about the mechanics of how actors are created and managed — that's handled by your development team. What matters to you is that targeting rules work based on Feature Flags, so the quality of your targeting depends on what flags your developers are sending to FlagPal.