Saltar al contenido principal

GPS Check-Ins — Member View

A check-in records that a member is physically present at a location. The platform supports two flavours:

  1. GPS check-in — the member taps a button and their device sends its current GPS coordinates.
  2. QR check-in — the member scans a QR code printed at the location.

Both run through the same engine and progress the same loyalty mechanics (earn rules, stamp cards).

When to use it​

  • A retail loyalty program where visits matter as much as purchases.
  • A multi-location campaign (treasure hunt, store launch tour, festival check-in).
  • A geofence-gated bonus where being at the right place at the right time earns extra points.

How it works​

When a check-in arrives, the platform runs three checks:

  1. Earn rule lookup — does the active loyalty program have a rule for a check-in event? If so, the rule's reward (points, multiplier, condition) is applied.
  2. Stamp card progression — if the member is on a stamp card tied to this program, the check-in adds a stamp.
  3. Geofence verification (when configured) — see below.

If no earn rule is configured, the check-in still records (and stamp cards still progress) but no points are awarded. The response says "no points rule configured for this action" so the member isn't surprised.

Geofence and IP cross-check​

For campaigns that require physical presence in a specific region (typical for raffles regulated to one country), the platform validates two signals:

  1. Phone-prefix check. The contact's phone must start with one of the allowed country codes (default +34).
  2. IP cross-check. When a GeoIP database is configured, the request's IP must resolve to a country that matches the allowed list (and matches the phone's country). If GeoIP is unavailable, the check is skipped — a database outage never hard-fails a participant.

Members who fail the geofence get a friendly error message (configurable per flow). Members who pass are recorded with geo_outcome=passed and proceed.

What members see​

GPS check-in​

  1. Open the member portal.
  2. Tap Check in here.
  3. The browser asks for geolocation permission.
  4. The platform records the check-in and shows:
    • Points earned (if any).
    • New stamp count (if applicable).
    • Welcome message tailored to the location.

QR check-in​

  1. Tap Scan QR on the member portal home.
  2. Point the camera at the QR code (e.g. on a poster in the store).
  3. The member portal recognises the code and runs the same check-in flow.

Both paths use the same backend logic — the only difference is how the location is captured.

Step-by-step (admin setup)​

This section is for admins who want to enable check-ins.

Configure a check-in earn rule​

  1. Go to Loyalty → Earning rules and click Create rule.
  2. Set the event to CheckIn.
  3. Set the reward (points, multiplier, etc.).
  4. Optionally restrict by location code (the QR code's payload).
  5. Save.

For QR check-in, generate codes with the payload format checkin:{locationCode}. Print and place them at the location. Members scanning a QR will trigger the same CheckIn event with the matching location.

Add a geofence to a flow​

If you also want to gate access by country (typical for regulated raffles), add a verify_geofence action to your conversation flow before the check-in step. Configure the allowed country codes (e.g. +34 for Spain).

Limits and gotchas​

  • GPS precision varies. Indoor coordinates drift by 30 m or more. If you check distance against a specific point of interest, tune the radius accordingly.
  • The platform doesn't enforce GPS authenticity — a member running a location-spoofing app could lie. For trustworthy presence, combine GPS with QR (the QR must be present at the location).
  • Geofence is skipped if GeoIP db is missing. This is deliberate — a database file outage shouldn't break the campaign. The phone-prefix check still applies.
  • Stamp cards progress on every check-in as long as the member is on a card tied to the program — including duplicate check-ins on the same day if the program allows.
  • Member endpoint: POST /api/member/portal/checkin with { latitude, longitude }.