> 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/ticketing/aparte/distribution.md).

# Distribution

### Why distribution matters

A wallet ticket is useful only if the entry point is easy to open and safe to trust. Aparté distribution usually starts right after purchase, on the confirmation page, in the confirmation email, or later from an account page.

The Wallet Crew supports two practical patterns. One pattern uses hosted ticket pages. The other uses the SDK on a website controlled by the Brand or partner.

<details>

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

* **Confirmation email**: one hosted link opens the ticket list for the booking.
* **My tickets page**: one SDK button appears next to each ticket row.
* **Reminder journey**: the same hosted link is reused before the event.

</details>

### Send tickets from an email

Email is the most common Aparté distribution channel. It works well when the ticketing flow already sends a purchase or reminder email.

The Wallet Crew exposes hosted pages that detect the device and open the right wallet flow. On mobile, the page shows the native Apple Wallet or Google Wallet action. On desktop, it falls back to a QR code.

Always use a custom domain for these links. This keeps the organizer branding visible and avoids exposing a generic Wallet Crew domain to customers.

For the full email pattern, see [Via email](https://github.com/TheWalletCrew/docs/tree/main/enroll/via-email/README.md).

#### Link to multiple tickets

Use the hosted `tickets` page when one Aparté order item resolves several tickets.

```
https://<customdomain>/<tenantId>/tickets?ids.aparte.orderItemId=<orderItemId>&ids.aparte.orderItemId.hmac=<hmac>
```

`ids.aparte.orderItemId` is the multi-ticket identifier. The matching HMAC signs that exact value.

This page lists every ticket resolved from that Aparté order item. It is the standard entry point for an order confirmation journey when several tickets must be exposed from one booking flow.

A QA example follows the same structure:

```
https://app-qa.neostore.cloud/<tenantId>/tickets?ids.aparte.orderItemId=1956141&ids.aparte.orderItemId.hmac=<hmac>
```

#### Link to a single ticket

Use the hosted `ticket` page when the journey must open one precise ticket directly.

```
https://<customdomain>/<tenantId>/ticket?id.aparte.ticketId=<orderItemId>%7C<seatId>&id.aparte.ticketId.hmac=<hmac>
```

`id.aparte.ticketId` is the single-ticket identifier. Its value is `<orderItemId>|<seatId>`.

Encoding the separator as `%7C` is safer than leaving a raw `|` in the URL. The HMAC must match the exact value used in the link.

A QA example follows the same pattern:

```
https://app-qa.neostore.cloud/<tenantId>/ticket?id.aparte.ticketId=1956141%7C29737860&id.aparte.ticketId.hmac=<hmac>
```

#### Email implementation notes

Three rules matter for reliability. Compute the HMAC server-side. Always use a configured custom domain, not `localhost`. Preserve the full URL in the email tool so no query parameter is truncated or rewritten.

### Add the button on a website with the SDK

Use the SDK when the Brand or partner controls the page where the ticket is shown. Typical placements are an order confirmation page, a customer account, or a dedicated ticket list.

The SDK handles device detection and renders the right wallet action. The Aparté-specific part is the identifier contract sent to the SDK.

For the full website integration model, see [On your website](https://github.com/TheWalletCrew/docs/tree/main/enroll/on-your-website.md).

#### Single-ticket SDK pattern

For one ticket, the page should resolve the Aparté identifier in the same format as the hosted single-ticket URL.

Use `aparte.ticketId` as the external identifier. Its value is `<orderItemId>|<seatId>`. The matching HMAC must be generated server-side from that exact value.

This is the pattern to use when one wallet button is rendered for one ticket card or one ticket row.

#### Multi-ticket website pattern

For a page that shows several tickets, two patterns work well.

The first pattern renders one SDK button per ticket. This is useful on an authenticated **My tickets** page.

The second pattern links to the hosted `/tickets` page using `ids.aparte.orderItemId`. This is usually simpler on a confirmation page because one link can expose the full ticket list resolved from the order item.

### Security notes

Aparté distribution relies on signed identifiers. The HMAC must stay server-side and must never be generated in browser code.

The identifier value and the signed value must stay identical. If the ticket id is signed as `<orderItemId>|<seatId>`, the distributed URL must reuse that exact value. If the pipe is URL-encoded in the final link, the HMAC still signs the logical identifier value, not a different ticket id.

### FAQ

<details>

<summary><strong>What is the difference between <code>id.aparte.ticketId</code> and <code>ids.aparte.orderItemId</code>?</strong></summary>

`id.aparte.ticketId` targets one precise ticket.

`ids.aparte.orderItemId` targets the hosted list flow and resolves the tickets attached to that Aparté order item.

</details>

<details>

<summary><strong>Why should a custom domain always be used?</strong></summary>

A custom domain keeps the organizer branding visible during the wallet journey.

This avoids exposing a generic The Wallet Crew domain to customers and creates a more consistent experience between the event, the email, and the hosted wallet page.

</details>

<details>

<summary><strong>Can the same email link expose several tickets?</strong></summary>

Yes.

Use the hosted `/tickets` page with `ids.aparte.orderItemId` and its matching HMAC.

</details>

<details>

<summary><strong>When should the SDK be preferred over the hosted page?</strong></summary>

Use the SDK when the page is fully controlled and the wallet action should appear inline.

Use the hosted page when email distribution or a single shared link is simpler.

</details>

<details>

<summary><strong>What happens on desktop instead of mobile?</strong></summary>

The hosted page detects the device automatically.

On mobile, it presents the native wallet action. On desktop, it falls back to a QR code so the pass can still be opened from a phone.

</details>

<details>

<summary><strong>Should the HMAC be generated in the browser?</strong></summary>

No.

The HMAC must always be generated server-side. Browser-side signing would expose the secret and weaken the distribution flow.

</details>

<details>

<summary><strong>What usually breaks a signed Aparté link?</strong></summary>

The most common issue is a mismatch between the identifier value and the signed value.

This can happen if a separator changes, if a query parameter is rewritten by the email tool, or if the final link does not reuse the exact identifier that was signed.

</details>

<details>

<summary><strong>When should the hosted <code>/tickets</code> page be preferred over several single-ticket links?</strong></summary>

Use `/tickets` when one booking flow needs to expose several tickets together.

This keeps the email or confirmation page simpler and lets one signed link resolve the full ticket list attached to the Aparté order item.

</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 dynamically by asking a question.

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

```
GET https://docs.thewalletcrew.io/connectors/ticketing/aparte/distribution.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.