---
sidebar_position: 0
---

# proofOfPlay

The `sos.proofOfPlay` API provides methods for recording information about played content on the device.

Can be useful for tracking the playback of content, which can be used for analytics, reporting, or debugging purposes.

## Methods

### recordItemPlayed()

The `recordItemPlayed()` method dispatches a `sos.command.dispatch()` command. It sends provided information about played content along
with additional metadata about current applet and device to signageOS.

```ts expandable
recordItemPlayed(options: IRecordItemOptions): Promise<void>;
// show-more
interface IRecordItemOptions {
    name: string;
    customId?: string;
    type?: 'video' | 'image' | 'html' | 'custom';
    tags?: string[];
    fileName?: string;
    playbackSuccess?: boolean;
    errorMessage?: string;
}

```

#### Params

| Name                      | Type                                                    | Required         | Description                                                                                                  |
|---------------------------|---------------------------------------------------------|------------------|--------------------------------------------------------------------------------------------------------------|
| `options`                 | `IRecordItemOptions`                                    |  <div>Yes</div>  | The options for recording the played item.                                                                   |
| `options.name`            | `string`                                                |  <div>Yes</div>  | The name of the item that was played.                                                                        |
| `options.customId`        | `string \| undefined`                                   |  <div>No</div>   | An optional custom identifier for the item.                                                                  |
| `options.type`            | `"video" \| "image" \| "html" \| "custom" \| undefined` |  <div>No</div>   | The type of the item that was played. It can be one of the following: `video`, `image`, `html`, or `custom`. |
| `options.tags`            | `string[] \| undefined`                                 |  <div>No</div>   | An array of tags associated with the item.                                                                   |
| `options.fileName`        | `string \| undefined`                                   |  <div>No</div>   | The name of the file that was played.                                                                        |
| `options.playbackSuccess` | `boolean \| undefined`                                  |  <div>No</div>   | A boolean indicating whether the playback was successful.                                                    |
| `options.errorMessage`    | `string \| undefined`                                   |  <div>No</div>   | An optional error message if the playback was not successful.                                                |

#### Return value

A promise that resolves when the item has been recorded.

#### Possible errors

If any of the provided options are invalid.

## API Example

```ts
import { sos } from '@signageos/front-applet';

void sos.onReady(async () => {
	await sos.proofOfPlay.recordItemPlayed({
		name: 'generic-brand-christmas-coffee-ad',
		customId: 'dBE43bFB3312VFfvd34bgGHJVV334cd2',
		type: 'video',
		tags: ['generic-brand', 'christmas'],
		fileName: 'coffee.mp4',
		playbackSuccess: false,
		errorMessage: 'Unsupported framerate 60fps',
	});
});

```