@leaflink/vue-notification-feed

vue-notification-feed

A set of components for integrating Knock in-app notifications into a Vue application.

Note: these components are currently designed to be used in conjunction with the Knock in-app feed channel, and via Vue for web only.

Knock documentation

Table of Contents

• Installation
• Configuration
• Usage
• Headless usage
  • Headless usage w/ refs
• Enhanced security mode
  • Component version
  • Headless version
• Related links
• Contribution

Installation

npm install @leaflink/vue-notification-feed

Configuration

To configure the feed you will need:

1. A public API key (found in the Knock dashboard)
2. A feed channel ID (found in the Knock dashboard)
3. A user ID (this should be unique to each user)
4. A user auth token for production environments with enhanced security mode enabled

Usage

You can integrate the feed into your app as follows:

<script setup lang="ts">
import {
  KnockFeedProvider,
  NotificationFeedPopover,
  NotificationIconButton,
} from "@leaflink/vue-notification-feed";
import { useUserStore } from "@/stores/user";

// Required CSS import, unless you're fully overriding the styles
import "@leaflink/vue-notification-feed/style.css";

const userStore = useUserStore();
</script>

<template>
  <KnockFeedProvider
    apiKey="{import.meta.env.VITE_KNOCK_PUBLIC_API_KEY}"
    feedId="{import.meta.env.VITE_KNOCK_FEED_ID}"
    userId="{userStore.id}"
  >
    <Dropdown close-manually>
      <template #toggle="{ toggle }">
        <NotificationIconButton @click="toggle" />
      </template>
      <template #default="{ dismiss }">
        <NotificationFeedPopover @keydown.esc="dismiss" />
      </template>
    </Dropdown>
  </KnockFeedProvider>
</template>

If you want to display notifications as a listing page rather then a popover:

<script setup lang="ts">
import {
  KnockFeedProvider,
  NotificationFeed,
} from "@leaflink/vue-notification-feed";
import { useUserStore } from "@/stores/user";

// Required CSS import, unless you're fully overriding the styles
import "@leaflink/vue-notification-feed/style.css";

const userStore = useUserStore();
</script>

<template>
  <KnockFeedProvider
    apiKey="{import.meta.env.VITE_KNOCK_PUBLIC_API_KEY}"
    feedId="{import.meta.env.VITE_KNOCK_FEED_ID}"
    userId="{userStore.id}"
  >
    <NotificationFeed />
  </KnockFeedProvider>
</template>

Headless usage

Alternatively, if you don't want to use our components you can render the feed in a headless mode using our composables:

<script setup lang="ts">
import {
  useAuthenticatedKnockClient,
  useNotifications,
} from "@leaflink/vue-notification-feed";
import { useUserStore } from "@/stores/user";

const store = useUserStore();
const knockClient = useAuthenticatedKnockClient(
  import.meta.env.VITE_KNOCK_PUBLIC_API_KEY,
  store.id
);
const feed = useNotifications(knockClient, import.meta.env.VITE_KNOCK_FEED_ID);
const store = useFeedStore();

feed.value.on("items.received.*", (payload) => {
  console.log("items.received.*", payload, payload.items);
});
feed.value.fetch();
</script>

<template>
  <p>Total notifications: {{ store.metadata.total_count }}</p>
  <p>Total unread: {{ store.metadata.unread_count }}</p>

  <template
    v-for="item in store.items"
    :key="item.id"
    :item="item"
    :feed="feed"
  >
    <div v-for="block in item.blocks" v-html="block.rendered" />
  </template>
</template>

Headless usage w/ refs

In the event you can't initialize the feed synchronously (i.e. you're waiting for the user's id to be populated by an Auth0 call), you can pass refs to the composables and they will adjust accordingly.

Important:

• You won't be able to use a tool like vue-zustand though, so you'll need to define your own refs.

In this example, you can expect store.id to be undefined to begin with and then eventually get set to the users id.

<script setup lang="ts">
import {
  useAuthenticatedKnockClient,
  useNotifications,
  FeedItem,
  FeedMetadata,
} from "@leaflink/vue-notification-feed";
import { useUserStore } from "@/stores/user";

const store = useUserStore();
const knockClient = useAuthenticatedKnockClient(
  import.meta.env.VITE_KNOCK_PUBLIC_API_KEY,
  store.id
);
const feed = useNotifications(knockClient, import.meta.env.VITE_KNOCK_FEED_ID);

const items = ref<FeedItem[]>([]);
const metadata = ref<FeedMetadata>({});

watch(feed, () => {
  if (!feed.value) return;

  feed.value.on("items.received.*", (payload) => {
    items.value = payload.items;
    metadata.value = payload.metadata;
  });
  feed.value.fetch();
});
</script>

Enhanced security mode

On production environments, we have Enhanced security mode enabled. So it's necessary to provide a user auth token to knock.

[!TIP] Please follow the documentation instructions on how to generate this token.

Component version

<script setup lang="ts">
const userToken = "my-user-token";
</script>

<template>
  <KnockFeedProvider [...] :user-token="userToken">
    <!-- your code here -->
  </KnockFeedProvider>
</template>

Headless version

<script setup lang="ts">
import {
  useAuthenticatedKnockClient,
  useNotifications,
} from "@leaflink/vue-notification-feed";
import { useUserStore } from "@/stores/user";

const store = useUserStore();
const userToken = "my-user-token";
const knockClient = useAuthenticatedKnockClient(
  import.meta.env.VITE_KNOCK_PUBLIC_API_KEY,
  store.id,
  userToken
);
</script>

[!WARNING] Be aware that if a knock environment doesn't have Enhanced security mode enabled, the request for that environment will fail. Make sure to provide the user token only for environments that has enhanced security enabled.

Related links

• Knock documentation
• Knock dashboard

Contribution

Contribution guidelines