Location & Store Marketing
Tie engagement to the physical store — measure real, member-keyed store visits, target by store or region, and (on the roadmap) re-engage members who came near a store. Built privacy-first: consent + Global Privacy Control, fail-closed, no raw coordinates stored.
Read the badges precisely: deterministic store visits are live; the geofence endpoints are server-built and callable; the on-device detection that completes the proximity audience is in development.
What's live, what's coming
Deterministic store visitLive
A QR check-in or in-store redeem fires a member-keyed, DB-deduplicated store-visit event. No device location needed. With a randomized holdout, you measure true incremental lift.
Store / region targetingLive
Target members by their attributed store or region for location-relevant offers — first-party, no device tracking. (Region segment rolling out.)
Geofence endpoints + triggersServer built
nearby-stores + geofence-event are live and callable, with consent + GPC fail-closed and near_store / store_dwell automation triggers wired in.
On-device proximity detectionIn development
Background geofencing inside the FlashLocation package (CoreLocation / Play Services). In active development and not yet device-validated — so the end-to-end “near a store recently” audience is not yet live.
Start here: deterministic store visits Live
// LIVE TODAY — no device location required. A QR check-in or an in-store coupon
// redeem fires a member-keyed store-visit event, deduplicated at the database.
// This is the cleaner, privacy-safe signal for store-driven campaigns, and the one
// to build on now while the on-device proximity detection is finished.
//
// QR check-in / in-store redeem → store_visit_event (member-keyed, DB-deduped)
//
// Pair it with a randomized holdout to measure INCREMENTAL visits your campaign
// actually caused — not self-reported footfall.Geofence endpoints Server built
These are live and callable from a signed-in member session today. The on-device piece that calls them — background geofence monitoring — ships with the FlashLocation package, which is still in development; until then the end-to-end proximity audience is not live.
1. Get the nearest store geofences to monitor
// The device reports its current location; the server returns the ≤20 NEAREST store
// geofences for it to monitor (server-curated to fit iOS's 20-region limit). The
// lat/lng is used transiently to rank stores and is NOT persisted.
POST https://flash.socialhub.ai/api/v2/lbs/nearby-stores
Content-Type: application/json
{ "lat": 40.71, "lng": -74.00, "limit": 20 }
// → 200 { "geofences": [
// { "storeId": "…", "name": "…", "lat": …, "lng": …, "distanceMeters": … }
// ] }
//
// FAIL-CLOSED: no precise_location_consent, or a Global Privacy Control signal
// present → { "geofences": [] } (empty set, no error).2. Report a geofence transition
// When the device crosses a monitored geofence, report the transition. This fires
// the near_store / store_dwell automation triggers server-side.
POST https://flash.socialhub.ai/api/v2/lbs/geofence-event
Content-Type: application/json
{ "storeId": "<uuid>", "eventType": "enter" } // "enter" | "dwell"
// → 200 { "recorded": true }
//
// FAIL-CLOSED privacy gate:
// GPC signal present → { "recorded": false, "reason": "gpc" }
// no precise_location_consent → { "recorded": false, "reason": "no_consent" }
// Only the derived enter/dwell event is recorded — never the device's coordinates.Privacy by construction
Precise location is gated by explicit precise_location_consent AND the absence of a Global Privacy Control signal — both checked, fail-closed.
Only derived enter / dwell events are stored. Raw device coordinates are never persisted; the lat/lng you send to nearby-stores is used transiently to rank stores and discarded.
Consent is withdrawable one-tap with no penalty; withdrawal takes effect immediately on the next call.
Planning store-driven campaigns?
Talk to an engineer about deterministic store visits, holdout lift, store/region targeting, or the geofence roadmap.
Talk to engineering