App checklist

Our own apps follow this list. Their source shows how.

Sign-inCopy Anchor Link

• Open OAuth in the system browser, not in a web view.
• Send a random state with each OAuth request. Reject a callback whose state does not match.
• On a TV, show the device-link code large and poll every few seconds. When the code expires, offer a new one.
• Keep the token in the platform’s secure store, such as Keychain or Keystore.
• Sign the person out only on a 401 or when they ask. Keep the token on network errors, 429 and 5xx.

PlaybackCopy Anchor Link

• Resume from start_from when the account has use_start_from on, and offer to start over.
• Prefer HLS. When a file needs an MP4, show the conversion progress and stop polling when the screen closes.
• Load subtitles from /files/{id}/subtitles in the account’s languages.
• Keep the video playing when a subtitle or audio track fails to load.
• When a stream URL expires, fetch a new one once before you show an error.

Files and transfersCopy Anchor Link

• Page long lists with per_page and the /continue endpoints.
• Poll transfers only while your app is on screen.
• Respect trash_enabled, and confirm before you delete anything for good.
• Download to the person’s own device, not through your servers. Downloads from many addresses look like a shared account.
• Keep offline copies across restarts, and free the space when the person removes one.

TVCopy Anchor Link

• Show one clear focus at a time.
• Back closes the top layer first, and focus returns to where the person was.
• A playback error always offers a way back.

Errors and privacyCopy Anchor Link

• On a 429, wait until X-RateLimit-Reset. If X-RateLimit-Action is captcha-needed, send the person to put.io to clear it.
• Time out requests, and retry only a few times.
• Show a readable message, never raw API error text.
• Keep tokens, file names, URLs and search text out of logs, crash reports and analytics.