> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/events.md).

# Events

Reference of the wallet events The Wallet Crew sends to Bloomreach Engagement for customer segmentation, scenario automation and measurement.

The Wallet Crew sends wallet pass events through the brand's Bloomreach event API. Each event is associated with the customer through the pass's registered identifier or identifiers.

## Event list

Events are tracked in Bloomreach with the following event names:

| The Wallet Crew event | Bloomreach name      | When                                                             |
| --------------------- | -------------------- | ---------------------------------------------------------------- |
| `Pass:Created`        | `wallet_created`     | A wallet pass is created.                                        |
| `Pass:Installed`      | `wallet_installed`   | A pass is installed on a device.                                 |
| `Pass:Uninstalled`    | `wallet_uninstalled` | A pass is removed from the last device of a wallet (per wallet). |
| `Pass:Scanned`        | `wallet_scanned`     | A pass is scanned through the Scan API.                          |
| `Pass:LinkOpened`     | `wallet_linkOpened`  | A customer taps a tracked link in a pass.                        |

The following diagram shows the round trip between Bloomreach and The Wallet Crew.

```mermaid
sequenceDiagram
    participant B as Bloomreach scenario
    participant W as The Wallet Crew
    participant D as Customer device
    B->>W: Update pass or Notify (activity)
    W->>D: Pass update or wallet message
    D->>W: Install, uninstall, scan or link tap
    W->>B: Event (wallet_installed, ...)
    B->>B: Segment or trigger next step
```

## Event data model

Events are sent as flat key/value properties. Every event includes these base properties:

* `passType` (string): pass template identifier.
* `passId` (string): pass identifier.
* `passKind` (string): type of pass, such as `CustomerCard` or `EventTicket`.
* `identifier_<name>` (string): one property for each pass identifier.
* `metadata_<name>` (string): one property for each non-null pass metadata entry.

Dots in an identifier name become underscores. For example, `y2.customerId` becomes `identifier_y2_customerId`, and a `crm.customerId` identifier becomes `identifier_crm_customerId`.

Metadata properties with a `null` value are omitted.

## Event definitions

<details>

<summary><strong>Pass:Created</strong></summary>

Sent when The Wallet Crew creates a wallet pass. This event has no properties beyond the base set.

**Bloomreach event name:** `wallet_created`

</details>

<details>

<summary><strong>Pass:Installed</strong></summary>

Sent when a pass is installed on a device. It can fire multiple times for the same pass.

**Bloomreach event name:** `wallet_installed`

**Additional properties:**

* `device` (string): `Apple` or `Google`.
* `registrationInformation_totalRegistrationCount` (string): registrations ever recorded. It never decreases.
* `registrationInformation_activeRegistrationCount` (string): current registrations. `0` means the pass is no longer installed anywhere.
* `registrationSource_medium` (string): included when set.
* `registrationSource_origin` (string): included when set.
* `registrationSource_userAgent` (string): included when set.
* `registrationSource_tags` (string): comma-separated tags, included when set.

All `registrationSource_*` properties are absent when the registration has no source information.

</details>

<details>

<summary><strong>Pass:Uninstalled</strong></summary>

Sent when a pass is removed from the last device of a wallet, so it is per wallet. `registrationInformation_activeRegistrationCount` tells whether the pass is still installed on another device.

**Bloomreach event name:** `wallet_uninstalled`

**Additional properties:**

* `device` (string): `Apple` or `Google`.
* `registrationInformation_totalRegistrationCount` (string): registrations ever recorded. It never decreases.
* `registrationInformation_activeRegistrationCount` (string): current registrations. `0` means the pass is no longer installed anywhere.

</details>

<details>

<summary><strong>Pass:Scanned</strong></summary>

Sent when a pass is scanned.

{% hint style="info" %}
For this event to be triggered, the [Scan API](https://docs.thewalletcrew.io/developers-guides/integration-guides/scan-api.md) (Developers guide) must be invoked by the scanning system.
{% endhint %}

**Bloomreach event name:** `wallet_scanned`

**Additional properties:**

* `scannedData` (string): scanned value.
* `scannedType` (string): scanned type.

</details>

<details>

<summary><strong>Pass:LinkOpened</strong></summary>

Sent when a customer taps a tracked link embedded in a wallet pass.

**Bloomreach event name:** `wallet_linkOpened`

**Additional properties:**

* `link_targetUrl` (string): always included.
* `link_device` (string): `Apple` or `Google`, included when known.
* `link_origin` (string): included when known. This identifies the location in the pass the link was tapped from, such as `BackField`, `FeaturedAction` or `LinksModule`. The [origin reference](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/link-url-enrichment.md#handlers) lists every value and what it means on each wallet.
* `link_sourceId` (string): included when set. This identifies the individual link within that location, such as a field key or a message identifier.
* `link_language` (string): included when the link was tapped in localized text. This is the language the cardholder saw.
* `link_userAgent` (string): included when known.

[Measure link clicks in passes](https://docs.thewalletcrew.io/guides-monitoring/monitor/measure-link-clicks.md) explains what tracking does to the destination URL before the customer reaches it.

</details>

## FAQ

<details>

<summary><strong>Can the same event fire multiple times for the same pass?</strong></summary>

Yes. This is expected for installs (multiple devices, re-installs) and scans (multiple visits).

</details>

<details>

<summary><strong>How to avoid triggering scenarios twice on multiple installs?</strong></summary>

Scenarios can use deduplication rules based on `passId` and time windows. Another common approach stores “installed once” flags as customer attributes.

</details>

<details>

<summary><strong>Can events be used for segmentation and for scenario triggers?</strong></summary>

Yes. Once ingested, events can be used in Bloomreach the same way as other tracked events.

Events can be used to build segments based on recency and frequency. They can also be used as triggers to start or branch scenarios.

</details>

<details>

<summary><strong>Can events be renamed / filtered before ingestion?</strong></summary>

Yes. The connector can intercept events before sending them to Bloomreach.

This is used to rename event names, add or remove properties, or drop events entirely. Details: [Components and scripts](https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/extensibility.md).

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
