API Reference

This page contains the complete documentation about the Hooks library. You can find here the list of all the methods that you can use.

useFeed

Hook for handling all the states of a notification feed

const { notifications, loading, loadMore, refresh, hasMore } = useFeed();

type definition

const useFeed: () => {
  notifications: EngagespotStoreNotification[];
  loading: boolean;
  loadMore: () => void;
  refresh: () => void;
  hasMore: boolean;
};

type EngagespotStoreNotification = EngagespotNotification & {
  createdAtRelative?: string;
  clickedAtRelative?: string;
  seenAtRelative?: string;
};

type EngageSpotNotification = {
  id: number;
  title: string;
  message?: string | null;
  icon?: string | null;
  url?: string | null;
  data?: Record<string, unknown> | null;
  category?: {
    id?: string;
    identifier?: string;
    name?: string;
  };
  blocks?: {
    id?: string;
    type?:
      | 'box'
      | 'typography'
      | 'blue-dot'
      | 'rating-star'
      | 'card'
      | 'button'
      | 'image'
      | 'textarea'
      | 'input';
    text?: string;
    src?: OneOf<
      [
        string,
        {
          blob?: string;
        },
      ]
    >;
    variant?: 'default' | 'primary' | 'secondary';
  }[];
  createdAt: string;
  seenAt?: string | null;
  clickedAt?: string | null;
  state?: 'unread' | 'seen' | 'clicked' | null;
};

useActions

Hook for handling all the actions of a notification panel

const {
  deleteNotification,
  markAsRead,
  markAllAsRead,
  deleteAllNotifications,
  markAsSeen,
  changeState,
} = useActions();

type definition

const useActions: () => {
  deleteNotification: (notificationId: number) => Promise<void>;
  markAsRead: (notificationId: number) => Promise<void>;
  markAllAsRead: (data: Optional<Pagination, 'limit'>) => Promise<void>;
  deleteAllNotifications: () => Promise<void>;
  markAsSeen: (data: Optional<Pagination, 'limit'>) => Promise<void>;
  changeState: (values: { id: string; state: string }) => Promise<void>;
};

type Pagination = { pageNo: number; limit?: number };

Additional Info

• changeState: (values: {id: string, state: string}) => Promise<void>
  • A function to change the state for actionable notifications.

useUnreadCount

Hook for getting the unread no of notifications

const unreadCount = useUnreadCount();

type definition

useUnreadCount(): number

useEvent

Hook for listening to an event firing and get it's related data

useEvent('eventName', data => {
  console.log(data, 'event information');
});

type definition

useEvent<T extends keyof EventCallbackMap>(eventName: T, callback: EventCallbackMap[T]): void

type EventCallback<T> = (params: T) => void;

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

type NotificationReceiveEvent = { notification: Notification };
type NotificationDeleteEvent = { id: string };
type NotificationClickEvent = { id: string };
type NotificationSeenEvent = { unreadCount: number };
type NotificationReadAll = void;
type NotificationDeleteAll = void;
type NotificationStateChange = {
  notification: Notification;
};

Additional Info

• eventName could be of the values notificationReceive | notificationDelete | notificationRead | notificationSeen | notificationReadAll | notificationDeleteAll | notificationStateChange
• The data on your callback argument is based on the type of your eventName

useWebPush

Hook for handling WebPush actions

const {
  metadata,
  subscribe,
  clearWebPushSubscription,
  isSupported,
  webPushState,
} = useWebPush();

type definition

const useWebPush: () => {
  metadata: FetcherValue<FetchResponse<MetaData>>;
  subscribe: () => Promise<void>;
  clearWebPushSubscription: () => Promise<void>;
  isSupported: () => boolean;
  webPushState: PermissionState;
};

type PermissionState = 'denied' | 'granted' | 'default';

usePreferences

Hook for user preference state and methods

const { preferences, setProfileAttributes, setPreferences, channels } =
  usePreferences();

type definition

const usePreferences: () => {
 preferences: Preferences;
 setProfileAttributes: (data: SetUserAttributes) => void
 setPreferences: setPreferences;
 channels: Channels;
};

type Preferences: {
    categories: {
        channels: {
            id: Channels;
            name: string;
            enabled: boolean;
        }[];
        id?: number | undefined;
        name?: string | undefined;
        identifier?: string | undefined;
        createdAt?: string | undefined;
        updatedAt?: string | undefined;
    }[] | undefined;
}

type SetUserAttributes = Record<string, unknown>;

type setPreferences: (data: {
    categoryId?: number | undefined;
    channels?: {
        channel?: Channels;
        enabled?: boolean | undefined;
    }[] | undefined;
}[]) => Promise<void>

type Channels = "inApp" | "webPush" | "email" | "mobilePush" | "sms" | "whatsapp" |
  "webhook" | "discord" | "slack" | "chat"

Engagespot Provider

Provider makes all hook methods and values accessible throughout your application.

const App = () => {
  return (
    <EngagespotProvider
      options={{
        userId: 'youruser@example.com',
        apiKey: 'YOUR_ENGAGESPOT_API_KEY',
      }}
    >
      <NotificationFeed />
    </EngagespotProvider>;
  );
};

type definition

EngagespotProvider({ options, children, }: EngagespotProviderProps): JSX.Element

type EngagespotProviderProps = {
  options: StoreOptions;
  children: ReactNode;
};

type StoreOptions = {
  /**
   * Unique user identifier
   */
  userId: string;

  /**
   * Engagespot API key
   */
  apiKey: string;

  /**
   *  signature for the user
   * @deprecated
   */
  userSignature?: string;

  /**
   * Enabling secure mode enforces token based authentication for the front-end in-app inbox.
   * Production apps must enable secure mode to prevent unauthorised access to your users in-app inbox.
   *
   * https://docs.engagespot.co/docs/features/in-app-inbox/authentication/#enabling-the-secure-mode
   */
  userToken?: string;

  /**
   * disable web push notifications.
   * Default is false
   */
  disableWebPush?: boolean;

  /**
   * Allow non-HTTPS web push. Useful for development environments.
   * Default is false
   */
  allowNonHttpsWebPush?: boolean;

  /**
   * service worker registration object
   */
  serviceWorkerRegistration?: ServiceWorkerRegistration;

  /**
   * Disables realtime messages
   * Default is false
   */
  disableRtm?: boolean;

  /**
   * optional base URL for Engagespot server.
   * Should be set if the Engagespot server is hosted on a different domain.
   */
  baseUrl?: string;

  /**
   * Enable debug mode
   * Default is false
   */
  debug?: boolean;

  /**
   * Disabling this will prevent Engagespot from calling the `connect()` and `realTime()` services automatically.
   */
  disableAutoStart?: boolean;

  /**
   * If disabled, the store won't update automatically on real-time events.
   */
  disableRealTimeStoreUpdates?: boolean;

  /**
   * If disabled, the store won't fetch notifications on start.
   */
  disableFetchOnStart?: boolean;

  /**
   * Limit the no of data to be fetched
   */
  itemsPerPage?: number;

  /**
   * The interval in milliseconds to recall the relative time update function
   */
  relativeTimeUpdateInterval?: number;
};