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 personalization you also need:

• Profile Collection ID — from the dashboard collection you want to query, prefixed apc- (e.g. apc-vPsQheAm).
• 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.
• Linking keys — the collection’s linking_keys array determines which identifiers Signal can use to resolve visitors. Add at least one of: _dfdid (device cookie), email_sha256, phone_sha256, or a customer-specified account_id. Ask your Amperity admin to add these if they aren’t configured.

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 personalization)

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 — the pipeline transformation engine simply forwards them flat.

Resolve the visitor

Using the configured linking keys, Signal issues Profile API lookups until one matches. Result cached in Redis (15 min positive, 5 min negative) so subsequent events skip the call.

Fetch profile attributes

Given the resolved amperity_id, Signal calls GET /prof/profiles/{collection_id}/{amperity_id} and receives the full attribute map.

Attach to the event

Attributes land on event.Context.PartnerAttrs.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. Event-processor resolves the visitor and fetches attributes (as above).
2. Result is filtered through browser_attribute_allowlist and written to a separate Redis cache keyed by the visitor’s _dfdid.
3. Datafly.js fires GET /v1/enrich?provider=amperity against identity-hub on init; the endpoint reads the filtered cache and returns it.
4. 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 JS Builder when Amperity personalization 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: '[email protected]' });
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 personalization

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.