featbit-evaluation-insights-api

What this skill does

# FeatBit Flag Evaluation & Insights API

Direct HTTP access to FeatBit's evaluation server — the foundation for building custom SDKs on any platform (Kotlin, Swift, Android, iOS, Unity, embedded, etc.).

**Official documentation:**
- Flag Evaluation API: https://docs.featbit.co/api-docs/flag-evaluation-api
  (source: https://github.com/featbit/featbit-docs/blob/main/pages/api-docs/flag-evaluation-api.md)
- Track Insights API: https://docs.featbit.co/api-docs/track-insights-api
  (source: https://github.com/featbit/featbit-docs/blob/main/pages/api-docs/track-insights-api.md)

## When to Use This Skill

Activate when users:
- Build custom FeatBit SDK for Android, iOS/Swift, Kotlin, Unity, or any platform without an official SDK
- Call the evaluation server directly via HTTP without using a client library
- Need to implement flag evaluation + A/B experiment tracking from scratch
- Ask about `sendToExperiment`, variation insights, custom metric events, or batch insight payloads

## Prerequisites

Before writing any code:
1. **Evaluation server URL** — `{evaluation-server-url}` (e.g., `https://eval.your-featbit.com`). Found in your FeatBit dashboard under environment settings.
2. **Environment secret key** — client-side or server-side key. Include in every request header:
   ```
   Authorization: your-environment-secret-key
   ```
   > See [How to get the environment secret](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret)

## Core Workflow

This is the recommended pattern for a custom mobile/frontend SDK:

```
Step 1 ─ App launch       →  Evaluate ALL flags (or filtered by tags/keys)
Step 2 ─ Store locally    →  Cache results in memory for fast synchronous reads
Step 3 ─ Track insights   →  Fire-and-forget: send evaluation records to FeatBit
Step 4 ─ Poll for updates →  Repeat Step 1 periodically using `filter.timestamp`
Step 5 ─ Track metrics    →  Send custom events (conversion, click, purchase) as they occur
```

### Step 1: Evaluate Feature Flags

```
POST {evaluation-server-url}/api/public/featureflag/evaluate
Authorization: your-environment-secret-key
Content-Type: application/json
```

Minimal request body:

```json
{
  "user": {
    "keyId": "user-123",
    "name": "John Doe",
    "customizedProperties": [
      { "name": "country", "value": "US" },
      { "name": "plan", "value": "premium" }
    ]
  }
}
```

Response — array of flag evaluation results:

```json
[
  {
    "key": "new-checkout-flow",
    "variation": {
      "id": "08aceef3-5513-4b38-80ad-4b27bebe8871",
      "type": "boolean",
      "value": "true",
      "matchReason": "premium user rule",
      "sendToExperiment": true
    }
  }
]
```

Key fields:
- `variation.value` — always a **string**, cast to the needed type (`"true"` → boolean, `"104857600"` → number)
- `variation.sendToExperiment` — **save this**; pass it unchanged when tracking insights
- `variation.matchReason` — `"flag disabled"` | `"targeted"` | `"{rule name}"` | `"default"`

**Narrow the response with filters** (essential for reducing payload on mobile):

```json
{
  "user": { "keyId": "user-123" },
  "filter": {
    "keys": ["checkout-flow", "theme-color"],
    "tags": ["mobile"],
    "tagFilterMode": "and",
    "timestamp": 1704067200000
  }
}
```

> `filter.timestamp` — Unix ms. Returns only flags modified **after** this timestamp. Pass the timestamp from the previous call to implement efficient polling.

Read `references/flag-evaluation-api.md` for the complete schema, all filter options, and error responses.

### Step 2: Cache Locally

Store the response array in memory keyed by `flag.key`. Serve flag values synchronously from cache — never block UI on a network call.

### Step 3: Track Flag Evaluation Insights (fire-and-forget)

After evaluating flags, send evaluation records asynchronously.

```
POST {evaluation-server-url}/api/public/insight/track
Authorization: your-environment-secret-key
Content-Type: application/json
```

Request body — array of insight objects:

```json
[
  {
    "user": {
      "keyId": "user-123",
      "name": "John Doe",
      "customizedProperties": [
        { "name": "plan", "value": "premium" }
      ]
    },
    "variations": [
      {
        "featureFlagKey": "new-checkout-flow",
        "variation": {
          "id": "08aceef3-5513-4b38-80ad-4b27bebe8871",
          "value": "true"
        },
        "sendToExperiment": true,
        "timestamp": 1704067200000
      }
    ],
    "metrics": []
  }
]
```

> Response: `200 OK` with empty body on success. Do **not** await this in the main UI thread.

**Critical**:
- Copy `variation.id`, `variation.value`, and `sendToExperiment` exactly from the evaluation response. Do **not** derive or guess these values.
- At least one of `variations` or `metrics` must be non-empty in each insight object. A payload where both are empty arrays is a no-op.

### Step 4: Poll for Flag Updates

On a background timer, re-evaluate using `filter.timestamp` set to the time of the last successful poll. Only changed flags are returned — update your cache with the diff.

### Step 5: Track Custom Metric Events

When a user performs a meaningful action (purchase, conversion, click):

```json
[
  {
    "user": { "keyId": "user-123" },
    "variations": [],
    "metrics": [
      {
        "route": "/checkout/complete",
        "type": "CustomEvent",
        "eventName": "purchase-completed",
        "numericValue": 99.99,
        "appType": "Mobile",
        "timestamp": 1704067350000
      }
    ]
  }
]
```

> `appType` — use `"Mobile"` for Android/iOS apps, `"Web"` for browser-based apps.

Read `references/track-insights-api.md` for the complete schema, batch examples, and best practices.

## Decision Map

| Scenario | Action |
|---|---|
| Evaluate all flags on launch | POST evaluate with user, no filter |
| Evaluate only mobile-tagged flags | POST evaluate with `filter.tags: ["mobile"]` |
| Evaluate one specific flag | POST evaluate with `filter.keys: ["flag-key"]` |
| Detect flag changes since last poll | POST evaluate with `filter.timestamp: {lastPollMs}` |
| Record which variation user saw | POST track with `variations` array |
| Record A/B test conversion | POST track with `metrics` array |
| Record both at once | POST track with both `variations` and `metrics` in one payload |

## Mobile SDK Implementation Checklist

Copy and track progress:
- [ ] Step 1: Store evaluation server URL and secret key in app config (never hardcode in source)
- [ ] Step 2: At app startup, call evaluate endpoint and cache results in memory
- [ ] Step 3: Fire-and-forget: post flag variation insights immediately after evaluation
- [ ] Step 4: Implement background polling with `filter.timestamp` to pick up flag changes
- [ ] Step 5: Expose a `getFlag(key, defaultValue)` helper that reads from cache synchronously
- [ ] Step 6: On relevant user action, post metric insights asynchronously
- [ ] Step 7: On user context change (login, upgrade), re-evaluate immediately

## Reference Files

| File | Read when |
|---|---|
| `references/flag-evaluation-api.md` | User asks about exact request/response schema, filter parameters, error codes, or single-flag evaluation |
| `references/track-insights-api.md` | User asks about insights schema, batching multiple users, MetricInsight fields, or best practices |