Firestore Record Acknowledgments

The extension stores notices and acknowledgments as documents in a collection inside Firestore. You configure the collection during the installation process, when you set up the extension instance's configuration parameters.

The extensions' source code contains a web app providing admin utilities that you can run locally. This contains a notice builder UI that you can use to easily create and customize notices. Setup instructions are available in the above link provided. Once set up, navigate to localhost:3000 to see the notice builder tool.

Retrieving a notice#

After creating a notice, you can use the following snippet in your web/mobile app to get the notice you want to show to your users, using the notice type:

import { getFunctions, httpsCallable } from 'firebase/functions';

const functions = getFunctions();
const notice = await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-getNotice',
)({
  type: 'banner',
});

Note: if multiple instances of this extension are installed the callable function name might contain a unique identifier, e.g. ext-firestore-firestore-record-acknowledgments-<id>-getNotice.

The response of the function call will contain the notice document data, along with whether the current authenticated user has acknowledged the notice.

To retrieve a notice by a specific version, provide the version parameter:

import { getFunctions, httpsCallable } from 'firebase/functions';

const functions = getFunctions();
const notice = await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-getNotice',
)({
  type: 'banner',
  version: 2,
});

View the reference API for full details on the response interface.

Acknowledging a notice#

To acknowledge a notice, the extension provides two callable functions which accept the notice ID: acknowledgeNotice & unacknowledgeNotice. The extension will keep historical records of each acknowledgment the callable functions are called multiple times for the same user and notice.

For example, to acknowledge a notice:

import { getFunctions, httpsCallable } from 'firebase/functions';

const functions = getFunctions();
await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-acknowledgeNotice',
)({
  noticeId: 'EA9QhZKKta9KXcckiasc',
});

In-case you need to capture custom preferences relating to an acknowledgment, you can provide custom metadata to the function, for example:

await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-acknowledgeNotice',
)({
  noticeId: 'EA9QhZKKta9KXcckiasc',
  metadata: { preference1: true, preference2: false },
});

You can also provide a custom “type” of acknowledgment (the default type is “seen”), for example:

await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-acknowledgeNotice',
)({
  noticeId: 'EA9QhZKKta9KXcckiasc',
  type: 'seen',
});

If you wish to unacknowledge a notice, call the unacknowledgeNotice function:

await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-unacknowledgeNotice',
)({
  noticeId: 'EA9QhZKKta9KXcckiasc',
  metadata: { reason: '...' },
});

Retrieving acknowledgments#

To retrieve all previous user notice acknowledgments, call the getAcknowledgments callable function. This function will return an ordered array of all acknowledgments along with the notice data:

import { getFunctions, httpsCallable } from 'firebase/functions';

const functions = getFunctions();
const acknowledgments = await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-getAcknowledgments',
)();

By default this won’t include unacknowledgment documents, however if those are required you can provide a includeUnacknowledgments property to the call:

import { getFunctions, httpsCallable } from 'firebase/functions';

const functions = getFunctions();
const acknowledgments = await httpsCallable(
  functions,
  'ext-firestore-firestore-record-acknowledgments-getAcknowledgments',
)({
  includeUnacknowledgments: true,
});

User specific acknowledgments#

You may need to create custom notices that are shown to and can only be acknowledged by a specific subset of users. To accomplish this, specify an allowList array of UIDs to the notice document. If the user requesting a notice by type is not within the list of UIDs, a not-found error will be returned.

Updating a notice#

When it's time to update a notice, for example when additional user preferences are required, create a new notice document with the same type as the existing notice you wish to update.

When the notice is retrieved, a new notice document will be returned with no acknowledgment, allowing users to acknowledge the newer notice.