Amperity

Access your Amperity tenant

Log in to the Amperity dashboard at app.amperity.com. Two values you’ll need:

• Tenant subdomain — the host in your dashboard URL (e.g. acme in https://acme.amperity.com). Used to build every API URL.
• Tenant ID — the value Amperity expects in the Amperity-Tenant HTTP header. Usually the same as the subdomain, but in some multi-tenant demo/sandbox setups they differ.

Create a realtime event stream

Navigate to Sources > Streams and click Add Stream. Configure the routing expression to match the source value Datafly will send (e.g. routing on source == "DATAFLY" → your target event type).

After creation, copy the Event Stream ID — it’s prefixed esm- (e.g. esm-2VP6va3Zn).

Generate the Streaming Ingest API key

Go to Settings > Security > API Keys > Add API key. Select Streaming Ingest Write Access. Generate the JWT and copy the token immediately — it won’t be shown again.

Configure Profile API access (optional but recommended)

For profile enrichment + browser personalisation you also need:

• Profile API Index — a published Profile API index, identified by its ID (e.g. apc-vPsQheAm). Each index has a single lookup key — the field you query it by. Publish one index keyed on amperity_id for enrichment, and (optionally) further indexes keyed on the identifiers you resolve visitors by (e.g. a hashed email or a device cookie).
• Profile API Key — a separate JWT with Profile Read Access scope. Must be distinct from the Streaming Ingest key; Amperity rejects cross-scope usage with 403.
• Hosting region — Azure-hosted tenants are reached at https://{tenant_subdomain}.amperity.com. AWS-hosted tenants are reached at https://app.amperity.com — set the Profile API Base URL field accordingly. Ask your Amperity admin which region your tenant is in.

Install the integration

Go to Integrations → Integration Library, find Amperity, click Install, and fill in all required fields with values from the prerequisites above.

Set linking keys (optional — for profile enrichment)

If you want Amperity profile attributes attached to every event (or exposed to the browser), configure the linking keys. See Linking keys below.

Set the browser allowlist (optional — for personalisation)

To expose profile attributes to window.datafly.profile.amperity in datafly.js, list them as a comma-separated string. Anything not in this list is stripped server-side before it reaches the browser.

Attach to a pipeline

From the pipeline page, add the Amperity integration. The blueprint (v1.8.0) provides 40+ flat global mappings shared across every vertical, plus vertical-specific event handlers so events flow through with minimal customisation.

Pick a vertical preset

The blueprint ships seven vertical presets — pick the one that matches your business and the event handlers will be pre-configured for that domain:

All presets share the same global mappings (identity, network, locale, page, session, campaign, geo, vendor IDs, consent), so the only difference between them is the event handlers and the property names they pull off event.properties.*. Unmapped events still pass through (the blueprint defaults to pass_through), so you can ship custom event names without changing the blueprint.

Resolve the visitor

Using the configured linking keys, Signal issues Profile API lookups until one matches. Each lookup is a GET /api/indexes/{index_id}/profiles/{lookup_value} against the index keyed on that identifier. Signal reads the visitor’s amperity_id from the resolved profile (the amperity_id attribute, falling back to the response id). Successful resolutions are cached server-side so subsequent events skip the call; failed resolutions are dampened to keep partner API traffic bounded.

Fetch profile attributes

Given the resolved amperity_id, Signal calls GET /api/indexes/{index_id}/profiles/{amperity_id} (against an index keyed on amperity_id) and receives the full attribute map. Every call carries the required headers: Authorization: Bearer {profile_api_key}, Amperity-Tenant: {tenant_id}, and api-version: 2025-07-31. The response shape is {"id": …, "index_id": …, "attributes": { … }}.

Attach to the event

Attributes are attached to the event as partner_attrs.amperity and are accessible to every downstream blueprint via source paths like:

global:
  mappings:
    - source: partner_attrs.amperity.Persona
      target: user_persona
    - source: partner_attrs.amperity.LifetimeTier
      target: user_tier

This lets Meta CAPI, GA4, TikTok, etc. receive enriched Amperity attributes on every event without each integration doing its own Amperity lookup.

Flow

1. The visitor’s attributes are resolved server-side via the Amperity Profile API and filtered through browser_attribute_allowlist.
2. The filtered profile is made available to Datafly.js on init.
3. Browser code reads datafly.profile.amperity after datafly.onProfileReady() resolves.

Page-side usage

datafly.init({
  pipelineKey: '...',
  endpoint: 'https://collect.example.com',
  // Baked in by the Collector tab when Amperity personalisation is enabled:
  enrich: {
    endpoint: 'https://id.example.com',
    providers: ['amperity'],
  },
});
 
await datafly.onProfileReady();
const persona = datafly.profile.amperity?.Persona;
if (persona === 'Value Hunter') {
  document.querySelector('#hero').dataset.variant = 'promo';
}
 
// After a user logs in / identifies, you can refresh to pick up richer attributes:
datafly.identify('user-123', { email: 'alice@example.com' });
await datafly.refreshProfile();

What the browser can and cannot see

• Only attributes in browser_attribute_allowlist — configured server-side, not overridable by page code.
• Empty-attributes response (HTTP 200 with attributes: {}) for first-touch visitors with no resolved profile.
• Never the Profile API token.
• Never the raw Amperity response — always filtered server-side first.

Event ingest

1. Fire a test event from your website or Signal’s event API.
2. In Signal, open Live Events and click the event — the Vendor Request tab should show POST https://{tenant_subdomain}.amperity.com/prof/events/{event_stream_id} with status 202.
3. In Amperity, navigate to your stream’s event inspector. Within ~5 seconds the event appears; within ~15 seconds the profile’s updated_at and any configured aggregations update.

Profile enrichment

1. Ensure Profile API creds + linking keys are set.
2. Fire an event from a visitor whose identifier matches an existing profile (e.g. send an identify with an email that’s in your Amperity collection).
3. Inspect the next outbound event — its Transformed Event tab should show partner_attrs.amperity populated.

Browser personalisation

1. Ensure browser_attribute_allowlist is set and datafly.js is built with enrich config.
2. Open browser devtools → Network tab.
3. Load the page. You should see GET /v1/enrich?provider=amperity fire after init, returning {provider: "amperity", attributes: {...}} with only the allowlisted keys.
4. In the console, window.datafly.profile.amperity should match the response’s attributes.