# Recipes

This page collects practical recipes to leverage the integration between **Bloomreach Engagement** and **The Wallet Crew**.

These recipes complement the reference documentation:

* [Setup](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/setup)
* [Bloomreach activities](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/bloomreach-activities)
* [Events](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/events)
* [The Wallet Crew components](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/the-wallet-crew-components)

### How to use these recipes

Bloomreach scenarios define targeting, timing, and personalization. The Wallet Crew executes wallet actions such as pass refresh, benefit attachment, and wallet notifications.

The Bloomreach integrator (IT team or implementation partner) typically decides which activities to include and how to map data. [Setup](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/setup) covers the required configuration and data mapping concepts.

Most teams validate one recipe end-to-end in staging first. Recipes are then combined into multi-step scenarios.

## Recipes

### Send a wallet push notification (Notify activity)

Notify sends a wallet message to a pass. Apple Wallet can deliver a lock-screen notification. Google Wallet displays the message on the pass.

{% hint style="info" %}
**Example:**

When an order is delivered, a notification confirms that shipment is under way.
{% endhint %}

**How it is typically implemented**

* Use the **Notify** activity in the scenario. Reference scenario attributes to build a personalized message.
* If the message references updated pass content, run **Update pass** first, then **Notify**.
* Use segmentation and frequency caps. Wallet messages feel system-level and can be perceived as intrusive when overused.

{% stepper %}
{% step %}

#### Define the trigger and the pass target

Start by selecting the scenario entry condition. Most setups rely on an order event, a segment entry, or a time-based rule, depending on when the pass update should happen.

Then confirm the scenario context includes a stable pass identifier. This keeps targeting consistent across updates and devices. In most Bloomreach implementations, this identifier is stored as a customer property such as `passId`.
{% endstep %}

{% step %}

#### Add the Notify activity

In Bloomreach, add the **Notify** activity from The Wallet Crew activity catalog. Set the notification content, then personalize it with scenario attributes (for example customer name or order number). When the message references pass content, make sure the values are already up to date.
{% endstep %}

{% step %}

#### Guard against non-installed passes

Wallet messages require at least one active installation. Add a guard so Notify runs only when installation is confirmed.

Common guard patterns:

* Trigger Notify only after `wallet_installed`.
* Add a branch that checks installation flags stored in Bloomreach.

If no active installation exists, use a fallback channel (email/SMS) to distribute an “Add to Wallet” link.
{% endstep %}

{% step %}

#### Validate delivery on real devices

Validation should cover iOS and Android. It should also cover both logging and on-device behavior.

Check both:

* Bloomreach activity logs.
* On-device behavior (notification visibility and message rendering).

When the message refers to updated fields, validate the update first.
{% endstep %}
{% endstepper %}

Related reference: [Bloomreach activities](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/bloomreach-activities).

### Grant a benefit and reflect it on the pass (Apply privilege activity)

Apply privilege attaches a benefit to a pass. A privilege can be a coupon, an access right, or a perk with an expiry and redemption lifecycle.

{% hint style="info" %}
**Example:**

A “VIP Weekend” privilege is granted to a segment. The pass displays the perk and can switch to a “VIP” styling while the privilege is active.
{% endhint %}

**How it is typically implemented**

* Use **Apply privilege** to attach the benefit to the pass.
* Configure the pass template to display privileges and, when relevant, change styling based on active privileges.
* Optionally follow with **Notify** to announce the benefit.

{% stepper %}
{% step %}

#### Create the privilege model in The Wallet Crew

Start by defining the privilege type and its lifecycle. Then confirm the pass template can display privileges, either as a list or as dedicated fields.
{% endstep %}

{% step %}

#### Create the Bloomreach scenario

Select a trigger that represents eligibility. Typical options include segment entry, tier change, or a purchase milestone.
{% endstep %}

{% step %}

#### Apply the privilege

Add **Apply privilege**, then define both the content and the lifecycle rules.

* title and description
* validity and expiry (when relevant)
* priority (when multiple benefits can overlap)

For audit and idempotency, use a deterministic `processId` (or another correlation identifier) that stays stable across retries.
{% endstep %}

{% step %}

#### Refresh and announce (optional)

If the pass template renders privilege data from the pass payload, add **Update pass** next. If the benefit needs attention, follow with **Notify**. Order is usually update first, then notify.
{% endstep %}

{% step %}

#### Validate in staging

Validation should cover creation, rendering, and lifecycle behavior.

* The privilege exists in The Wallet Crew.
* The pass reflects it (fields and visuals).
* The redemption lifecycle behaves as expected.
  {% endstep %}
  {% endstepper %}

Related reference: [Privilege](https://docs.thewalletcrew.io/engage-and-animate/privilege-and-activation/privilege).

### Branch scenarios based on pass lifecycle (The Wallet Crew → Bloomreach events)

The Wallet Crew forwards wallet events to Bloomreach. These events make wallet measurable and triggerable as a CRM touchpoint.

{% hint style="info" %}
**Example:**

After pass creation, a scenario waits for `wallet_installed`. If install does not happen within a time window, a reminder email is triggered instead.
{% endhint %}

**Common scenario patterns**

* **Welcome only after install**: start an onboarding series only after `wallet_installed`.
* **Suppress wallet notifications**: do not run Notify when no active installation exists.
* **Churn signals**: trigger a reactivation flow after `wallet_uninstalled`.
* **Post-visit triggers**: trigger a follow-up after `wallet_scanned` (when Scan API is connected).

{% stepper %}
{% step %}

#### Confirm event forwarding

`wallet_created`, `wallet_installed`, `wallet_uninstalled`, and `wallet_scanned` must be visible in Bloomreach. This depends on connector configuration.

Validation steps are in [Setup](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/setup).
{% endstep %}

{% step %}

#### Start a scenario on a wallet event

Create a scenario triggered by a wallet event. Use `wallet_installed` for install-confirmed flows. Use `wallet_uninstalled` for suppression and win-back flows.
{% endstep %}

{% step %}

#### Add deduplication and time windows

Treat events as “at least once” and plan for duplicates.

Common safeguards:

* Store a `firstWalletInstalledAt` attribute.
* Use time windows (example: ignore repeated installs within 24h).
  {% endstep %}

{% step %}

#### Use the event properties for segmentation

Use `device`, `registrationSource_medium`, and `registrationSource_tags` to segment adoption and measure channel performance.

Keep governance in mind when passing identifiers through events.
{% endstep %}
{% endstepper %}

Related reference: [Events](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/events).

### Create or update a Bloomreach contact from The Wallet Crew enrolment form (CustomerFlowElement)

CustomerFlowElement connects The Wallet Crew form submissions to Bloomreach. It creates or updates a Bloomreach contact when a customer completes an enrolment flow.

{% hint style="info" %}
**Example:**

After a pass is installed, an enrolment form collects consent and profile data. The submission creates or updates the Bloomreach contact, then a Bloomreach onboarding scenario starts.
{% endhint %}

**How it is typically implemented**

* Enable **CustomerFlowElement** in the wallet flow used for enrolment.
* Map form fields to Bloomreach contact attributes.
* Define matching rules (email, phone, member ID, etc.) so contacts are resolved deterministically.

{% stepper %}
{% step %}

#### Decide the contact resolution strategy

Start by choosing which Bloomreach identifier is used for contact matching. Email is common because it is widely available in CRM data models. When a program has a stable member identifier, that identifier is often a better match key because it avoids issues with email changes.
{% endstep %}

{% step %}

#### Configure the enrolment form flow

Add **CustomerFlowElement** to the enrolment flow, then map form fields to Bloomreach contact properties. When consent is required by governance, make sure consent fields are collected and mapped as well.
{% endstep %}

{% step %}

#### Test a real submission

Run a real submission with a staging pass. Then confirm the contact is created or updated in Bloomreach, and that the identifiers used for matching remain consistent across subsequent submissions.
{% endstep %}

{% step %}

#### Start downstream scenarios

Trigger downstream scenarios after the contact upsert. A common pattern starts only after `wallet_installed`, then uses the form submission as the profile completion step.
{% endstep %}
{% endstepper %}

Related reference: [The Wallet Crew components](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/the-wallet-crew-components).

### Display Bloomreach data on the pass (PassDataProvider + Update pass)

PassDataProvider fetches customer attributes from Bloomreach and exposes them to pass rendering. This makes Bloomreach a data source for values displayed on Apple Wallet and Google Wallet passes.

{% hint style="info" %}
**Example:**

When a tier attribute changes in Bloomreach, a scenario runs **Update pass** so the pass immediately displays the new tier.
{% endhint %}

**Key operational note**

Bloomreach data appears on the pass after a refresh. A refresh can be triggered by **Update pass** in a scenario.

**Tutorial (Bloomreach as a pass data source)**

{% stepper %}
{% step %}

#### Identify the fields owned by Bloomreach

Start with stable profile fields owned by Bloomreach, such as tier label, points, preferred store, or personalization attributes. Keep transactional values in their system of record when accuracy or audit constraints apply.
{% endstep %}

{% step %}

#### Configure PassDataProvider

Enable PassDataProvider for the project, then confirm which Bloomreach properties are fetched. Naming conventions and mapping rules should be validated early to avoid field drift across environments.
{% endstep %}

{% step %}

#### Render the attributes in the pass template

Reference the PassDataProvider-exposed values in the template fields. Then validate the rendered values on a staging pass, including empty values and edge cases.
{% endstep %}

{% step %}

#### Trigger refreshes from Bloomreach

Create a scenario triggered by profile changes and add **Update pass**. When the change is time-sensitive, follow with **Notify** so it is visible without opening the pass.
{% endstep %}
{% endstepper %}

Related reference: [The Wallet Crew components](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/the-wallet-crew-components).

### Combining recipes into multi-step campaigns

These recipes are designed as building blocks. In practice, scenarios often chain pass creation, pass refresh, benefit attachment, and messaging.

Common chains:

* Update pass → Notify
* `wallet_installed` → onboarding series
* Enrolment form submission → contact upsert → tier-based benefits

## FAQ

<details>

<summary><strong>What’s the difference between Update pass and Notify?</strong></summary>

Update pass changes what is displayed on the pass. Notify brings attention through a wallet message.

When the message refers to updated content, the common pattern runs Update pass first, then Notify.

</details>

<details>

<summary><strong>What happens if a Notify or Update pass runs on a pass that is not installed?</strong></summary>

The activity still targets a pass record, but there is no active device installation to push to. Notify cannot be delivered without an active installation.

A common fallback uses email to distribute an “Add to Wallet” link, then resumes wallet actions after `wallet_installed`.

</details>

<details>

<summary><strong>How to test Notify without disturbing real users?</strong></summary>

Most teams isolate staging at both levels.

A staging Bloomreach project token is used with a staging The Wallet Crew tenant.

Tests are run with a small set of test passes installed on internal devices.

</details>

<details>

<summary><strong>How to prevent Notify if the pass is not installed?</strong></summary>

Use install status as a guard.

Common patterns are triggering Notify only after `wallet_installed`, or maintaining an “isInstalled” attribute in Bloomreach.

When the guard fails, use an email/SMS fallback to distribute an “Add to Wallet” link.

</details>

<details>

<summary><strong>Can the same install or scan event happen multiple times?</strong></summary>

Yes. Installs can repeat (re-install, multiple devices). Scans can repeat (multiple visits).

Scenario logic often uses deduplication rules based on `passId` and time windows.

</details>

<details>

<summary><strong>Can Bloomreach be the source of truth for pass fields?</strong></summary>

Yes, when PassDataProvider is used to fetch profile attributes. Transactional values (orders, redemptions, balances) often remain owned by other systems.

</details>