Skip to content

Branded SDK events

SDK callbacks let your host app respond when a cardholder opens an offer, views a balance or completes merchant activation. Use the event names, payloads and subscription example below to connect those interface actions to your app. Callbacks alone do not prove that a purchase qualifies for a reward.

Activity Reporting

Under the session contract, the SDK reports activity using the authenticated active cardholder identity. You do not need to turn these callbacks into additional user-activity requests. Use the user-activity API for interactions in experiences you build outside the SDK.

Callbacks and Qualification

  • offer_viewed means offer detail opened. It does not establish 50% viewport visibility for 1.3 seconds.
  • offer_clicked alone does not record a cashback CLICK.
  • Merchant-activation callbacks describe branded activation only and do not activate any cashback policy.

Record actual cashback CLICK or paired VIEW facts through the cardholder user-activity routes.

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

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

unsubscribe();
EventPayload
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. Handlers should ignore unknown properties because payloads may gain fields over time.