Clipboard Access in Alien Mini Apps: useClipboard Hook

The Alien SDK reads and writes the clipboard through the host app’s native clipboard API. This works reliably across iOS and Android, unlike browser clipboard APIs which are restricted in WebViews.

Quick Start


 
function CopyButton({ text }: { text: string }) {
  const { writeText, readText, isReading } = useClipboard();
 
  return (
    <div>
      <button onClick={() => writeText(text)}>Copy</button>
      <button onClick={async () => {
        const r = await readText();
        if (r.ok) console.log('Clipboard:', r.text);
      }}>
        {isReading ? 'Reading…' : 'Paste'}
      </button>
    </div>
  );
}

writeText is fire-and-forget. readText resolves a discriminated ClipboardReadResult so you can tell apart a successful read, a denied permission, and a transport failure.

Return Values

Property	Type	Description
`writeText`	`(text: string) => void`	Copy text to the clipboard
`readText`	`() => Promise<ClipboardReadResult>`	Read from the clipboard
`isReading`	`boolean`	`true` while a read is in progress
`errorCode`	`ClipboardErrorCode \| null`	Code from the last failed read
`error`	`BridgeError \| null`	Bridge error from the last failed read
`callable`	`boolean`	`true` if the host supports clipboard read and write

errorCode and error are two separate channels: errorCode is a host-domain refusal (permission_denied / unavailable), while error is a bridge-level failure (no bridge, host too old, timeout).

Options


const clipboard = useClipboard({ timeout: 10000 });

Option	Type	Default	Description
`timeout`	`number`	`5000`	Timeout in ms for read operations

Reading the Clipboard

readText() resolves one of three shapes:


type ClipboardReadResult =
  | { ok: true; text: string }                    // success (text may be '')
  | { ok: false; errorCode: ClipboardErrorCode }  // host refused
  | { ok: false; error: BridgeError };            // bridge failure

Branch on it once and every case is handled:


const r = await readText();
 
if (r.ok) {
  console.log('Clipboard:', r.text);
} else if (r.errorCode) {
  console.warn('Refused:', r.errorCode); // permission_denied | unavailable
} else {
  console.warn('Bridge error:', r.error.message);
}

Error Codes

Code	Description
`permission_denied`	The user denied clipboard access
`unavailable`	Clipboard is not available on this device

Bridge API

For non-React apps, use the bridge directly.

Write to Clipboard

Fire-and-forget — no response event.


 
send('clipboard:write', { text: 'Hello!' });

Read from Clipboard

Request-response with clipboard:response.


 
const response = await request(
  'clipboard:read',
  {},
  'clipboard:response',
  { timeout: 5000 }, // bare request() defaults to 30000ms; the hook defaults to 5000
);
 
if (response.text !== null) {
  console.log('Clipboard content:', response.text);
} else {
  console.error('Clipboard error:', response.errorCode);
}

The raw clipboard:response payload:


{
  reqId: string;
  text: string | null;
  errorCode?: 'permission_denied' | 'unavailable';
}

On success: text holds the content (may be an empty string), no errorCode
On failure: text is null, errorCode gives the reason

Version Requirements

Clipboard methods are available since contract version 0.1.1. To gate your UI on host support, read callable from the hook, or use useCallable directly:


 
const c = useCallable('clipboard:write');
if (!c.callable && c.reason === 'host-outdated') {
  return <p>Update the Alien app to use clipboard features.</p>;
}

Next Steps

Haptic Feedback — haptic feedback
Link Management — open URLs through the host app
Payments — accept payments
Bridge Reference — full bridge API reference