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, passed to the Session Replay plugin. @amplitude/unified sets up the plugin on every init, whether or not this is set; 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. Passed to the Experiment plugin only when they include `deploymentKey`. @amplitude/unified sets up the plugin on every init; without a deploymentKey it uses the API key.
`engagement`	`any`	Guides & Surveys options object. @amplitude/unified loads the Guides & Surveys SDK from cdn.amplitude.com on every init, whether or not this is set; `true` passes no options.

* 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": "32bda52589e14e78",
  "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": "839bff8a70676571",
  "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": "f8c85a614e692b72",
  "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": "0d7854f97c5923ce",
  "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": "28ddc53c50a4d59e",
  "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

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,
    "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": "e8fc751a33540bca",
  "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": "77d35ababb1394c9",
  "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": "50001d0c51256e6a",
  "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": "75aaef747d55ac7d",
  "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. It still writes its event queue and plugin state to localStorage. 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.

Plugins

@amplitude/unified sets up Session Replay, Experiment, and Guides & Surveys on every init, whether or not the settings below are present; the settings only pass options to them. With just apiKey set, the SDK fetches the Session Replay remote configuration from Amplitude and loads the Guides & Surveys SDK from cdn.amplitude.com. Session Replay and Experiment ship in the destination's bundle.

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. Experiment uses experiment.deploymentKey, or the API key when it is missing.

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​

Plugins​

Related​

Installation

Configuration

Settings

Mapping

Defaults

Plugins

Related