Adding WebSocket Event Subscriptions

This skill documents how to add new WebSocket event subscriptions in the OneKey app.

Overview

WebSocket events enable real-time server-to-client communication. The pattern involves:

1. Define the event name in

   EAppSocketEventNames

   enum
2. Define the payload type interface
3. Add the event handler in

   PushProviderWebSocket

Key Files

packages/shared/types/socket.ts

packages/kit-bg/src/services/ServiceNotification/PushProvider/PushProviderWebSocket.ts

Step-by-Step Guide

Step 1: Define Event Name

Add the new event name to

EAppSocketEventNames

packages/shared/types/socket.ts

export enum EAppSocketEventNames {
  notification = 'notification',
  ping = 'ping',
  pong = 'pong',
  ack = 'ack',
  market = 'market',
  primeConfigChanged = 'CONFIG_CHANGE',
  // ... existing events
  myNewEvent = 'MY_NEW_EVENT',  // Add your new event
}

Convention: Use camelCase for the enum key, SCREAMING_SNAKE_CASE for the string value.

Step 2: Define Payload Type

Add the payload interface in

packages/shared/types/socket.ts

export interface IMyNewEventPayload {
  msgId: string;  // Required for acknowledgment
  // Add other fields as needed
  someData?: string;
  someNumber?: number;
}

Important: Always include

msgId: string

Step 3: Add Event Handler

In

packages/kit-bg/src/services/ServiceNotification/PushProvider/PushProviderWebSocket.ts

1. Import the new payload type:

import type {
  // ... existing imports
  IMyNewEventPayload,
} from '@onekeyhq/shared/types/socket';

2. Add the event handler in

   initWebSocket()

   method:

this.socket.on(EAppSocketEventNames.myNewEvent, (payload: IMyNewEventPayload) => {
  // 1. Acknowledge receipt (required for most events)
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });

  // 2. Handle the event (call appropriate service method)
  void this.backgroundApi.someService.handleMyNewEvent(payload);
});

Complete Example: userInfoUpdated Event

Here's a real example from the codebase:

1. Event Name (socket.ts)

export enum EAppSocketEventNames {
  // ... other events
  userInfoUpdated = 'USER_INFO_UPDATED',
}

2. Payload Type (socket.ts)

export interface IUserInfoUpdatedPayload {
  msgId: string;
}

3. Event Handler (PushProviderWebSocket.ts)

this.socket.on(EAppSocketEventNames.userInfoUpdated, (payload: IUserInfoUpdatedPayload) => {
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });
  void this.backgroundApi.servicePrime.apiFetchPrimeUserInfo();
});

Event Handler Patterns

Simple Acknowledgment + Action

this.socket.on(EAppSocketEventNames.myEvent, (payload: IMyPayload) => {
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });
  void this.backgroundApi.someService.doSomething();
});

With Logging

this.socket.on(EAppSocketEventNames.myEvent, (payload: IMyPayload) => {
  defaultLogger.notification.websocket.consoleLog(
    'WebSocket received myEvent:',
    payload,
  );
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });
  void this.backgroundApi.someService.doSomething(payload);
});

With Validation

this.socket.on(EAppSocketEventNames.myEvent, async (payload: IMyPayload) => {
  if (!payload?.requiredField) {
    console.error('myEvent ERROR: requiredField is missing', payload);
    return;
  }
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });
  await this.backgroundApi.someService.doSomething(payload);
});

With EventBus Emission

this.socket.on(EAppSocketEventNames.myEvent, (payload: IMyPayload) => {
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });
  appEventBus.emit(EAppEventBusNames.MyEventReceived, payload);
});

Important: Message Acknowledgment

You MUST acknowledge messages via

serviceNotification.ackNotificationMessage

msgId

void this.backgroundApi.serviceNotification.ackNotificationMessage({
  msgId: payload.msgId,
  action: ENotificationPushMessageAckAction.arrived,
});

This should be called as early as possible in your event handler to prevent duplicate message delivery.

Acknowledgment Actions

Available actions in

ENotificationPushMessageAckAction

• arrived

  - Message was received (use this for most cases)

• clicked

  - User clicked the notification

Checklist

• Event name added to

  EAppSocketEventNames

  enum
• Payload interface defined with

  msgId: string

• Payload type imported in

  PushProviderWebSocket.ts

• Event handler added in

  initWebSocket()

  method
• Message acknowledged via

  ackNotificationMessage

  (required to prevent server retries)
• Appropriate service method called to handle the event
• Logging added if needed for debugging