# Events

Subscribe to SDK events with `widget.on(name, handler)`. The method returns an unsubscribe function.

```ts
const unsubscribe = widget.on('offer_viewed', (payload) => {
  console.log(payload.offerId, payload.merchantId);
});

unsubscribe();
```

| Event | Payload |
|  --- | --- |
| `ready` | `{ view }` after the iframe receives bootstrap data. |
| `resize` | `{ height }` when the iframe content height changes. The SDK applies the height to the iframe. |
| `offer_viewed` | `{ offerId, merchantId }` when a cardholder opens offer detail. |
| `offer_clicked` | `{ offerId, merchantId }` when a cardholder clicks an offer card. |
| `merchant_activation_started` | `{ merchantId, offerId }` when activation begins. |
| `merchant_activation_completed` | `{ merchantId, offerId }` when activation succeeds. |
| `balance_detail_opened` | `{ merchantId }` when balance detail opens. |
| `closed` | `{ surface, merchantId? }` when an offer-detail overlay or merchant-balance drawer closes. `surface` is `offer_details` or `balance_details`. |
| `error` | `{ message }` when SDK initialization fails. |


Event names are stable. Payloads may add fields over time, so handlers should ignore unknown properties.