Choose a version:

Device API

The Device API provides access to device information and capabilities, allowing you to retrieve device details, check device types, and adapt your extension behavior based on the POS hardware characteristics. The API enables device-aware functionality and responsive design based on device form factors.

Use cases

Responsive design: Implement responsive design that adapts based on device form factor.
Device information: Display device-specific information for troubleshooting or support.
Device-aware features: Customize user experiences based on device capabilities.
Usage tracking: Track device usage patterns for analytics or optimization.

Support

Targets (17)

Supported targets

Anchor to propertiesProperties

The DeviceApi object provides access to device information and capabilities. Access these properties through api.device to retrieve device details and check device characteristics.

Anchor to getDeviceId getDeviceId () => Promise<string> required: Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations.
Anchor to isTablet isTablet () => Promise<boolean> required: Determines whether the device is a tablet form factor. Returns a promise that resolves to true for tablets, false for other device types. Use for implementing responsive design, optimizing touch targets, or providing device-appropriate user experiences.
Anchor to name name string required: The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful.

Examples

import React, { useState } from 'react';

import {

Tile,

useApi,

reactExtension,

} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {

const api = useApi<'pos.home.tile.render'>();

return (

<Tile

title='My App'

enabled={api.device.isTablet()}

/>

);

};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

Examples

Check if the device is a tablet

Description

Check whether the extension is running on a tablet form factor. This example uses the `isTablet` property to determine the device type, allowing you to adapt layouts, adjust component sizing, or enable tablet-specific features for larger screen experiences.

React

import React, { useState } from 'react';
import {
  Tile,
  useApi,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile
      title='My App'
      enabled={api.device.isTablet()}
    />
  );
};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

TS

import {
  Tile,
  Screen,
  Navigator,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    enabled: api.device.isTablet(),
  });

  root.append(tile);
});

Get the device ID

Description

Retrieve the unique identifier for the device running your extension. This example accesses the device ID, enabling device-specific tracking, settings synchronization, or associating actions with specific POS terminals for audit trails and analytics.

React

import React, { useState } from 'react';
import {
  Tile,
  useApi,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile
      title='My App'
      subtitle={api.device.getDeviceId()}
      enabled
    />
  );
};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

TS

import {
  Tile,
  Screen,
  Navigator,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: api.device.getDeviceId(),
    enabled: true,
  });

  root.append(tile);
});

Get the device name

Description

Retrieve the human-readable name of the device running your extension. This example accesses the device's name, which can be useful for debugging, analytics, device-specific customization, or displaying device information to staff members.

React

import React, { useState } from 'react';
import {
  Tile,
  useApi,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile
      title='My App'
      subtitle={api.device.name}
      enabled
    />
  );
};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

TS

import {
  Tile,
  Screen,
  Navigator,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: api.device.name,
    enabled: true,
  });

  root.append(tile);
});

Anchor to best-practicesBest practices

Handle async device queries: Handle the Promise-based device methods with async/await or .then() patterns, and implement appropriate error handling for device query failures.
Cache device information appropriately: Consider caching device information after the initial query to avoid repeated async calls, but ensure you handle cases where device characteristics might change during the session.
Provide device-appropriate experiences: Design different user experiences for tablets versus other devices, taking advantage of larger screens while ensuring functionality works across all supported device types.

Anchor to limitationsLimitations

Device information queries are asynchronous and may take time to resolve, so always handle the Promise-based responses appropriately in your extension logic.
The Device API provides read-only access to device information and can't be used to modify device settings or capabilities.
Device type detection is limited to basic form factor identification (tablet vs. non-tablet) and doesn't provide detailed hardware specifications or capabilities.

Was this page helpful?