Ask your AI

Amplitude

Amplitude 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 SDK, translating events into amplitude.track(...), identify(...), revenue(...), setGroup(...), and setOptOut(...) calls.

Where this fits

Amplitude is a web destination in the walkerOS flow:

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 | CLI reference

Configuration

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings

Property	Type	Description
`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 set, the Session Replay plugin starts; the other plugins start only from their own settings. It records a sampled share of sessions, set by the project sampling settings in Amplitude when present, else by sampleRate (default 0).
`experiment`	`any`	Feature Experiment options. The Experiment plugin starts only when they include `deploymentKey`; the other plugins start only from their own settings.
`engagement`	`any`	Guides & Surveys options object; `true` passes no options. When set, the Guides & Surveys plugin starts and loads its SDK from cdn.amplitude.com; the other plugins start only from their own settings.

* Required fields

Mapping

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Property	Type	Description
`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

With consent: { analytics: true } in the destination config, a walker consent command that grants analytics opts into Amplitude tracking via setOptOut(false).

Event

{
  "analytics": true
}

Out

amplitude.setOptOut(false)

Consent revoked

With consent: { analytics: true } in the destination config, a walker consent command that denies analytics 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": "db22fb16c70f663d",
  "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

With settings.identify mapping user, device, and session to 'user.id', 'user.device', and 'user.session', the destination sets userId, deviceId, and sessionId before the track call. A non-numeric session string is hashed to a stable number. Setters only re-fire when the resolved values change.

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": "f0cc5f6fec3d8eeb",
  "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

With include: ['data'] in the destination config, the event data section is flattened 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": "db22fb16c70f663d",
  "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": "d4f12311e59536f9",
  "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,
    "value": 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": "235d0d7bd7a213f2",
  "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_value": 555,
  "globals_pagegroup": "shop"
})

Rule include overrides

With include: ['data'] in the destination config, the rule's include: ['globals'] replaces it, so this event forwards only globals.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "value": 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": "235d0d7bd7a213f2",
  "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": "7ac0e9f89e2de3f6",
  "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": "7915c2aafa2878b8",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000105000,
  "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": 1700000105000
  },
  "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": "f61213223ce02c69",
  "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()

Defaults

walkerOS sets two defaults that differ from Amplitude's: autocapture: false, because walkerOS sources capture events, and identityStorage: 'none', so the SDK sets no identity cookies. At init the SDK still fetches its remote configuration from Amplitude (sr-client-cfg.amplitude.com, or the EU host with serverZone: 'EU') and keeps it in localStorage, next to its queue of unsent events and the state of any plugin that runs. fetchRemoteConfig: false turns that fetch off. Without stored identity, Amplitude starts a new device ID and session on every page load. To keep them across page loads, map device and session in settings.identify (see the Destination identify example above), or set identityStorage yourself.

The destination's config.consent decides when Amplitude is allowed to collect: a revocation calls setOptOut(true) and a grant setOptOut(false). A missing apiKey fails the destination with a config error. Otherwise an event counts as delivered once the Amplitude SDK has accepted the call, and only a call that throws fails it. The SDK sends events afterwards, and a request that Amplitude rejects (a wrong apiKey) or that never reaches Amplitude is not reported: the push result stays ok, status.destinations.amplitude.failed stays 0 and no ERROR line is logged. The only sign is the SDK's own console message, Amplitude Logger [Error].

Plugins

With just apiKey set, only Amplitude analytics starts. Session Replay, Experiment, and Guides & Surveys start only when you enable them: setting sessionReplay, experiment.deploymentKey or engagement starts that plugin and no other. Guides & Surveys loads its SDK from cdn.amplitude.com. Session Replay and Experiment ship in the destination's bundle. The settings accept SDK options that the schema does not list and pass them through.

Session Replay records a sampled share of sessions. The share is sessionReplay.sampleRate (default 0) unless the project's Session Replay sampling settings in Amplitude set it; those take precedence and also decide whether capture is on.

settings: {
  apiKey: 'YOUR_KEY',
  sessionReplay: { sampleRate: 1 },
  experiment: { deploymentKey: 'DEPLOYMENT_KEY' },
}

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

Installation​

Configuration​

Settings​

Mapping​

Examples

Consent granted

Consent revoked

Default track

Destination identify

Include data

Group assignment

Multi-product order

Rule include overrides

Subscription revenue

User login identify

User logout reset

Defaults​

Consent and failures​

Plugins​

Related​

Installation

Configuration

Settings

Mapping

Defaults

Consent and failures

Plugins

Related