# 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](https://github.com/invertase/firebase-extensions/tree/main/extensions/firestore-firestore-record-acknowledgments/admin-dashboard) 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](http://localhost:3000) to see the notice builder tool.

![Admin Dashboard](/firestore-record-acknowledgments/assets/admin-dashboard-example.png)

## 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`:

```js
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:

```js
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](/firestore-record-acknowldegements/reference) 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:

```js
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:

```js
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:

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

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

```js
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:

```js
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:

```js
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.