# Geolocated Notifications

Geolocated notifications show a contextual message near a location. Apple Wallet or Google Wallet can surface it when a customer is nearby. Use it for reminders (“don’t forget your card”) and on-site information (“gate changed”).

<figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2FMiLr7PXaIn4oLiwNm781%2Fimage.png?alt=media&#x26;token=5b78349a-18e8-4e7e-8ccd-9620290d4e65" alt=""><figcaption></figcaption></figure>

This works for **stores and any venue**. Typical venue examples are stadiums, concert halls, theaters, and pop-ups.

<details>

<summary><strong>Real-world examples</strong></summary>

* Remind loyalty members to scan their card at checkout.
* Display a voucher reminder only if a voucher is available.
* Announce a store opening to customers near that location.
* Remind ticket holders of gate/door info when approaching the venue.
* Surface a “your ticket is ready” message near the venue entrance.

</details>

{% hint style="info" %}
Geolocated notifications appear only if the customer enables location features for their wallet app.

On iOS: **Settings → Privacy & Security → Location Services → Wallet**.

On Android: check Google Wallet permissions in your device **Settings** (location must be allowed).
{% endhint %}

## How it works

Wallet passes can store a small set of “relevance” locations. The phone compares the device position to those locations. When the customer enters the configured radius, the wallet app can surface the pass and its message.

The Wallet Crew configures these locations on the pass based on your location dataset. Most brands use store addresses. For venues, you usually model the venue as a “store” record so it can be geolocated the same way.

### What customers will see (varies by platform)

{% tabs %}
{% tab title="Apple Wallet (iOS)" %}
iOS can surface a lock screen suggestion when the customer is near one of the configured locations. The suggestion can include the message you configured.
{% endtab %}

{% tab title="Google Wallet (Android)" %}
Android can surface a “nearby pass” experience when the customer is near one of the configured locations. The exact UI depends on Android version and device manufacturer.
{% endtab %}
{% endtabs %}

### Limits you should design for

These platform limits apply:

* Up to **10 GPS coordinates** per pass.
* Up to **300 m radius** per coordinate.

Message visibility is controlled by the OS. In practice, the message can remain visible while the customer stays in the area.

### Geolocation vs “push notifications”

Geolocated notifications are not “sent” at a specific time by The Wallet Crew. They are triggered by the customer’s phone when it detects proximity.

If you need a server-triggered message, use standard wallet notifications instead. Start with [Push notifications](https://docs.thewalletcrew.io/engage-and-animate/push-notification).

## Prerequisites

You must configure locations (addresses) in The Wallet Crew. The platform uses those addresses to compute GPS coordinates.

Locations are managed through the **Stores** dataset. You can use it for retail stores and for venues. Example: create a store entry for `Stadium - Gate A` or `Concert hall - Main entrance`.

If you have not set up locations yet, start with [Stores](https://docs.thewalletcrew.io/enroll/enrolment-form/stores).

<div data-with-frame="true"><figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2Fgit-blob-a9d0ebfebdfac9a3abc4f5b263071d9f1ec3cba6%2Fgeolocated_notifications_1.png?alt=media" alt="The Wallet Crew back office showing store and address configuration"><figcaption><p>Addresses are used to compute GPS coordinates (stores or venues).</p></figcaption></figure></div>

## Set up the message in The Wallet Crew

Configure the message directly on the pass template. Use Liquid if you need personalization.

{% stepper %}
{% step %}

#### Open the notification settings on a template

Go to **Templates**. Open the template **More options** menu, then select **Notifications**.
{% endstep %}

{% step %}

#### Write the message (Geo notification tab)

Open the **Geo notification** tab. Write your message. Add Liquid variables if needed.

Keep it short. Aim for **≤ 140 characters** to avoid truncation.
{% endstep %}

{% step %}

#### Configure translations (optional)

If your template is translated, update the geo notification message for each language.
{% endstep %}

{% step %}

#### Save and test

Click **Send notification** to save. Then test with a device near a configured location.

Validate both the location behavior and the Liquid rendering.
{% endstep %}
{% endstepper %}

<div data-with-frame="true"><figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2Fgit-blob-8f13190d544134531d045b124aa0372a2c895d49%2Fgeolocated_notifications_2.png?alt=media" alt="Notification configuration screen showing the Geo notification tab"><figcaption><p>Geo notification messages are configured per template and can be translated.</p></figcaption></figure></div>

## How The Wallet Crew selects locations per customer

The location selection logic depends on your use case. Loyalty programs typically rely on “home store” logic. Event tickets typically rely on the venue location you assign to the pass.

For a retail-style setup, geolocated notifications are commonly computed for:

* The customer’s **home store**.
* The **9 closest locations** to that home store (or to the customer address).

This keeps the pass within the 10-location limit while covering nearby locations.

## Automatic updates of location coordinates

When you perform a pass update via The Wallet Crew, location coordinates can be recalculated:

* If the customer’s home store changes, the “closest locations” list is recalculated.
* If the customer address changes, the “closest locations” list is recalculated.
* If you add new stores (with an address), they can become eligible as “closest locations”.

This keeps location triggers aligned with your latest location data.

## Liquid examples for geo notification messages

Use Liquid to show a message only to relevant customers. Typical inputs are store identifiers, customer profile data, and voucher availability.

{% code title="Example 1 — show a voucher reminder only if a voucher exists" %}

```liquid
{%- if y2.bons.loyaltyCertificates.size > 0 -%}
Your €20 loyalty voucher is available. Use it in store today.
{%- else -%}
Don’t forget to scan your loyalty card at checkout.
{%- endif -%}
```

{% endcode %}

{% code title="Example 2 — store-specific message" %}

```liquid
{%- if storeId == "013" -%}
This store is permanently closed. Visit our other nearby stores.
{%- else -%}
Welcome back. Your store is nearby. Come discover our latest arrivals.
{%- endif -%}
```

{% endcode %}

## FAQ

<details>

<summary><strong>Can we track how many customers received the geolocated message?</strong></summary>

No. This is not a message that The Wallet Crew actively sends at a given time. The customer’s phone triggers it locally when it gets near the configured coordinates.

</details>

<details>

<summary><strong>Do we know if the customer is inside the store or venue?</strong></summary>

No. Geolocation triggers do not send “entered” or “in-store” events back to The Wallet Crew.

</details>

<details>

<summary><strong>Why didn’t the geo notification show up on an iPhone?</strong></summary>

Start with iOS settings. The customer must enable location access for Wallet in **Settings → Privacy & Security → Location Services → Wallet**.

Then validate the pass data. The pass must include location coordinates. The customer must be close enough to the configured radius.

</details>

<details>

<summary><strong>Why didn’t the geo notification show up on Android (Google Wallet)?</strong></summary>

Start with Android settings. The user must allow location features for Google Wallet (and not restrict it via system privacy settings).

Then validate the pass data. The pass must include locations, and the customer must be close enough to trigger them.

</details>

<details>

<summary><strong>What is the delay between two geolocated notifications?</strong></summary>

The OS typically surfaces the message when the customer enters the configured area. It can disappear when they leave. It can reappear the next time they enter.

Apple’s reference: [Showing a pass on the lock screen](https://developer.apple.com/documentation/walletpasses/showing-a-pass-on-the-lock-screen).

</details>

<details>

<summary><strong>How are the 10 locations selected for one customer?</strong></summary>

Each customer has a home store. The Wallet Crew selects the 9 closest locations to that home store, for a total of 10.

</details>

<details>

<summary><strong>Is this the same as beacon-based notifications?</strong></summary>

No. Beacons use Bluetooth (iBeacon identifiers). Geolocated notifications use GPS coordinates.

Apple Wallet also supports beacon triggers. If you plan to use them, confirm your target devices and store hardware constraints first.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thewalletcrew.io/engage-and-animate/geolocated-notifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.