> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Amplitude

<!-- -->

[Web](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/amplitude)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/amplitude)[ ](https://www.npmjs.com/package/@walkeros/web-destination-amplitude)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/web-destination-amplitude)

[Amplitude](https://amplitude.com/) is a product analytics platform with built-in identity, revenue, groups, and optional session replay, feature experiments, and guides & surveys. This destination forwards walkerOS events to Amplitude via the official [`@amplitude/unified`](https://www.npmjs.com/package/@amplitude/unified) SDK, translating events into `amplitude.track(...)`, `identify(...)`, `revenue(...)`, `setGroup(...)`, and `setOptOut(...)` calls. Loads the Amplitude Analytics SDK, forwards every walkerOS event, and lets you layer on identity, revenue, groups, consent toggling, and optional plugins.

<!-- -->

Where this fits

Amplitude is a **web destination** in the walkerOS flow:

## Installation[​](#installation "Direct link to Installation")

```
npm install @walkeros/web-destination-amplitude
```

* Integrated
* Bundled

```
import { startFlow } from '@walkeros/collector';
import { destinationAmplitude } from '@walkeros/web-destination-amplitude';

await startFlow({
  destinations: {
    amplitude: {
      code: destinationAmplitude,
      config: {
        consent: { analytics: true },
        settings: {
          apiKey: 'YOUR_AMPLITUDE_API_KEY',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```
"destinations": {
  "amplitude": {
    "package": "@walkeros/web-destination-amplitude",
    "config": {
      "consent": { "analytics": true },
      "settings": {
        "apiKey": "YOUR_AMPLITUDE_API_KEY"
      }
    }
  }
}
```

[See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->destination<!-- --> uses the standard <!-- -->destination<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [destination<!-- --> configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property              | Type                           | Description                                                                                                                                                              | More |
| --------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| `apiKey*`             | `string`                       | Your Amplitude project API key. Find it in your Amplitude project settings under "General" → "API Keys" (like a1b2c3d4e5f6789012345678abcdef12).                         |      |
| `serverZone`          | `'US' \| 'EU'`                 | Amplitude server zone. Default: US.                                                                                                                                      |      |
| `flushIntervalMillis` | `integer`                      | How often (in ms) to flush the event queue. Default: 1000.                                                                                                               |      |
| `flushQueueSize`      | `integer`                      | Max queued events before a flush. Default: 30.                                                                                                                           |      |
| `flushMaxRetries`     | `integer`                      | Max retries on failed flush. Default: 5.                                                                                                                                 |      |
| `transport`           | `'fetch' \| 'xhr' \| 'beacon'` | HTTP transport. Default: fetch.                                                                                                                                          |      |
| `useBatch`            | `boolean`                      | Use the Amplitude batch endpoint instead of the standard endpoint. Default: false.                                                                                       |      |
| `appVersion`          | `string`                       | Application version; tagged onto every event.                                                                                                                            |      |
| `identify`            | `any`                          | walkerOS mapping value resolving to an identity object. Keys: user, device, session, set, setOnce, add, append, prepend, preInsert, postInsert, remove, unset, clearAll. |      |
| `sessionReplay`       | `any`                          | Session Replay options. When present, session replay is enabled via @amplitude/unified with the provided options.                                                        |      |
| `experiment`          | `any`                          | Feature Experiment config. Must include \`deploymentKey\`. When present, the experiment plugin from @amplitude/unified is configured with the provided options.          |      |
| `engagement`          | `any`                          | Guides & Surveys config. Pass \`true\` for defaults, or an options object for custom configuration. Enabled via @amplitude/unified.                                      |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

| Property        | Type  | Description                                                                                                                                                                                                                               | More |
| --------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `identify`      | `any` | Per-event identity mapping. Resolves to an object with any of: user, device, session, set, setOnce, add, append, prepend, preInsert, postInsert, remove, unset, clearAll.                                                                 |      |
| `revenue`       | `any` | Revenue mapping. Resolves to a single object or (via loop) an array of objects, each with: productId, price, quantity, revenueType, currency, revenue, receipt, receiptSig, eventProperties. One amplitude.revenue() call fires per item. |      |
| `group`         | `any` | Group assignment. Resolves to { type, name } → amplitude.setGroup(type, name).                                                                                                                                                            |      |
| `groupIdentify` | `any` | Group properties. Resolves to { type, name, set?, setOnce?, ... } → amplitude.groupIdentify(type, name, identify).                                                                                                                        |      |
| `reset`         | `any` | Logout trigger. Resolves to a truthy value → amplitude.reset() (clears userId, regenerates deviceId). Typically used with silent: true on a user logout rule.                                                                             |      |

## Examples

### Consent granted

A walker consent command with analytics granted opts back into Amplitude tracking via setOptOut(false).

Event

```
{
  "analytics": true
}
```

Out

```
amplitude.setOptOut(false)
```

### Consent revoked

A walker consent command with analytics denied opts out of Amplitude tracking via setOptOut(true).

Event

```
{
  "analytics": false
}
```

Out

```
amplitude.setOptOut(false);

amplitude.setOptOut(true)
```

### Default track

A walker event is forwarded to Amplitude as an amplitude.track call with the event name and empty properties.

Event

```
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "3c4a9fe4fad33ca8",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
amplitude.track("product view", {})
```

### Destination identify

Destination-level identify sets userId, deviceId, and sessionId on the Amplitude client before sending events; setters only re-fire when the resolved values change (cached values are not re-applied on subsequent pushes).

Event

```
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "7fa55cc0191bed62",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000104,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
amplitude.setUserId("us3r");

amplitude.setDeviceId("c00k13");

amplitude.setSessionId(394324160);

amplitude.track("page view", {})
```

### Include data

Destination-level include flattens the event data section into prefixed event\_properties on every track call.

Event

```
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "f0f99231bc65309d",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000102,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
amplitude.track("product view", {
  "data_id": "ers",
  "data_name": "Everyday Ruck Snack",
  "data_color": "black",
  "data_size": "l",
  "data_price": 420
})
```

### Group assignment

A company update assigns the user to a group and sets group properties via setGroup and groupIdentify.

Event

```
{
  "name": "company update",
  "data": {
    "company": "Acme",
    "industry": "tech",
    "employee_count": 50,
    "founded_year": 2020
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "06c7bc9163bb6540",
  "trigger": "test",
  "entity": "company",
  "action": "update",
  "timestamp": 1700000109,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "group": {
      "map": {
        "type": {
          "value": "company"
        },
        "name": "data.company"
      }
    },
    "groupIdentify": {
      "map": {
        "type": {
          "value": "company"
        },
        "name": "data.company",
        "set": {
          "map": {
            "industry": "data.industry",
            "size": "data.employee_count"
          }
        },
        "setOnce": {
          "map": {
            "founded": "data.founded_year"
          }
        }
      }
    }
  }
}
```

Out

```
amplitude.setGroup("company", "Acme");

amplitude.groupIdentify("company", "Acme", {
  "set": {
    "industry": "tech",
    "size": 50
  },
  "setOnce": {
    "founded": 2020
  }
})
```

### Multi-product order

An order fires one amplitude.revenue call per nested product plus a single track for the order totals.

Event

```
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "93d748c3cfe83cf0",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000108,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "include": [
    "data",
    "globals"
  ],
  "settings": {
    "revenue": {
      "loop": [
        "nested",
        {
          "condition": {
            "$code": "e=>{var t;return\"number\"==typeof(null==(t=null==e?void 0:e.data)?void 0:t.price)}"
          },
          "map": {
            "productId": "data.id",
            "price": "data.price",
            "quantity": {
              "key": "data.quantity",
              "value": 1
            },
            "revenueType": {
              "value": "purchase"
            },
            "currency": {
              "key": "data.currency",
              "value": "EUR"
            }
          }
        }
      ]
    }
  }
}
```

Out

```
amplitude.revenue({
  "productId": "ers",
  "price": 420,
  "quantity": 1,
  "revenueType": "purchase",
  "currency": "EUR"
});

amplitude.revenue({
  "productId": "cc",
  "price": 42,
  "quantity": 1,
  "revenueType": "purchase",
  "currency": "EUR"
});

amplitude.track("order complete", {
  "data_id": "0rd3r1d",
  "data_currency": "EUR",
  "data_shipping": 5.22,
  "data_taxes": 73.76,
  "data_total": 555,
  "globals_pagegroup": "shop"
})
```

### Rule include overrides

A per-rule include replaces the destination-level include for the matched event, here using only globals.

Event

```
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "0bfea13214d4cc1c",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000103,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "include": [
    "globals"
  ]
}
```

Out

```
amplitude.track("order complete", {
  "globals_pagegroup": "shop"
})
```

### Subscription revenue

A subscription renewal fires a single amplitude.revenue call with productId, price, and currency fallback.

Event

```
{
  "name": "subscription renew",
  "data": {
    "plan_id": "plan-pro",
    "amount": 9.99
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f9caea2b0f349efe",
  "trigger": "test",
  "entity": "subscription",
  "action": "renew",
  "timestamp": 1700000107,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "revenue": {
      "map": {
        "productId": "data.plan_id",
        "price": "data.amount",
        "revenueType": {
          "value": "renewal"
        },
        "currency": {
          "key": "data.currency",
          "value": "EUR"
        }
      }
    }
  }
}
```

Out

```
amplitude.revenue({
  "productId": "plan-pro",
  "price": 9.99,
  "revenueType": "renewal",
  "currency": "EUR"
})
```

### User login identify

A user login sets the Amplitude userId and runs identify with set, setOnce, and add operations.

Event

```
{
  "name": "user login",
  "data": {
    "user_id": "new-user-123",
    "plan": "premium",
    "company": "Acme",
    "email": "user@acme.com"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "d1eab5d325755f6e",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000105,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "user": "data.user_id",
        "set": {
          "map": {
            "plan": "data.plan",
            "company": "data.company",
            "email": "data.email"
          }
        },
        "setOnce": {
          "map": {
            "first_login": "timestamp"
          }
        },
        "add": {
          "map": {
            "login_count": {
              "value": 1
            }
          }
        }
      }
    }
  }
}
```

Out

```
amplitude.setUserId("new-user-123");

amplitude.identify({
  "set": {
    "plan": "premium",
    "company": "Acme",
    "email": "user@acme.com"
  },
  "setOnce": {
    "first_login": 1700000105
  },
  "add": {
    "login_count": 1
  }
})
```

### User logout reset

A user logout calls amplitude.reset to clear the userId and regenerate the deviceId.

Event

```
{
  "name": "user logout",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "bfab41f58a0e9349",
  "trigger": "test",
  "entity": "user",
  "action": "logout",
  "timestamp": 1700000106,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "reset": true
  }
}
```

Out

```
amplitude.reset()
```

## Plugins[​](#plugins "Direct link to Plugins")

All three plugin packages are npm-bundled with the destination (\~135 KB for Session Replay plus Experiment and Engagement payloads). Enable them via destination settings:

```
settings: {

  apiKey: 'YOUR_KEY',

  sessionReplay: { sampleRate: 1 },

  experiment: { deploymentKey: 'DEPLOYMENT_KEY' },

  engagement: true,

}
```

## Related[​](#related "Direct link to Related")

* [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2)
* [Amplitude Session Replay](https://amplitude.com/docs/session-replay)
* [Amplitude Experiment](https://amplitude.com/docs/experiment)
* [Amplitude Guides & Surveys](https://amplitude.com/docs/guides-and-surveys)