# Setup

Connect **Bloomreach Engagement** with **The Wallet Crew** to orchestrate wallet journeys. Bloomreach scenarios can trigger pass actions (create, update, notify). The Wallet Crew also sends events back to Bloomreach for segmentation and measurement.

A minimal end-to-end setup typically takes **1 to 2 hours**. This assumes access rights and a test pass are available to validate the flow.

## Prerequisites

Before starting, make sure you have:

* **Bloomreach permissions**
  * Access to **Project settings → Integrations**.
  * Access to API credentials under **Project settings → Access Management → API**.
* **The Wallet Crew permissions**
  * Access to the admin console to configure the Bloomreach connector.
  * Permission to create and manage API keys.
* **Environment and test data**
  * Target environment identified (staging vs production).
  * A test pass exists, with a known `passId`, to validate calls end-to-end.
  * Any required network allowlisting and security constraints are in place.

## The Wallet Crew configuration

{% stepper %}
{% step %}

#### Enable the connector

The Bloomreach connector must be enabled for the tenant. This is typically done by The Wallet Crew team.
{% endstep %}

{% step %}

#### Configure general settings

Open the Bloomreach connector settings in the Wallet Crew back-office.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/integrations/bloomreach/settings" class="button secondary" data-icon="chevrons-right">Open General settings page</a></p>

<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%2Feh8aPbK5B5yUmlsfpf0U%2Fimage.png?alt=media&#x26;token=b01c15dc-cb5f-478d-bab3-0b854ca4f539" alt="The Wallet Crew Bloomreach connector: general settings screen"><figcaption><p>General settings define how The Wallet Crew authenticates to Bloomreach.</p></figcaption></figure></div>

Fill in:

* `Project Token`
* `API Base Url`
* `API Key Id`
* `API Secret`

Bloomreach values are available under `Project settings` → `Access Management` → `API`.

{% hint style="info" %}
Project Token determines the target environment. This makes it possible to keep staging and production separated.
{% endhint %}

<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%2Fv6ujscaHT42a854x6bXf%2Fimage.png?alt=media&#x26;token=735eaeb9-8f42-4bcf-aec7-023e26acad69" alt="Bloomreach Engagement API credentials screen showing API keys and project token"><figcaption><p>Use a token and API key scoped to the correct Bloomreach environment.</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### Advanced settings (extensibility)

Advanced settings expose script entry points for the connector. These scripts control contact resolution, event transformation, and field mapping.

<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%2FCTh3F3F2UJ34fDZx6AL4%2Fimage.png?alt=media&#x26;token=eba6a0a0-5b96-4d84-ab17-0abf9677d361" alt="The Wallet Crew Bloomreach connector: advanced settings screen with script configuration blocks"><figcaption><p>Advanced settings are used for custom data models and governance.</p></figcaption></figure></div>

Details and script examples: [Extensibility](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/extensibility).
{% endstep %}
{% endstepper %}

## Bloomreach configuration

{% stepper %}
{% step %}

#### Set up an HTTP authentication schema

Bloomreach calls The Wallet Crew APIs using an API key. This is configured once as an HTTP authentication schema in Bloomreach.

In Bloomreach:

1. Go to `Data & Assets` → `Integrations` → `+ Add new integration`.

<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%2FBakz2SCLU9LEHDGiILNj%2Fimage.png?alt=media&#x26;token=964d28d5-4f35-4193-b5dd-4aedb7b35321" alt="Add new HTTP integration" width="375"><figcaption></figcaption></figure></div>

2. Select **Http Authentication Schemas**.

<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%2FTQxciFErmOIq1hfMOU5D%2Fimage.png?alt=media&#x26;token=2168a3fe-d3ed-4032-8525-6240991a59fc" alt="Http Authentication schemes configuration" width="375"><figcaption></figcaption></figure></div>

3. Configure the schema with an API key created in The Wallet Crew.

A The Wallet Crew API key with `tenant.pass:write` permission is required. API keys are managed in the Wallet Crew admin console.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/settings/security/apiKeys" class="button secondary" data-icon="chevrons-right">Open API Keys configuration</a></p>

Bloomreach schema values:

<table data-header-hidden data-full-width="true"><thead><tr><th width="141.88885498046875"></th><th></th></tr></thead><tbody><tr><td>Endpoint</td><td><code>https://app.neostore.cloud/api</code> (production) or <code>https://app-qa.neostore.cloud/api</code> (staging)</td></tr><tr><td>Type</td><td>Custom headers</td></tr><tr><td>Key</td><td><code>X-API-KEY</code></td></tr><tr><td>Value</td><td>The Wallet Crew API Key</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Install the WebHook preset activities

Bloomreach activities are installed as WebHook preset integrations. One Bloomreach integration is typically created per activity.

Only the needed activities should be installed. This keeps scenario building simple and reduces configuration drift.

{% hint style="info" %}
Activity icons are available as a file:

{% file src="<https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2Fwfi8BE4teckdrUb8xRPe%2Ftwc-bloomreach-icons.zip?alt=media&token=78174804-50f2-4db1-8cd8-e5fd972651dc>" %}
{% endhint %}

Payload examples use Bloomreach WebHook preset parameter syntax.

<details>

<summary><strong>Update pass ("Push Update")</strong></summary>

Endpoint URL:

```
PATCH https://app.neostore.cloud/api/<<tenantId>>/passes/?id=[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target', isJsonParam: true} : string]]
```

Minimum payload (options only):

```json
{
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

Example payload to update `additionalData`:

```json
{
  "additionalData": {
    "xx": "[[ {name: 'xx', tooltip: 'xx', category: 'Content', orderIndex: 10, isJsonParam: true} : string]]",
    "xy": "[[ {name: 'xy', tooltip: 'xy', category: 'Content', orderIndex: 11, isJsonParam: true} : string]]"
  },
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

Example payload to change the pass template (`passType`):

```json
{
  "passType": "newTemplate",
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

API reference: [API reference](https://docs.thewalletcrew.io/develop/api-reference).

</details>

<details>

<summary><strong>Notify</strong></summary>

Endpoint URL:

```
PUT https://app.neostore.cloud/api/<<tenantId>>/passes/notification?id=[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target', isJsonParam: true} : string]]
```

Example payload (single language):

```json
{
  "content": "[[ {name: 'Notification Content', tooltip: 'Content of the notification', category: 'Content', orderIndex: 10, isJsonParam: true} : string]]",
  "options": {
    "updateData": [[ {name: 'Update data', tooltip: 'Also update pass data when notification is sent', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : boolean | false]],
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

Example payload (localized):

```json
{
  "localizedContent": {
    "en": "[[ {name: 'Notification Content (en)', tooltip: 'Content of the notification', category: 'Content', orderIndex: 10, isJsonParam: true} : string]]",
    "fr": "[[ {name: 'Notification Content (fr)', tooltip: 'Content of the notification', category: 'Content', orderIndex: 11, isJsonParam: true} : string]]"
  },
  "options": {
    "updateData": [[ {name: 'Update data', tooltip: 'Also update pass data when notification is sent', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : boolean | false]],
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

API reference: [API reference](https://docs.thewalletcrew.io/develop/api-reference).

</details>

<details>

<summary><strong>Apply privilege</strong></summary>

Endpoint URL:

```
POST https://app.neostore.cloud/api/<<tenantId>>/passes/[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target', isJsonParam: true} : string]]/privileges
```

Payload example (unlocalized privilege):

```json
{
  "type": "multiUse",
  "origin": {
    "generator": "bloomreach",
    "processId": "[[ {name: 'Process identifier', tooltip: 'Identifier of the scenario / campaign', category: 'Advanced configuration', orderIndex: 120, isJsonParam: true} : string]]"
  },
  "priority": [[ {name: 'Priority', tooltip: 'High values mean stronger priority', category: 'Advanced configuration', orderIndex: 110, isJsonParam: true} : number]],
  "content": {
    "title": {
      "value": "[[ {name: 'Title', tooltip: 'Title of this privilege', category: 'Content', orderIndex: 10, isJsonParam: true} : string]]"
    },
    "description": {
      "value": "[[ {name: 'Description', tooltip: 'Description of this privilege', category: 'Content', orderIndex: 20, isJsonParam: true} : string]]"
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": "[[ {name: 'Main Image', tooltip: 'Url of the main image', category: 'Content', orderIndex: 30, isJsonParam: true} : image]]"
    }
  },
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 130, isJsonParam: true} : string]]"
  }
}
```

API reference: [API reference](https://docs.thewalletcrew.io/develop/api-reference).

</details>

{% hint style="danger" %}
Endpoints include `<tenantId>`. Replace it with the tenant identifier of The Wallet Crew.
{% endhint %}

To know more about activities : [Bloomreach activities](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/bloomreach-activities).
{% endstep %}
{% endstepper %}

## Validation checklist

A minimal validation run usually covers:

* One test pass exists and its `passId` is available in Bloomreach.
* One Update pass activity refreshes visible content on the pass.
* One Notify activity delivers a message.
* One test install/uninstall produces Bloomreach events.

Event names and properties: [Events](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach/events).

## Best practices

* **Staging first**: validate activities and events in a test Bloomreach project token.
* **Progressive rollout**: install only Notify first, then add Apply privilege.
* **Multi-team setup**: IT configures credentials and allowlists, marketing installs the scenario activities.

## FAQ

<details>

<summary><strong>Who typically owns Setup?</strong></summary>

Connector enablement and credentials are typically owned by IT or an implementation partner. Activity installation and scenario usage are often owned by CRM or marketing operations.

</details>

<details>

<summary><strong>Which environment should be set up first?</strong></summary>

A staging environment is usually set up first. This makes it possible to validate activities, events, and scripts before production.

</details>

<details>

<summary><strong>Which permissions are required for the API key used by Bloomreach?</strong></summary>

A key with `tenant.pass:write` permission is required for activities that update passes. Additional permissions can be required depending on the activity set.

</details>