Props

EngagespotProps are configuration options for customizing and integrating the Engagespot notification panel in your application. These options include visual styling, notification behavior, and event handling.

Visual and Theming Options

• theme (ThemeOverrides)
  Customize the theme to align with your app's branding by overriding default styles, including colors, fonts, and layout.

• feedItemPlaceholderImage (string)
  Placeholder image displayed when a notification lacks a specific image.

• headerText (string)
  Text displayed at the top of the notification panel, typically a title or heading.

• hideNotificationAvatar (boolean)
  Hides the avatar image shown alongside each notification item in the feed.

• hideJumpToTop (boolean)
  Toggles visibility of the button that scrolls to the top of the feed.

• disableNotificationChime (boolean)
  Disables the chime sound when a new notification is received. Defaults to true.

• notificationChimeSrc (string)
  Path or URL for the audio file used for the notification chime.

• hideCategoryTabs (boolean)
  When true, hides category tabs, showing all notifications in a single feed.

Custom Rendering Options

• renderFooterContent (customRenderFn)
  Custom function to render footer content in the panel, allowing for links or other specific content.

• renderNotificationIcon (customRenderFn)
  Custom icon renderer for the main notification icon.

• renderEmptyPlaceholderImage (customRenderFn)
  Renders a custom image when no notifications are available.

• renderNotificationContent (customRenderFn<customNotificationContentType>)
  Customize the content display for each notification item.

• renderNotificationBody (customRenderFn<customNotificationContentType>)
  Provides granular control over the text or components within the notification body.

Behavior and Functionality

• panelOpenByDefault (boolean)
  Automatically opens the notification panel when the component is loaded for the first time.

• panelOnly (boolean)
  Enables panel-only mode, hiding other UI elements and displaying only the notification panel.

• onFeedItemClick (onFeedItemClickType)
  Callback function triggered when a notification item is clicked, useful for navigation or custom actions.

• formatDate ((dateString: string, dateFns: typeof dateFunctions) => string)
  Function to format dates within notifications, useful for custom date formats.

• textOverrides (TextOverridesPartial)
  Allows overriding default text in the notification panel for custom wording or localization.

Event and Interaction Settings

• eventListenersToRun (EventListenersToRun[])
  List of event listeners for the panel, defining specific actions triggered by events.

• headerDropdownItems (DropdownMenuProps['items'])
  Custom dropdown items displayed in the panel header, useful for quick settings or filters.

• profile ({ [attribute: string]: any })
  Object to dynamically edit user profile attributes.

• events (Partial<EventCallbackMap>)
  Register callbacks for notification events from the store instance.

Advanced Options

• panel (PanelProps)
  Additional configurations for the floating panel.

• disableTextTranslation (boolean)
  Disables automatic text translation, useful for non-translatable content.

• toast (Partial<ToastProps>)
  Toast notification settings, allowing overrides for properties like position and duration.

• enableErrorBoundary (boolean)
  Enables error boundaries around the notification panel, capturing unexpected errors.

---

Store Options

• disableRealTimeStoreUpdates (boolean)
  If true, real-time store updates are disabled, and notifications won't automatically update with real-time events.

• disableFetchOnStart (boolean)
  Disables initial fetch of notifications when the store is created.

• itemsPerPage (number)
  Limits the number of notifications fetched per page.

• relativeTimeUpdateInterval (number)
  Interval (in milliseconds) to update relative time displays (e.g., "5 minutes ago").

---

Instance Options

• userId (string)
  Unique identifier for the user.

• tenantIdentifier (string)
  Unique identifier for the tenant (optional).

• apiKey (string)
  API key for accessing Engagespot services.

• userSignature (string)
  Deprecated. User-specific signature (use userToken for secure mode).

• userToken (string)
  Token for secure mode, enforcing token-based authentication.

• disableWebPush (boolean)
  Disables web push notifications (defaults to false).

• allowNonHttpsWebPush (boolean)
  Allows web push on non-HTTPS domains, useful for development (defaults to false).

• serviceWorkerRegistration (ServiceWorkerRegistration)
  Service worker registration object for push notifications.

• disableRtm (boolean)
  Disables real-time messages (defaults to false).

• baseUrl (string)
  Custom base URL for Engagespot server, necessary if hosted on a different domain.

• debug (boolean)
  Enables debug mode for additional logging (defaults to false).

• disableAutoStart (boolean)
  Prevents Engagespot from automatically calling connect() and realTime() on startup.

---

Example Usage

<EngagespotProvider options={{
  userId: "user_12345",
  apiKey: "your-api-key",
  disableFetchOnStart: false,
  itemsPerPage: 10,
  theme: { colorPrimary: "#007BFF" },
  panelOpenByDefault: true,
  onFeedItemClick: (item) => console.log("Notification clicked", item),
  renderNotificationContent: (notification) => <CustomNotification notification={notification} />,
}}>
  <YourApp />
</EngagespotProvider>

Type Definitions

type EngagespotProps = {
  userId: string;
  tenantIdentifier?: string;
  apiKey: string;
  userSignature?: string;
  userToken?: string;
  disableWebPush?: boolean;
  allowNonHttpsWebPush?: boolean;
  serviceWorkerRegistration?: ServiceWorkerRegistration;
  disableRtm?: boolean;
  baseUrl?: string;
  debug?: boolean;
  disableAutoStart?: boolean;
  disableRealTimeStoreUpdates?: boolean;
  disableFetchOnStart?: boolean;
  itemsPerPage?: number;
  relativeTimeUpdateInterval?: number;
  theme: ThemeOverrides;
  panelOpenByDefault: boolean;
  panelOnly: boolean;
  feedItemPlaceholderImage: string;
  hideNotificationAvatar: boolean;
  hideJumpToTop: boolean;
  headerText: string;
  renderFooterContent: customRenderFn;
  renderNotificationIcon: customRenderFn;
  renderEmptyPlaceholderImage: customRenderFn;
  onFeedItemClick: onFeedItemClickType;
  textOverrides: TextOverridesPartial;
  renderNotificationContent: customRenderFn<customNotificationContentType>;
  renderNotificationBody: customRenderFn<customNotificationContentType>;
  eventListenersToRun: EventListenersToRun[];
  headerDropdownItems: DropdownMenuProps['items'];
  formatDate: (dateString: string, dateFns: typeof dateFunctions) => string;
  disableNotificationChime: boolean;
  notificationChimeSrc: string;
  panel: PanelProps;
  disableTextTranslation: boolean;
  toast: Partial<ToastProps>;
  hideCategoryTabs: boolean;
  enableErrorBoundary: boolean;
  profile?: {
    [attribute: string]: any;
  };
  events?: Partial<EventCallbackMap>;
};

type defaultRenderFn = (...args: unknown[]) => ReactNode | string;

type customRenderFn<T = defaultRenderFn> = T | undefined;

type NotificationReceiveEvent = { notification: EngagespotNotification };

type ClickableNotificationPayload = {
  url?: string | null;
  id: number;
  markAsClicked: () => void;
};

type onFeedItemClickType = (
  evt: ReactMouseEvent<HTMLDivElement, MouseEvent>,
  payload: ClickableNotificationPayload,
) => void;

type PanelProps = {
  isOpen: boolean;
  setIsOpen: (isOpen: boolean) => void;
  disableDismiss?: boolean;
};

type ToastProps = {
  enableToast: boolean;
  toasterProps: Partial<ToasterProps>;
  toastProps: {
    renderToast?: (prop: {
      notificationReceiveEvent: NotificationReceiveEvent;
      toast: typeof sonnerToast;
    }) => void;
    message?: (notificationReceiveEvent: NotificationReceiveEvent) => string;
    description?: (
      notificationReceiveEvent: NotificationReceiveEvent,
    ) => string;
    options?: (
      notificationReceiveEvent: NotificationReceiveEvent,
    ) => Omit<ExternalToast, 'description'>;
  };
};

type EventListenersToRun = {
    blockId: string;
    event: ReactEvent;
    onEvent: ({ event, notification, changeNotificationState, getValue, }: {
        event: ReactEventHandler;
        notification: EngagespotNotification;
        changeNotificationState: changeNotificationStateFnType;
        getValue: (id: string) => string;
    }) => void;
};

type EventCallback<T> = (params: T) => void;
type Events = ReturnType<typeof initializeEvents>;

type EventCallbackMap = {
  notificationReceive: EventCallback<NotificationReceiveEvent>;
  notificationDelete: EventCallback<NotificationDeleteEvent>;
  notificationRead: EventCallback<NotificationClickEvent>;
  notificationSeen: EventCallback<NotificationSeenEvent>;
  notificationReadAll: EventCallback<NotificationReadAll>;
  notificationDeleteAll: EventCallback<NotificationDeleteAll>;
  notificationStateChange: EventCallback<NotificationStateChange>;
};