Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Listening to events

The SDK emits several events to provide the application with an up-to-date state of the SDK or ongoing payments.

Add event listener API docs

Rust
pub(crate) struct SdkEventListener {}

#[async_trait::async_trait]
impl EventListener for SdkEventListener {
    async fn on_event(&self, e: SdkEvent) {
        match e {
            SdkEvent::Synced => {
                // Data has been synchronized with the network. When this event is received,
                // it is recommended to refresh the payment list and wallet balance.
            }
            SdkEvent::UnclaimedDeposits { unclaimed_deposits } => {
                // SDK was unable to claim some deposits automatically
            }
            SdkEvent::ClaimedDeposits { claimed_deposits } => {
                // Deposits were successfully claimed
            }
            SdkEvent::PaymentSucceeded { payment } => {
                // A payment completed successfully
            }
            SdkEvent::PaymentPending { payment } => {
                // A payment is pending (waiting for confirmation)
            }
            SdkEvent::PaymentFailed { payment } => {
                // A payment failed
            }
            SdkEvent::Optimization { optimization_event } => {
                // An optimization event occurred
            }
        }
    }
}

pub(crate) async fn add_event_listener(
    sdk: &BreezSdk,
    listener: Box<SdkEventListener>,
) -> Result<String> {
    let listener_id = sdk.add_event_listener(listener).await;
    Ok(listener_id)
}
Swift
class SdkEventListener: EventListener {
    func onEvent(event: SdkEvent) async {
        switch event {
        case .synced:
            // Data has been synchronized with the network. When this event is received,
            // it is recommended to refresh the payment list and wallet balance.
            break
        case .unclaimedDeposits(let unclaimedDeposits):
            // SDK was unable to claim some deposits automatically
            let _ = unclaimedDeposits
        case .claimedDeposits(let claimedDeposits):
            // Deposits were successfully claimed
            let _ = claimedDeposits
        case .paymentSucceeded(let paymentSucceeded):
            // A payment completed successfully
            let _ = paymentSucceeded
        case .paymentPending(let paymentPending):
            // A payment is pending (waiting for confirmation)
            let _ = paymentPending
        case .paymentFailed(let paymentFailed):
            // A payment failed
            let _ = paymentFailed
        case .optimization(let optimizationEvent):
            // An optimization event occurred
            let _ = optimizationEvent
        default:
            // Handle any future event types
            break
        }
    }
}

func addEventListener(sdk: BreezSdk, listener: SdkEventListener) async -> String {
    let listenerId = await sdk.addEventListener(listener: listener)
    return listenerId
}
Kotlin
class SdkListener : EventListener {
    override suspend fun onEvent(e: SdkEvent) {
        when (e) {
            is SdkEvent.Synced -> {
                // Data has been synchronized with the network. When this event is received,
                // it is recommended to refresh the payment list and wallet balance.
            }
            is SdkEvent.UnclaimedDeposits -> {
                // SDK was unable to claim some deposits automatically
                val unclaimedDeposits = e.unclaimedDeposits
            }
            is SdkEvent.ClaimedDeposits -> {
                // Deposits were successfully claimed
                val claimedDeposits = e.claimedDeposits
            }
            is SdkEvent.PaymentSucceeded -> {
                // A payment completed successfully
                val payment = e.payment
            }
            is SdkEvent.PaymentPending -> {
                // A payment is pending (waiting for confirmation)
                val pendingPayment = e.payment
            }
            is SdkEvent.PaymentFailed -> {
                // A payment failed
                val failedPayment = e.payment
            }
            is SdkEvent.Optimization -> {
                // An optimization event occurred
                val optimizationEvent = e.optimizationEvent
            }
            else -> {
                // Handle any future event types
            }
        }
    }
}

suspend fun addEventListener(sdk: BreezSdk, listener: SdkListener): String? {
    try {
        val listenerId = sdk.addEventListener(listener)
        return listenerId
    } catch (e: Exception) {
        // handle error
        return null
    }
}
C#
class SdkListener : EventListener
{
    public async Task OnEvent(SdkEvent sdkEvent)
    {
        switch (sdkEvent)
        {
            case SdkEvent.Synced syncedEvent:
                // Data has been synchronized with the network. When this event is received,
                // it is recommended to refresh the payment list and wallet balance.
                break;

            case SdkEvent.UnclaimedDeposits unclaimedDepositsEvent:
                // SDK was unable to claim some deposits automatically
                var unclaimedDeposits = unclaimedDepositsEvent.unclaimedDeposits;
                break;

            case SdkEvent.ClaimedDeposits claimedDepositsEvent:
                // Deposits were successfully claimed
                var claimedDeposits = claimedDepositsEvent.claimedDeposits;
                break;

            case SdkEvent.PaymentSucceeded paymentSucceededEvent:
                // A payment completed successfully
                var payment = paymentSucceededEvent.payment;
                break;

            case SdkEvent.PaymentPending paymentPendingEvent:
                // A payment is pending (waiting for confirmation)
                var pendingPayment = paymentPendingEvent.payment;
                break;

            case SdkEvent.PaymentFailed paymentFailedEvent:
                // A payment failed
                var failedPayment = paymentFailedEvent.payment;
                break;

            case SdkEvent.Optimization optimizationEvent:
                // An optimization event occurred
                var optimization = optimizationEvent.optimizationEvent;
                break;

            default:
                // Handle any future event types
                break;
        }
    }
}

async Task<string> AddEventListener(BreezSdk sdk, SdkListener listener)
{
    var listenerId = await sdk.AddEventListener(listener: listener);
    return listenerId;
}
Javascript
class JsEventListener {
  onEvent = async (event: SdkEvent) => {
    switch (event.type) {
      case 'synced': {
        // Data has been synchronized with the network. When this event is received,
        // it is recommended to refresh the payment list and wallet balance.
        break
      }
      case 'unclaimedDeposits': {
        // SDK was unable to claim some deposits automatically
        const unclaimedDeposits = event.unclaimedDeposits
        break
      }
      case 'claimedDeposits': {
        // Deposits were successfully claimed
        const claimedDeposits = event.claimedDeposits
        break
      }
      case 'paymentSucceeded': {
        // A payment completed successfully
        const payment = event.payment
        break
      }
      case 'paymentPending': {
        // A payment is pending (waiting for confirmation)
        const pendingPayment = event.payment
        break
      }
      case 'paymentFailed': {
        // A payment failed
        const failedPayment = event.payment
        break
      }
      case 'optimization': {
        // An optimization event occurred
        const optimizationEvent = event.optimizationEvent
        break
      }
      default: {
        // Handle any future event types
        break
      }
    }
  }
}

const eventListener = new JsEventListener()

const listenerId = await sdk.addEventListener(eventListener)
React Native
class JsEventListener {
  onEvent = async (event: SdkEvent) => {
    if (event.tag === SdkEvent_Tags.Synced) {
      // Data has been synchronized with the network. When this event is received,
      // it is recommended to refresh the payment list and wallet balance.
    } else if (event.tag === SdkEvent_Tags.UnclaimedDeposits) {
      // SDK was unable to claim some deposits automatically
      const unclaimedDeposits = event.inner.unclaimedDeposits
    } else if (event.tag === SdkEvent_Tags.ClaimedDeposits) {
      // Deposits were successfully claimed
      const claimedDeposits = event.inner.claimedDeposits
    } else if (event.tag === SdkEvent_Tags.PaymentSucceeded) {
      // A payment completed successfully
      const payment = event.inner.payment
    } else if (event.tag === SdkEvent_Tags.PaymentPending) {
      // A payment is pending (waiting for confirmation)
      const pendingPayment = event.inner.payment
    } else if (event.tag === SdkEvent_Tags.PaymentFailed) {
      // A payment failed
      const failedPayment = event.inner.payment
    } else if (event.tag === SdkEvent_Tags.Optimization) {
      // An optimization event occurred
      const optimizationEvent = event.inner.optimizationEvent
    } else {
      // Handle any future event types
    }
  }
}

const eventListener = new JsEventListener()

const listenerId = await sdk.addEventListener(eventListener)
Flutter
StreamSubscription<SdkEvent>? _eventSubscription;
Stream<SdkEvent>? _eventStream;

// Initializes SDK event stream.
//
// Call once on your Dart entrypoint file, e.g.; `lib/main.dart`
// or singleton SDK service. It is recommended to use a single instance
// of the SDK across your Flutter app.
void initializeEventsStream(BreezSdk sdk) {
  _eventStream ??= sdk.addEventListener().asBroadcastStream();
}

final _eventStreamController = StreamController<SdkEvent>.broadcast();
Stream<SdkEvent> get eventStream => _eventStreamController.stream;

// Subscribe to the event stream
void subscribeToEventStream() {
  _eventSubscription = _eventStream?.listen((sdkEvent) {
    switch (sdkEvent) {
      case SdkEvent_Synced():
        // Data has been synchronized with the network. When this event is received,
        // it is recommended to refresh the payment list and wallet balance.
        break;
      case SdkEvent_UnclaimedDeposits(:final unclaimedDeposits):
        // SDK was unable to claim some deposits automatically
        final _ = unclaimedDeposits;
        break;
      case SdkEvent_ClaimedDeposits(:final claimedDeposits):
        // Deposits were successfully claimed
        final _ = claimedDeposits;
        break;
      case SdkEvent_PaymentSucceeded(:final payment):
        // A payment completed successfully
        final _ = payment;
        break;
      case SdkEvent_PaymentPending(:final payment):
        // A payment is pending (waiting for confirmation)
        final _ = payment;
        break;
      case SdkEvent_PaymentFailed(:final payment):
        // A payment failed
        final _ = payment;
        break;
      case SdkEvent_Optimization(:final optimizationEvent):
        // An optimization event occurred
        final _ = optimizationEvent;
        break;
    }
    _eventStreamController.add(sdkEvent);
  }, onError: (e) {
    _eventStreamController.addError(e);
  });
}
Python
class SdkListener(EventListener):
    def on_event(self, event: SdkEvent):
        if isinstance(event, SdkEvent.SYNCED):
            # Data has been synchronized with the network. When this event is received,
            # it is recommended to refresh the payment list and wallet balance.
            pass
        elif isinstance(event, SdkEvent.UNCLAIMED_DEPOSITS):
            # SDK was unable to claim some deposits automatically
            unclaimed_deposits = event.unclaimed_deposits
        elif isinstance(event, SdkEvent.CLAIMED_DEPOSITS):
            # Deposits were successfully claimed
            claimed_deposits = event.claimed_deposits
        elif isinstance(event, SdkEvent.PAYMENT_SUCCEEDED):
            # A payment completed successfully
            payment = event.payment
        elif isinstance(event, SdkEvent.PAYMENT_PENDING):
            # A payment is pending (waiting for confirmation)
            pending_payment = event.payment
        elif isinstance(event, SdkEvent.PAYMENT_FAILED):
            # A payment failed
            failed_payment = event.payment
        elif isinstance(event, SdkEvent.OPTIMIZATION):
            # An optimization event occurred
            optimization_event = event.optimization_event
        else:
            # Handle any future event types
            pass


async def add_event_listener(sdk: BreezSdk, listener: SdkListener):
    try:
        listener_id = await sdk.add_event_listener(listener=listener)
        return listener_id
    except Exception as error:
        logging.error(error)
        raise
Go
type SdkListener struct{}

func (SdkListener) OnEvent(e breez_sdk_spark.SdkEvent) {
	switch event := e.(type) {
	case breez_sdk_spark.SdkEventSynced:
		// Data has been synchronized with the network. When this event is received,
		// it is recommended to refresh the payment list and wallet balance.
	case breez_sdk_spark.SdkEventUnclaimedDeposits:
		// SDK was unable to claim some deposits automatically
		unclaimedDeposits := event.UnclaimedDeposits
		_ = unclaimedDeposits
	case breez_sdk_spark.SdkEventClaimedDeposits:
		// Deposits were successfully claimed
		claimedDeposits := event.ClaimedDeposits
		_ = claimedDeposits
	case breez_sdk_spark.SdkEventPaymentSucceeded:
		// A payment completed successfully
		payment := event.Payment
		_ = payment
	case breez_sdk_spark.SdkEventPaymentPending:
		// A payment is pending (waiting for confirmation)
		pendingPayment := event.Payment
		_ = pendingPayment
	case breez_sdk_spark.SdkEventPaymentFailed:
		// A payment failed
		failedPayment := event.Payment
		_ = failedPayment
	case breez_sdk_spark.SdkEventOptimization:
		// An optimization event occurred
		optimizationEvent := event.OptimizationEvent
		_ = optimizationEvent
	default:
		// Handle any future event types
	}
}

func AddEventListener(sdk *breez_sdk_spark.BreezSdk, listener SdkListener) string {
	return sdk.AddEventListener(listener)
}

Remove event listener API docs

When you no longer need to listen to events, you can remove the listener.

Rust
pub(crate) async fn remove_event_listener(sdk: &BreezSdk, listener_id: &str) -> Result<()> {
    sdk.remove_event_listener(listener_id).await;
    Ok(())
}
Swift
func removeEventListener(sdk: BreezSdk, listenerId: String) async {
    await sdk.removeEventListener(id: listenerId)
}
Kotlin
suspend fun removeEventListener(sdk: BreezSdk, listenerId: String)  {
    try {
        sdk.removeEventListener(listenerId)
    } catch (e: Exception) {
        // handle error
    }
}
C#
async Task RemoveEventListener(BreezSdk sdk, string listenerId)
{
    await sdk.RemoveEventListener(id: listenerId);
}
Javascript
await sdk.removeEventListener(listenerId)
React Native
await sdk.removeEventListener(listenerId)
Flutter
void unsubscribeFromEventStream() {
  _eventSubscription?.cancel();
}
Python
async def remove_event_listener(sdk: BreezSdk, listener_id: str):
    try:
        await sdk.remove_event_listener(id=listener_id)
    except Exception as error:
        logging.error(error)
        raise
Go
func RemoveEventListener(sdk *breez_sdk_spark.BreezSdk, listenerId string) bool {
	return sdk.RemoveEventListener(listenerId)
}