Designing a Proximity Marketing SDK: Events, Permissions, and Backend Data Models
SDKsAPIsmobile developmentevent schemasgeofencingbeaconspermissions

Designing a Proximity Marketing SDK: Events, Permissions, and Backend Data Models

NNearI Labs Editorial Team
2026-11-15
7 min read

Design a reliable proximity marketing SDK with practical event schemas, permission states, offline queues, estimates, and release checks.

A reliable proximity marketing SDK is less about collecting every possible signal than defining a small, explainable event system that respects permissions, survives intermittent connectivity, and produces data a backend can measure. This guide presents a reference architecture for geofences, beacons, QR codes, and consent, with a repeatable method for estimating event volume, storage needs, implementation effort, and release risk.

Overview

A proximity marketing SDK typically sits between mobile operating-system capabilities and a company’s analytics, campaign, or customer-data systems. Its responsibilities should be deliberately separated:

  • Signal collection: Receive supported events from geofences, beacons, QR codes, NFC, or app interactions.
  • Permission interpretation: Report whether a signal is allowed, denied, restricted, not requested, or temporarily unavailable.
  • Event normalization: Convert platform-specific callbacks into a stable application schema.
  • Queueing and delivery: Store events briefly when the network is unavailable and retry safely.
  • Privacy controls: Apply consent, data minimization, retention, and deletion rules before transmission.
  • Measurement: Expose identifiers and timestamps that support campaign reporting without treating an observation as proof of a visit or conversion.

The SDK should not decide campaign strategy or make unsupported claims about a person’s intent. It should expose well-documented observations and their quality. For example, a geofence transition, a beacon detection, and a QR scan are different signals and should remain distinguishable in analytics.

For measurement context, compare the SDK design with this comparison of proximity marketing channels and define downstream visit rules with a store visit measurement framework.

How to estimate

Before choosing a database or setting a delivery limit, estimate the SDK’s workload with simple, reviewable inputs. The goal is not to predict every event perfectly. It is to create a baseline that engineering and marketing teams can adjust.

Use this monthly event estimate:

Monthly events = active devices × eligible events per device per day × active days × delivery multiplier

The delivery multiplier accounts for retries, duplicate callbacks, app reinstalls, and other operational overhead. Keep it as an explicit assumption rather than hiding it in a vendor estimate.

Then estimate stored data:

Monthly raw storage = monthly events × average serialized event size

Add room for indexes, processing copies, logs, and backups separately. A compact event payload may be inexpensive to store, while detailed diagnostic logs can become the larger cost driver.

For implementation effort, estimate each signal independently. A QR event may require a small parser and attribution handoff. Background geofencing can require more platform testing, permission-state handling, lifecycle work, and operational monitoring. Beacon marketing may add ranging or proximity interpretation, hardware configuration, and site-level calibration. Do not combine all signals into one generic “location integration” estimate.

SignalCore eventImportant metadataCommon estimation variable
GeofenceEntered, exited, or observed transitionRegion identifier, transition time, permission state, accuracy or confidence where availableEligible regions per device and transition frequency
BeaconDetected or proximity observationBeacon namespace or approved identifier, site, observation time, signal quality where availableScan cadence and dwell deduplication window
QR codeScan or resolved destinationCode identifier, campaign, source, scan time, consent statusScans per campaign and retry rate
ConsentGranted, denied, withdrawn, or changedPurpose, policy version, capture time, jurisdictional context if neededPermission prompts, settings changes, and app lifecycle events

Inputs and assumptions

Use a stable event envelope

A common envelope makes downstream processing easier while preserving signal-specific fields:

{
  "event_id": "client-generated-unique-id",
  "event_type": "geofence.transition",
  "schema_version": 1,
  "occurred_at": "2026-01-15T10:30:00Z",
  "received_at": "2026-01-15T10:30:08Z",
  "installation_id": "rotating-or-scoped-id",
  "campaign_id": "optional-campaign-reference",
  "consent": {
    "purpose": "proximity_measurement",
    "status": "granted",
    "policy_version": "current-policy-reference"
  },
  "properties": {
    "region_id": "store-042",
    "transition": "enter"
  }
}

Use occurred_at for the device observation and received_at for backend arrival. This distinction is essential when events are queued offline. Include a schema version from the first release, and prefer additive changes over silently renaming or reinterpreting fields.

Operating-system permission and marketing consent are related but not interchangeable. A user may grant device access while declining a marketing purpose, or consent to a purpose while the required device capability is unavailable. Store both dimensions:

  • Capability state: unknown, not requested, authorized, denied, restricted, or unavailable.
  • Purpose state: unknown, granted, denied, withdrawn, or expired under the applicable policy.

Keep permission prompts in the application layer where the user experience can be explained. The SDK should expose current state, return clear error codes, and avoid repeatedly prompting. Recheck state when the app resumes because users can change settings outside the app.

Queue, retry, and deduplicate

Use a bounded local queue with encryption appropriate to the platform and data sensitivity. Each event needs a stable client-generated event_id. The backend should accept idempotent writes so a retry does not create a second conversion or visit signal.

Deduplication should be signal-specific. For example, repeated callbacks for the same geofence can share a region, transition, and time-window key; repeated beacon observations can be collapsed into a defined observation window; QR scans should generally remain distinct unless the product explicitly defines a repeat-scan rule. Document the window and apply it consistently in both mobile and backend processing.

Worked examples

Example 1: estimating event volume

Assume an app has 20,000 active devices, an average of 0.4 eligible proximity events per device per day, and 30 active days. The baseline is:

20,000 × 0.4 × 30 = 240,000 events per month.

If the team applies a planning multiplier of 1.25 for retries and duplicate callbacks, the working estimate becomes 300,000 events per month. If the average serialized event is assumed to be 1.5 KB, raw payload volume is approximately 450 MB per month, before indexes, backups, processing tables, and logs. These are planning assumptions, not universal benchmarks; replace them with observed data after a controlled release.

Example 2: comparing signal designs

Suppose a retailer wants geofences for store visit measurement, beacons for an in-store interaction, and QR codes on printed materials. A practical first release might expose three separate event types rather than one “proximity event.” This allows analysts to distinguish a geofence transition from a beacon observation and a deliberate QR scan.

The release can share one envelope, consent model, queue, and delivery endpoint. It should still retain signal-specific validation and deduplication. This reduces duplicated infrastructure without erasing the differences that matter for attribution. For campaign design and calibration, see the geofence launch and measurement playbook.

Example 3: estimating a new integration

Break the work into discovery, platform implementation, schema and backend work, permission and consent testing, offline behavior, observability, and release validation. Mark each item as required for the first release or deferred. A QR integration may prioritize parser validation and campaign attribution, while geofencing may prioritize lifecycle tests and background delivery diagnostics. This approach produces a more useful estimate than assigning one fixed effort to the entire SDK.

When to recalculate

Revisit the model whenever a mobile operating-system release, SDK dependency update, permission-flow change, signal provider change, or analytics migration could affect event delivery. Background execution behavior and permission interfaces can change, so test the supported operating-system and SDK matrix before publishing a new app version. Avoid assuming that a successful foreground test proves reliable background behavior.

Recalculate event and storage estimates after a staged rollout, when active-device volume changes, when a new region or beacon fleet is added, or when duplicate and retry rates differ from the planning multiplier. Review schema guidance at least annually, and sooner after a material privacy, security, or platform change.

Use this release-readiness checklist:

  1. Every event has a documented type, schema version, timestamp convention, and unique identifier.
  2. Geofence, beacon, QR, and consent events remain distinguishable downstream.
  3. Device permission and purpose-specific consent are represented separately.
  4. Events are minimized, encrypted in transit, retained for a documented period, and removable when required.
  5. Offline queues are bounded, observable, and safe to retry.
  6. Backend ingestion is idempotent and validates schema versions.
  7. Deduplication rules are written for each signal rather than applied globally.
  8. Tests cover denied permissions, changed settings, revoked consent, no connectivity, clock differences, app restarts, and duplicate callbacks.
  9. Dashboards distinguish received events from modeled visits, conversions, or attributed outcomes.
  10. Documentation records supported platform versions and the date of the last compatibility review.

For troubleshooting permission and delivery failures, use the geofencing API troubleshooting guide. A measured, versioned event model gives marketing teams useful proximity marketing data without turning uncertain device signals into overconfident identity or attribution claims.

Related Topics

#SDKs#APIs#mobile development#event schemas#geofencing#beacons#permissions
N

NearI Labs Editorial Team

Editorial and Developer Experience

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.