User files and data storage

Run the existing file example first#

1. Build the complete toolkit using the quickstart, then select the paired Novel Reader component from PhoneSDK and novel_reader from GlassSDK in Studio.
2. Prepare a small TXT file with content suitable for sharing, import it through the page's file picker, and confirm reading works on both phone and glasses.
3. Stop and re-enter, then check the library and reading position. Cancel a file-selection attempt and confirm the page remains usable.
4. Scan on the phone and repeat these steps with its file picker. Computer files do not automatically appear in the phone's library.

• First run and build steps
• Application identity and pairing rules

Where to store the three types of data#

Read a size-limited TXT preview#

Add this function to an existing plugin.js. Create gm and complete gm.ready(), then call readTextPreview(gm, signal) from a user click handler, catch errors, and show the result. signal comes from AbortController and cancels this read. Call abort() when the user cancels reading or exits the feature. The user still cancels the file picker through the system UI.

Preview only the first 64 KiB, decoding UTF-8 characters across chunk boundaries. A null result means the user canceled selection; truncated means some content remains unread. For a complete reader, follow Novel Reader's encoding detection, segment indexing, and on-demand reads.

export async function readTextPreview(gm, signal) {
  const { files } = await gm.files.pick({
    extensions: ['txt'], allowMultiple: false,
  });
  const file = files[0];
  if (!file) return null; // The user cancelled.
  if (file.size === 0) return { file, text: '', truncated: false };

  const opened = await gm.files.openRead(file.fileId, {
    offset: 0, length: Math.min(file.size, 64 * 1024), signal,
  });
  const reader = opened.stream.getReader();
  const decoder = new TextDecoder('utf-8');
  let text = '';
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      text += decoder.decode(value, { stream: true });
    }
    const truncated = opened.length < file.size;
    if (!truncated) text += decoder.decode();
    return { file, text, truncated };
  } finally {
    try { await reader.cancel(); } catch { /* Already closed or aborted. */ }
    reader.releaseLock();
  }
}

Check the return structure when reading settings#

gm.storage.get(key) returns an object with a value field; value is null if nothing was saved. Version your settings structure, then validate and migrate old data when reading. Do not treat the entire object resolved by the Promise as the settings value.

await gm.storage.set('reader-preferences', { schema: 1, fontScale: 1 });
const { value } = await gm.storage.get('reader-preferences');
if (value?.schema === 1 && typeof value.fontScale === 'number') {
  console.log('saved font scale', value.fontScale);
}

File quotas and read ranges#

Checks for deletion, cancellation and updates#

• An empty array from files.pick is normal cancellation, not “Import failed”. Files have already been copied into the application's private area; canceling a later read does not undo the import.
• Releasing the reader lock does not cancel the stream. When ending a read early, call reader.cancel() or AbortController.abort() and handle completion of any pending read().
• Delete with files.delete(fileId) and clean up your saved index or reading position. Deleting the App's private copy does not delete the original file selected by the user.
• After updating the same installation, revalidate saved-data structures and fileId values. Offer file selection again if a file has been removed.
• Read streams and large files do not pass through JSON/Base64. Save only the required index and current position; avoid concatenating hundreds of MiB of content.

• Data isolation and updates
• Backgrounding and session recreation

Reference files in the toolkit#

• PhoneSDK/packages/web-sdk/src/index.d.ts
• PhoneSDK/examples/novel-reader/reader-file.js
• PhoneSDK/examples/novel-reader/manifest.json
• PhoneSDK/examples/permission-debug/plugin.js