OptiSigns

https://docs.optisigns.com
Admin
OptiSigns is a digital signage platform and API that enables users to manage digital displays,...
Tokens:5,502
Snippets:62
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Device Management Example

Source: https://docs.optisigns.com/cookbook/sdk

A comprehensive example showing device listing, creation, and updating.

```typescript
import { OptiSigns } from "@optisigns/optisigns";

async function manageDevices() {
  const client = new OptiSigns("YOUR_API_KEY");

  try {
    // List all devices
    const devices = await client.devices.listAllDevices();

    // Create a new device
    const newDevice = await client.devices.createDevice({
      deviceName: "Reception Screen",
      orientation: "LANDSCAPE",
    });

    // Update device name
    await client.devices.updateDevice(newDevice.id, {
      deviceName: "Updated Screen Name",
    });
  } catch (error) {
    console.error("Error:", error);
  }
}
```

--------------------------------

### Install OptiSigns SDK

Source: https://docs.optisigns.com/cookbook/sdk

Install the package via npm.

```bash
npm install @optisigns/optisigns
```

--------------------------------

### Asset Management Example

Source: https://docs.optisigns.com/cookbook/sdk

A comprehensive example showing asset uploading, website creation, and settings modification.

```typescript
import { OptiSigns } from "@optisigns/optisigns";

async function manageAssets() {
  const client = new OptiSigns("YOUR_API_KEY");

  try {
    // Upload a new asset
    const asset = await client.assets.uploadFileAsset(
      "./path/to/image.jpg",
      "team_id"
    );

    // Create a website asset
    const websiteAsset = await client.assets.createWebsiteAppAsset(
      {
        url: "https://example.com",
        title: "Company Website",
      },
      "team_id"
    );

    // Modify asset settings
    await client.assets.modifyAssetSettings(
      asset.id,
      {
        name: "Updated Asset Name",
      },
      "team_id"
    );
  } catch (error) {
    console.error("Error:", error);
  }
}
```

--------------------------------

### GraphQL Cursor-Based Pagination

Source: https://docs.optisigns.com/fundamental/pagination

Example query demonstrating how to fetch a paginated list of devices using the 'first' and 'after' parameters.

```APIDOC
## GraphQL Query: devices

### Description
Fetches a paginated list of devices using cursor-based pagination.

### Parameters
- **first** (Int) - Optional - The number of items to retrieve from the start of the list.
- **after** (String) - Optional - The cursor to start fetching items after.
- **before** (String) - Optional - The cursor to start fetching items before.
- **last** (Int) - Optional - The number of items to retrieve from the end of the list.

### Request Example
```graphql
query {
  devices(query: {}, first: 1, after: "YXJyYXljb25uZWQwaW9uOjQ=") {
    page {
      edges {
        cursor
        node {
          id
          deviceName
          UUID
          pairingCode
          currentType
          currentAssetId
          currentPlaylistId
          localAppVersion
        }
      }
      pageInfo {
        hasNextPage
        startCursor
        endCursor
      }
    }
    pageData {
      limit
      offset
    }
  }
}
```

### Response
#### Success Response (200)
- **page** (Object) - Contains the edges and pageInfo metadata.
- **pageData** (Object) - Contains limit and offset information.

#### Response Example
```json
{
  "data": {
    "devices": {
      "page": {
        "edges": [
          {
            "cursor": "YXJyYXljb25uZWQwaW9uOjU=",
            "node": {
              "id": "603b0673b16b4c0012c120a3",
              "deviceName": "Android_Auto",
              "UUID": "85308fe5-b5b1-488e-a75b-8a694814b86d",
              "pairingCode": "vpLtH2",
              "currentType": "Asset",
              "currentAssetId": "Z9vkZzbAkEFsnjjtg",
              "currentPlaylistId": null,
              "localAppVersion": "4.2.23"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "startCursor": "YXJyYXljb25uZWQwaW9uOjU=",
          "endCursor": "YXJyYXljb25uZWQwaW9uOjU="
        }
      },
      "pageData": {
        "limit": 1,
        "offset": 0
      }
    }
  }
}
```
```

--------------------------------

### Get Device by ID

Source: https://docs.optisigns.com/cookbook/sdk

Retrieve details for a specific device using its unique identifier.

```typescript
const device = await client.devices.getDeviceById("device_id");
```

--------------------------------

### Initialize OptiSigns Client

Source: https://docs.optisigns.com/cookbook/sdk

Initialize the SDK with your API key obtained from account settings.

```typescript
import { OptiSigns } from "@optisigns/optisigns";

const client = new OptiSigns("YOUR_API_KEY");
```

--------------------------------

### Create New Device

Source: https://docs.optisigns.com/cookbook/sdk

Register a new device with a specified name and orientation.

```typescript
const newDevice = await client.devices.createDevice({
  deviceName: "Reception Screen",
  orientation: "LANDSCAPE",
});
```

--------------------------------

### client.devices.createDevice(params)

Source: https://docs.optisigns.com/cookbook/sdk

Registers a new digital signage device.

```APIDOC
## client.devices.createDevice(params)

### Description
Creates a new device with the specified configuration.

### Parameters
- **params** (object) - Required - Contains `deviceName` (string) and `orientation` (string: "LANDSCAPE" or "PORTRAIT")
```

--------------------------------

### client.devices.pushContentToDevice(deviceId, contentId, teamId, schedule)

Source: https://docs.optisigns.com/cookbook/sdk

Deploys specific content to a target device.

```APIDOC
## client.devices.pushContentToDevice(deviceId, contentId, teamId, schedule)

### Description
Triggers content deployment to a specific device.

### Parameters
- **deviceId** (string) - Required
- **contentId** (string) - Required
- **teamId** (string) - Required
- **schedule** (string) - Required - Timing parameter (e.g., "NOW")
```

--------------------------------

### client.devices.listAllDevices()

Source: https://docs.optisigns.com/cookbook/sdk

Retrieves a list of all digital signage devices associated with the account.

```APIDOC
## client.devices.listAllDevices()

### Description
Fetches all devices registered to the authenticated account.

### Signature
`await client.devices.listAllDevices()`
```

--------------------------------

### query { devices }

Source: https://docs.optisigns.com/quickstart

Fetches a list of all devices associated with the account, including details like device name, UUID, and current status.

```APIDOC
## GraphQL Query: devices

### Description
Fetch all devices in your account.

### Request Example
```graphql
query{
  devices (query : {}) {
    page{
      edges{
        cursor,
        node{
          _id,
          deviceName,
          UUID,
          pairingCode,
          currentType,
          currentAssetId,
          currentPlaylistId,
          localAppVersion,
        }
      }
    }
  }
}
```

### Response Example
```json
{
  "data": {
    "devices": {
      "page": {
        "edges": [
          {
            "cursor": "YXJyYXljb2luZW50aW9uOjA=",
            "node": {
              "_id": "G158712f0e404274e7300e7f",
              "deviceName": "TOMATO",
              "UUID": "c1af1246-d1c8-3e7c-a04b-9914579f5342",
              "pairingCode": "5MMESU",
              "currentType": "asset",
              "currentAssetId": "TQ7d4Nc4kZhjwF29F",
              "currentPlaylistId": null,
              "localAppVersion": "5.5.8"
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### List All Devices

Source: https://docs.optisigns.com/cookbook/sdk

Retrieve a list of all devices associated with the account.

```typescript
const devices = await client.devices.listAllDevices();
```

--------------------------------

### Create Website Asset

Source: https://docs.optisigns.com/cookbook/sdk

Create a website application asset for a specific team.

```typescript
const websiteAsset = await client.assets.createWebsiteAppAsset(
  {
    url: "https://example.com",
    title: "Company Website",
  },
  "team_id"
);
```

--------------------------------

### List All Devices Query

Source: https://docs.optisigns.com/quickstart

Retrieves a list of all devices associated with the account, including their status and identifiers.

```graphql
query{
  devices (query : {}) {
    page{
      edges{
        cursor,
        node{
          _id,
          deviceName,
          UUID,
          pairingCode,
          currentType,
          currentAssetId,
          currentPlaylistId,
          localAppVersion,
        }
      }
    }
  }
}
```

```json
{
  "data": {
    "devices": {
      "page": {
        "edges": [
          {
            "cursor": "YXJyYXljb2luZW50aW9uOjA=",
            "node": {
              "_id": "G158712f0e404274e7300e7f",
              "deviceName": "TOMATO",
              "UUID": "c1af1246-d1c8-3e7c-a04b-9914579f5342",
              "pairingCode": "5MMESU",
              "currentType": "asset",
              "currentAssetId": "TQ7d4Nc4kZhjwF29F",
              "currentPlaylistId": null,
              "localAppVersion": "5.5.8"
            }
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Push Content to Screen

Source: https://docs.optisigns.com/cookbook/sdk

Assign content to a specific device for immediate display.

```typescript
await client.devices.pushContentToDevice(
  "device_id",
  "content_id",
  "team_id",
  "NOW"
);
```

--------------------------------

### query { assets }

Source: https://docs.optisigns.com/quickstart

Retrieves details for specific assets filtered by their original filename.

```APIDOC
## GraphQL Query: assets

### Description
Retrieve asset details by filename.

### Parameters
#### Query Parameters
- **query** (Object) - Required - Filter criteria, e.g., {originalFileName: "string"}

### Request Example
```graphql
query{
  assets (query : {originalFileName:"Sample Image 1.JPG"}) {
    page{
      edges{
        cursor,
        node{
          _id,
          appType,
          fileType,
          name,
          filename
        }
      }
    }
  }
}
```

### Response Example
```json
{
  "data": {
    "assets": {
      "page": {
        "edges": [
          {
            "cursor": "YXJyYXljb2luZW50aW9uOjA=",
            "node": {
              "_id": "fAzD64mkENvCtde3p",
              "appType": null,
              "fileType": "image",
              "name": null,
              "filename": "Sample Image 1.JPG"
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Fetch Specific Assets Query

Source: https://docs.optisigns.com/quickstart

Retrieves details for a specific asset filtered by its original filename.

```graphql
query{
  assets (query : {originalFileName:"Sample Image 1.JPG"}) {
    page{
      edges{
        cursor,
        node{
          _id,
          appType,
          fileType,
          name,
          filename
        }
      }
    }
  }
}
```

```json
{
  "data": {
    "assets": {
      "page": {
        "edges": [
          {
            "cursor": "YXJyYXljb2luZW50aW9uOjA=",
            "node": {
              "_id": "fAzD64mkENvCtde3p",
              "appType": null,
              "fileType": "image",
              "name": null,
              "filename": "Sample Image 1.JPG"
            }
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Find Device by Name

Source: https://docs.optisigns.com/cookbook/sdk

Search for a specific device using its name.

```typescript
const device = await client.devices.findByDeviceName("Reception");
```

--------------------------------

### client.assets.uploadFileAsset(path, teamId)

Source: https://docs.optisigns.com/cookbook/sdk

Uploads a local file as an asset to the specified team.

```APIDOC
## client.assets.uploadFileAsset(path, teamId)

### Description
Uploads a file from the local filesystem to the OptiSigns platform.

### Parameters
- **path** (string) - Required - Local file path.
- **teamId** (string) - Required - The ID of the team to associate the asset with.
```

--------------------------------

### Update Screen via GraphQL

Source: https://docs.optisigns.com/fundamental/Update-Screen

Use the updateDevice mutation to modify screen properties such as the device name, assigned asset, and orientation.

```graphql
mutation {
  updateDevice(
    _id: "SCREEN_ID",
    payload: {
      deviceName: "New Screen Name",
      currentType: ASSET,
      currentAssetId: "ASSET_ID",
      orientation: LANDSCAPE
    }
  ) {
    _id
    deviceName
    currentType
    currentAssetId
  }
}
```

--------------------------------

### Fetch paginated devices query

Source: https://docs.optisigns.com/fundamental/pagination

Use this GraphQL query to retrieve a specific number of devices after a defined cursor.

```graphql
query {
  devices(query: {}, first: 1, after: "YXJyYXljb25uZWQwaW9uOjQ=") {
    page {
      edges {
        cursor
        node {
          id
          deviceName
          UUID
          pairingCode
          currentType
          currentAssetId
          currentPlaylistId
          localAppVersion
        }
      }
      pageInfo {
        hasNextPage
        startCursor
        endCursor
      }
    }
    pageData {
      limit
      offset
    }
  }
}
```

--------------------------------

### mutation updateDevice

Source: https://docs.optisigns.com/fundamental/Update-Screen

Updates a paired screen's name, assigned content, and orientation using the updateDevice GraphQL mutation.

```APIDOC
## mutation updateDevice

### Description
Use the `updateDevice` mutation to rename a paired screen or assign an asset or playlist to it.

### Operation
`mutation`

### Arguments
- **_id** (String) - Required - The unique ID of the screen.
- **payload** (Object) - Required - The configuration object for the screen.
  - **deviceName** (String) - Optional - The new name for the screen.
  - **currentType** (Enum) - Optional - The type of content (e.g., ASSET).
  - **currentAssetId** (String) - Optional - The ID of the asset or playlist to assign.
  - **orientation** (Enum) - Optional - The screen orientation (e.g., LANDSCAPE).

### Request Example
```graphql
mutation {
  updateDevice(
    _id: "SCREEN_ID",
    payload: {
      deviceName: "New Screen Name",
      currentType: ASSET,
      currentAssetId: "ASSET_ID",
      orientation: LANDSCAPE
    }
  ) {
    _id
    deviceName
    currentType
    currentAssetId
  }
}
```
```

--------------------------------

### Upload File Asset

Source: https://docs.optisigns.com/cookbook/sdk

Upload a local file as an asset to a specific team.

```typescript
const asset = await client.assets.uploadFileAsset(
  "./path/to/image.jpg",
  "team_id"
);
```

--------------------------------

### Update Device

Source: https://docs.optisigns.com/cookbook/sdk

Modify the properties of an existing device.

```typescript
await client.devices.updateDevice("device_id", {
  deviceName: "Updated Screen Name",
});
```

--------------------------------

### Authenticate API Requests with Bearer Token

Source: https://docs.optisigns.com/generate-api-key

Include the generated API key in the HTTP Authorization header to authenticate requests.

```bash
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Handle API Errors

Source: https://docs.optisigns.com/cookbook/sdk

Wrap SDK calls in try-catch blocks to handle potential errors.

```typescript
try {
  const devices = await client.devices.listAllDevices();
  console.log(devices);
} catch (error) {
  console.error("Error fetching devices:", error);
}
```

--------------------------------

### Modify Asset Settings

Source: https://docs.optisigns.com/cookbook/sdk

Update the settings or metadata of an existing asset.

```typescript
await client.assets.modifyAssetSettings(
  "asset_id",
  {
    name: "Updated Asset Name",
    metadata: { key: "value" },
  },
  "team_id"
);
```

--------------------------------

### Reboot Device

Source: https://docs.optisigns.com/cookbook/sdk

Trigger a remote reboot for a specific device.

```typescript
await client.devices.rebootDevice("device_id");
```

--------------------------------

### GraphQL Error Response Format

Source: https://docs.optisigns.com/fundamental/Error-Handling

Standard structure for GraphQL error responses, including validation and business logic errors.

```APIDOC
## GraphQL Error Response

### Description
GraphQL operations return errors in a standardized format. Each response may include an `errors` array containing a `message` and `extensions` metadata.

### Response Structure
- **errors** (array) - List of error objects
  - **message** (string) - Human-readable error description
  - **extensions** (object) - Additional metadata and error codes

### Example: GraphQL Validation Error
```json
{
  "errors": [
    {
      "message": "Cannot query field \"UID\" on type \"Device\". Did you mean \"UUID\" or \"_id\"?",
      "locations": [
        {
          "line": 5,
          "column": 5
        }
      ],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}
```

### Example: Device Already Paired Error
```json
{
  "errors": [
    {
      "message": "This device is already paired",
      "extensions": {
        "code": "406",
        "response": {
          "statusCode": 406,
          "message": "This device is already paired",
          "error": "Not Acceptable"
        }
      }
    }
  ],
  "data": null
}
```
```

--------------------------------

### Paginated response structure

Source: https://docs.optisigns.com/fundamental/pagination

The JSON response format containing the requested nodes, cursor information, and pagination metadata.

```json
{
  "data": {
    "devices": {
      "page": {
        "edges": [
          {
            "cursor": "YXJyYXljb25uZWQwaW9uOjU=",
            "node": {
              "id": "603b0673b16b4c0012c120a3",
              "deviceName": "Android_Auto",
              "UUID": "85308fe5-b5b1-488e-a75b-8a694814b86d",
              "pairingCode": "vpLtH2",
              "currentType": "Asset",
              "currentAssetId": "Z9vkZzbAkEFsnjjtg",
              "currentPlaylistId": null,
              "localAppVersion": "4.2.23"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "startCursor": "YXJyYXljb25uZWQwaW9uOjU=",
          "endCursor": "YXJyYXljb25uZWQwaW9uOjU="
        }
      },
      "pageData": {
        "limit": 1,
        "offset": 0
      }
    }
  }
}
```

--------------------------------

### Handle Business Logic Errors

Source: https://docs.optisigns.com/fundamental/Error-Handling

Represents a domain-specific error, such as a device pairing conflict, containing metadata in the extensions field.

```json
{
  "errors": [
    {
      "message": "This device is already paired",
      "extensions": {
        "code": "406",
        "response": {
          "statusCode": 406,
          "message": "This device is already paired",
          "error": "Not Acceptable"
        }
      }
    }
  ],
  "data": null
}
```

--------------------------------

### Delete Device

Source: https://docs.optisigns.com/cookbook/sdk

Remove a device from the account using its ID and team ID.

```typescript
await client.devices.deleteDeviceById("device_id", "team_id");
```

--------------------------------

### Handle GraphQL Validation Errors

Source: https://docs.optisigns.com/fundamental/Error-Handling

Represents a schema validation failure when querying non-existent fields.

```json
{
  "errors": [
    {
      "message": "Cannot query field \"UID\" on type \"Device\". Did you mean \"UUID\" or \"_id\"?",
      "locations": [
        {
          "line": 5,
          "column": 5
        }
      ],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}
```
Tokens:
Raw