Destination analytics
Map augeo.event onto destination names and piggyback writers.
What this package does not do
@kigo-digital/augeo-events fires no events. It holds no identity. It does not
decide where events are sent. That charter is load-bearing: a dictionary that
called gtag('config') or PostHog.init() would mint a second tracker beside
the one the host already loaded.
What it does ship is the destination binding: a mapping from a registered
augeo.event onto a destination event name plus params, plus optional pure
writers that assume the host already initialized the tag. Subscribe, consent,
and fan-out live in the implementing SDK, not here.
Entry points
| Import | Holds |
|---|---|
@kigo-digital/augeo-events/analytics/core | mapping, CloudEvents conversion, denylist — no destination writers |
@kigo-digital/augeo-events/analytics/gtag | createGtagAdapter |
@kigo-digital/augeo-events/analytics/gtm | createGtmAdapter |
@kigo-digital/augeo-events/analytics/custom | createCustomAdapter |
@kigo-digital/augeo-events/analytics | all of the above |
Import /analytics/core from a widget bundle that must not contain gtag.
Import a writer only from the host (or an SDK entry the IIFE does not load).
Importing /analytics pulls the writers into that graph.
Look up a destination name
The vendor-neutral lookup is destinationEventFor. Registry field ga4 is still
the source of the default name; ga4EventFor is a published alias of the same
function.
import { destinationEventFor, ga4EventFor } from "@kigo-digital/augeo-events/analytics/core";
destinationEventFor("com.augeo.engagement.cart.item.added"); // "add_to_cart"
destinationEventFor("com.augeo.ui.action.pressed"); // null — observed, no projection
ga4EventFor("com.augeo.engagement.cart.item.added") ===
destinationEventFor("com.augeo.engagement.cart.item.added");null is an answer: that name is not forwarded. Do not invent a destination
event for it. Observed ui.* names are in this set on purpose.
The default projection for every registered name is on Destination names. A host overlay can rename a row; that page is the default, not a ceiling. The same lookup is on the published package:
import { destinationEventFor } from "@kigo-digital/augeo-events/analytics/core";
destinationEventFor("com.augeo.engagement.item.viewed"); // "theo_item_impression"A per-item impression is not GA4 view_item. view_item belongs to
engagement.item.detail.viewed. Projecting a card someone scrolled past onto
view_item made it indistinguishable from a product they opened.
engagement.cart.item.updated follows the sign of the quantity delta when
both item.quantity and previousQuantity are present: a decrease maps to
remove_from_cart, otherwise the registry default (add_to_cart). GA4 has no
quantity-change event; the canonical stream still keeps add and update as
separate names.
Map an event
applyMapping takes the compact envelope, an optional host overlay, and an
optional identity callback. Registry defaults first, overlay last. Only keys the
mapping named leave.
import { applyMapping } from "@kigo-digital/augeo-events/analytics/core";
const result = applyMapping(event);
if (!result.ok) {
// "mapped_drop" | "direct_identifier_blocked" | "forbidden_key"
return;
}
result.mapped.event; // destination event name
result.mapped.params; // only mapped scalars
result.mapped.items; // ItemRef → GA4 items[], when present
result.mapped.kind; // "standard" | "custom" | "none"A host overlay renames the destination event and adds params. It does not invent
a parallel catalog of augeo.event names.
const overlay = {
allowDirectIdentifiers: ["userId"],
events: {
"com.augeo.engagement.cart.item.added": {
event: "theo_add_to_cart",
params: {
placement_type: { from: "context.storefront.attribution" },
catalog_id: { from: "context.storefront.catalogId" },
member_key: { identity: "userId" },
product_id: { from: "data.occurrence.item.id" },
},
},
},
};
applyMapping(event, overlay, { userId: () => hostMemberId });from is a dot-path on the compact envelope. A path starting context. is
read as data.context.. { const: value } writes a literal. { identity: "userId" }
calls the host callback only if allowDirectIdentifiers includes userId.
The overlay chooses the destination param name. This package never bakes a
host-specific key such as prysm_user_id into the mapping. That name belongs in
the host overlay, not the library.
Setting event: null drops the name. Unmapped keys do not travel.
PDP guidance projection
Rewards Hub owns the PDP UI component and host integration. The AI integration defines the event/integration contract and owns contextual Chat wiring, semantic measurement and backend intake. Rewards Hub implements against that contract using the existing event system. Native facts must conform to the registered profile; a different mapping requires an explicit AI-owned contract revision. Design-system provenance applies only to design-system reuse. The event bus carries no question text or labels. The host integration supplies those privately to the existing local contextual Chat operation. These recipes neither build a standalone PDP SDK nor start a Chat turn.
Four measured names already have destination events: theo_launcher_viewed,
theo_prompt_selected, theo_turn_requested and theo_turn_admission_reported.
On source.surface pdp_guidance, applyMapping also fills scalar params for
that recipe. The same names on any other surface keep the name-only default.
Observed ui.* inputs, including the native chip press, still have no default
projection. Registration does not enable a layer, grant consent, configure
forwarding, or select an account, warehouse, collector or provider.
Only those scalars leave. Missing and blank values are omitted. The nested
prompt-presentation item is not turned into an ecommerce items array.
programId and placementId are included when the envelope already has them.
causationId, a known conversationId, and turnId on a request or outcome
are included only as correlation mirrors. Product id, question text and URL are
not used as subject and do not authorize the write.
participantRef is not a default param. An overlay may map that opaque value
only as participant_ref. That mapping does not call DestinationIdentity.userId.
userId stays blocked for this composition even if the overlay sets
allowDirectIdentifiers.
An overlay that reads question or seed text, a prompt label, a member or
identity id, rewardsAuthorityFingerprint, a token, email, profile data, an
exact balance, a product snapshot, attributes, title, price, a URL, a selector,
PdpHostScope, or an object bag fails with forbidden_key. Renaming the
destination key, or writing the path as context.* instead of data.context.*,
does not bypass that. A native chip press that carries prompt presentation is
held to the same rule, so its label cannot leave through a host-chosen param.
| Destination key | When it is set |
|---|---|
event_id, source_surface, presentation, prompt-set and item scalars, causation_id | all four measured names, omitting a missing causation id |
placement_id, program_id | when resolved |
exposure_ms | launcher impression |
prompt_id, prompt_type, prompt_source, position, presentation, gesture_key | choice, request and outcome |
client_turn_id | request and outcome, when the turn is known |
conversation_id | when the thread is known |
admission_status, plus admission_disposition and user_message_id or outcome_code | admission outcome; the unused branch is omitted |
Identity stays on the destination, not the envelope
Three different things get collapsed. Keep them apart.
| Surface | What it may carry |
|---|---|
Compact augeo.event (Layer 1) | opaque theo.participantRef only — no email, phone, name, card, or raw member id |
| Destination params (Layer 3) | only keys the overlay mapped, plus items from ItemRef when the kind is standard |
| Host identity callback | a user id for the destination, never copied onto augeo.event |
{ identity: "userId" } without allowDirectIdentifiers: ["userId"] fails
closed (direct_identifier_blocked). PDP guidance never resolves userId, even
when the overlay opts in. That hatch does not unlock email, phone, card,
person name, or billing address. Those destination keys are refused even when
the overlay names them (forbidden_key).
participantRef is not a drop-in for a host profile id. It is a hash of the
SDK's API user, minted by the SDK. If a destination report already joins on a
host profile id, the host supplies that id through the mapping, on Layer 3 only.
CloudEvents conversion
Compact form is what the browser bus carries. CloudEvents 1.0 is the form at the SDK boundary and up. The conversion is total for the compact fields this package knows about:
import { toCloudEvent, fromCloudEvent } from "@kigo-digital/augeo-events/analytics/core";
const cloud = toCloudEvent(event);
const compact = fromCloudEvent(cloud);source.surface and source.instanceId are URI-encoded as path components so a
value containing / round-trips. Promoted CloudEvents attributes (eventclass,
programid, family, origin) still mirror data.context.theo and must not
contradict it.
Writers (piggyback only)
A writer calls a tag the host already initialized. It does not insert a
script, does not call gtag('config'), and does not create window.dataLayer.
import { applyMapping, toCloudEvent } from "@kigo-digital/augeo-events/analytics/core";
import { createGtagAdapter } from "@kigo-digital/augeo-events/analytics/gtag";
const adapter = createGtagAdapter({ gtag: window.gtag });
if (!adapter.ready?.()) {
// destination_not_ready — do not inject gtag.js from here
}
const mapped = applyMapping(event, overlay, identity);
if (!mapped.ok) return;
adapter.send({
event,
cloudEvent: toCloudEvent(event),
mapped: mapped.mapped,
});| Writer | Call | If the tag is missing |
|---|---|---|
createGtagAdapter | gtag('event', name, params) | send throws destination_not_ready |
createGtmAdapter | dataLayer.push({ event, ...params }) | buffers up to 50 dispatches on that adapter instance |
createCustomAdapter | the function you passed | whatever you implement |
Do not enable gtag and GTM writers together on a page that already uses gtag directly. One destination, one writer.
A custom writer is how PostHog, Mixpanel, Amplitude, Matomo, Plausible, Fathom,
Adobe Analytics, Piwik PRO, or an ad platform is added today: same
AnalyticsAdapter shape, your send. Built-in loaders that call vendor.init()
are out of this package on purpose.
Consent and fan-out are not here
DestinationDeclineReason includes consent_withheld, disabled, lifecycle,
and adapter_error because the SDK runtime uses those codes. This package
does not read cookies, does not guess a CMP, and does not subscribe to
augeo.event. If consent is omitted at the SDK, that means the host tag already
handled it (piggyback). If consent is provided there, the SDK gates on it.
Related
- Getting started — emit and consume the compact envelope
- Event names — the vocabulary
destinationEventForprojects - Destination names — default destination event for every registered name
- Validating events — check a document at a boundary