Location Analytics Event Taxonomy: A Naming Standard for Impressions, Visits, Dwell, and Conversions
analyticsevent taxonomySDKsdata modelinggeofencingmeasurement

Location Analytics Event Taxonomy: A Naming Standard for Impressions, Visits, Dwell, and Conversions

NNearI Labs
2026-11-18
7 min read

A practical location analytics event taxonomy for tracking exposure, visits, dwell, scans, redemptions, purchases, consent, and schema changes.

A reliable location analytics system starts with a consistent event taxonomy. This guide defines a practical naming standard for exposure, entry, dwell, exit, scans, redemptions, and purchases, then shows how to add consent, deduplication, QA, versioning, and dashboard migration controls so results remain comparable across apps, stores, SDKs, and measurement vendors.

Overview

Location marketing data often becomes difficult to compare because different systems use different definitions. One platform may call an ad interaction an impression, another may record an exposure only after a device meets a delivery condition, and a store-visit vendor may use its own entry and dwell logic. Without a shared event model, campaign reports can show conflicting totals even when the underlying activity is similar.

An event taxonomy is the agreed vocabulary and structure used to describe those actions. It should answer four questions for every event:

  • What happened? For example, an exposure was recorded or a visitor crossed a store boundary.
  • Where and when did it happen? The event needs a location reference and a precise event time or time window.
  • How was it measured? The collection method, source, and measurement version help explain differences between signals.
  • Was it permitted and usable? Consent, purpose, retention, and data-quality fields should travel with the event.

The model below is intended as a neutral reference for a proximity marketing SDK, a warehouse-based location analytics pipeline, or an API that receives events from several vendors. Adapt field names to your stack, but preserve the definitions and relationships.

What to track

Core event taxonomy

Use a stable namespace and a verb that describes the observed action. A practical starting point is:

Event nameDefinitionTypical next event
location.exposureAn eligible device, account, or consented audience member was recorded as exposed to a campaign or placement.location.entry or qr.scan
location.entryA location signal met the configured rules for entering a store, venue, or geofence.location.dwell_start
location.dwell_startThe system began a qualified dwell interval according to the location measurement definition.location.dwell_end
location.dwell_endA qualified dwell interval ended or reached its closing condition.location.exit
location.exitThe signal met the configured rules for leaving a location or geofence.commerce.purchase
qr.scanA QR code was scanned and the scan was accepted by the campaign endpoint.qr.landing_view or commerce.redemption
commerce.redemptionA campaign code, offer, or benefit was successfully redeemed.commerce.purchase
commerce.purchaseA purchase or qualified transaction was attributed to the configured campaign or location flow.None or a repeat purchase event

Field-by-field schema

Each event should contain an envelope shared across event types. Event-specific properties should be added only when they can be defined consistently.

FieldPurposeExample or guidance
event_nameCanonical event identifier.location.entry
schema_versionVersion of the payload contract.1.2; increment when meaning or required structure changes.
event_idUnique identifier used for idempotency and deduplication.Generate at collection or ingestion time according to your implementation.
event_timeTime at which the underlying action was observed.Use a normalized timestamp and preserve the source timezone separately if needed.
received_timeTime the platform received the event.Useful for detecting offline delivery and processing delays.
sourceCollection channel or vendor source.sdk, server, qr_endpoint, or a named integration.
campaign_idStable campaign reference.Do not use a display name as the primary key.
placement_idAd, beacon, QR code, geofence, or media placement reference.Required when one campaign has multiple activation points.
location_idCanonical store, venue, or geofence reference.Map vendor-specific location IDs to an internal ID.
location_typeDescribes the measured boundary.store, venue, geofence, or beacon_zone.
measurement_methodExplains how the event was determined.gps, beacon, wifi, qr, or transaction, if applicable.
consent_statusRecords whether the signal was collected for the relevant purpose.Use controlled values such as granted, denied, unknown, or not_applicable.
consent_purposeConnects collection to a defined purpose.Keep purpose labels documented and avoid inferring permission from an unrelated setting.
subject_keyPrivacy-reviewed reference for joining permitted events.Prefer a scoped, pseudonymous key; do not place raw personal identifiers in location events.
attribution_windowStates the window used to connect exposure, visit, and conversion.Store the configuration or reference to it, not just the final result.
dwell_secondsQualified duration for a dwell event or completed visit.Populate only after the duration rule is satisfied.
transaction_idJoins a purchase or redemption to a transaction.Hash, tokenize, or otherwise protect it according to the data design.
value and currencyOptional commercial value fields.Define whether value is gross, net, estimated, or unavailable.
quality_statusIndicates whether the event passed validation.valid, late, duplicate, invalid, or quarantined.

Naming and versioning template

Use a predictable format such as domain.action. Keep the name short and place details in properties. For example, use location.entry rather than separate names for every store or campaign. A payload can follow this pattern:

{
  "event_name": "location.entry",
  "schema_version": "1.2",
  "event_id": "evt_example_123",
  "event_time": "2026-11-05T10:15:00Z",
  "source": "mobile_sdk",
  "campaign_id": "campaign_example",
  "location_id": "store_example",
  "location_type": "store",
  "measurement_method": "geofence",
  "consent_status": "granted",
  "consent_purpose": "measurement",
  "subject_key": "scoped_subject_example",
  "quality_status": "valid"
}

Use a major version for breaking changes, such as renaming a required field or changing the meaning of an event. Use a minor version for backward-compatible additions, such as an optional property. Maintain a changelog with the effective date, affected consumers, migration steps, and examples of old and new payloads.

Cadence and checkpoints

Instrumentation should be reviewed as an operating process rather than a one-time implementation. Use these checkpoints:

  1. Before launch: Document event definitions, required fields, consent states, location-boundary rules, attribution windows, and ownership. Confirm that every dashboard metric maps to one or more canonical events.
  2. During implementation: Test valid, denied, delayed, duplicated, out-of-order, and incomplete payloads. Verify that SDK and server events use the same IDs and definitions where a journey crosses both systems.
  3. Weekly during active campaigns: Review event volume, delivery latency, null rates, duplicate rates, and the progression from exposure to entry, dwell, redemption, and purchase.
  4. Monthly or quarterly: Compare vendor totals with warehouse totals, audit location mappings, inspect consent tagging, and review whether campaign teams have introduced unofficial event names.
  5. Before a migration: Freeze the old schema, map every legacy event to a canonical event, run parallel reporting, and record expected differences before retiring the old dashboard.

For deduplication, treat event_id as the preferred idempotency key. If a source cannot provide one, define a documented fallback based on the smallest permitted combination of source, time, location, campaign, and transaction attributes. Do not silently discard repeated events; label them as duplicates so delivery behavior remains visible.

How to interpret changes

A change in visits or conversions is not automatically a change in campaign performance. First separate measurement changes from behavioral changes.

  • Exposure rises but entries do not: Check campaign eligibility, location mapping, attribution windows, and whether exposure and entry use compatible identity or consent rules.
  • Entries rise but dwell falls: Review boundary size, dwell qualification, signal quality, and whether the entry event is being triggered by passersby.
  • Dwell is stable but purchases fall: Inspect redemption joins, transaction ingestion, value definitions, and checkout or offer changes before concluding that foot traffic became less valuable.
  • One vendor reports more visits: Compare event definitions, deduplication, sampling or suppression rules, location boundaries, and reporting time zones.
  • Totals change after an SDK release: Compare schema versions, event delivery timing, permission states, background behavior, and retry logic. Preserve pre-release and post-release cohorts where possible.

Keep raw events separate from modeled metrics. The raw layer should preserve the received payload, schema version, and validation result. A curated layer can standardize locations, apply approved deduplication, and calculate visits or attribution. This separation makes dashboard audits and historical restatements easier to explain.

When to revisit

Revisit this taxonomy at least monthly or quarterly for active programs and whenever a recurring data point changes unexpectedly. A formal review is also warranted after a mobile SDK, geofencing API, QR endpoint, consent-management flow, warehouse model, or analytics tool is upgraded. Platform changes can alter field availability, event timing, permission handling, or delivery behavior even when campaign configuration remains unchanged.

Use this practical refresh sequence:

  1. List every current event and compare it with the canonical names in this model.
  2. Check required fields, null rates, consent tags, location mappings, and schema versions.
  3. Reconcile exposure, entry, dwell, exit, scan, redemption, and purchase totals across the SDK, ingestion layer, warehouse, and dashboard.
  4. Investigate discontinuities around releases, campaign changes, boundary edits, and reporting-time changes.
  5. Update the schema changelog, test fixtures, data dictionary, and dashboard definitions.
  6. Run a short parallel period when migrating, then document which historical metrics are comparable and which require restatement.

A consistent event taxonomy does not remove uncertainty from location analytics. It makes uncertainty visible and gives teams a common way to investigate it. That foundation supports more defensible store visit measurement, privacy-safe attribution, and comparable reporting across proximity marketing channels.

Related Topics

#analytics#event taxonomy#SDKs#data modeling#geofencing#measurement
N

NearI Labs

Editorial Team

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.