Native Platform APIs

Find the shipped shared and iOS service APIs, permissions, and lifecycle contracts

Services live on One when they support both native platforms, and on One.iOS when they expose an iOS capability. Hooks are named imports from one. Use each reference for the complete signature, configuration, permission behavior, event cleanup, and errors.

Shared services

One.Auth.Apple is grouped under the shared authentication namespace, but Apple authorization is an iOS operation. On Android and web, isAvailable is false and authorization calls reject.

Secure storage uses string keys and values:

import { One } from 'one'

export async function saveSession(token: string) {
  await One.SecureStore.setItem('session', token)
}

export async function readSession() {
  return One.SecureStore.getItem('session')
}

export async function clearSession() {
  await One.SecureStore.deleteItem('session')
}

A missing key reads null. SecureStore rejects on web; choose a separate web session strategy. The synchronous verbs block the JavaScript thread, so reserve them for a value needed synchronously, such as an initial session read.

iOS services

These are exported on One.iOS; they do not acquire Android implementations because the same app also uses Compose.

Widget and Live Activity APIs need a generated extension, App Group, and the relevant signing capabilities. Native project setup shows the configuration. Widgets render a supported serialized JSX layout, not an arbitrary React Native subtree.

Permissions and subscriptions

Configure native usage descriptions and capabilities before building the app, then request runtime permission from the corresponding API. A camera picker, camera preview, library picker, and Photos library management have different permission contracts. The system picker can select media without granting the app general library access.

A live network subscription returns an object with remove():

import { useEffect, useState } from 'react'
import { One } from 'one'

export function useConnectionType() {
  const [type, setType] = useState('unknown')

  useEffect(() => {
    const subscription = One.Network.addStateListener((state) => {
      setType(state.type)
    })
    return () => subscription.remove()
  }, [])

  return type
}

For a component that also needs the initial snapshot, use the exported useNetworkState hook. Other services can return an unsubscribe function or another handle; follow their own cleanup signature rather than assuming every service uses remove().

Apple authentication

One.Auth.Apple.isAvailable is a boolean. signIn accepts optional requestedScopes ('fullName' and 'email'), state, and nonce, and resolves a discriminated result. Cancellation resolves { type: 'cancel' }. On success the credential includes the user identifier and nullable identity token, authorization code, name, and email fields.

import { One } from 'one'

export async function signInWithApple() {
  if (!One.Auth.Apple.isAvailable) return null
  const result = await One.Auth.Apple.signIn({
    requestedScopes: ['fullName', 'email'],
  })
  return result.type === 'success' ? result.credential : null
}

Use getCredentialState(user) to read the credential’s current state. Enable Sign in with Apple in the app’s entitlements and signing capabilities; native.app.ios.usesAppleSignIn configures the One prebuild entitlement. Your server owns credential verification and the session it creates.

Dictation

One.Speech.isAvailable() reports native recognizer availability. getPermissions() and requestPermissions() return permission responses. After a grant, start({ lang? }, onEvent) returns a session with stop() and abort(). lang is a language tag such as en-US.

The callback receives { type, transcript, error?, message? }; type is start, transcript, end, or error. Each transcript is the whole result so far. stop() finishes with a final event, while abort() tears down the session silently. Configure native.app.speech with recognition and microphone usage descriptions before prebuild. On web, availability is false, permissions are denied, and start throws.

System actions and HTTP

One.openURL(url) and One.openSettings() return Promise<void>. One.openShare({ title?, message?, url? }) passes content to the system share surface. On web, URL opening uses a new tab, sharing needs navigator.share, and app settings are unsupported.

Native global fetch streams response bodies and accepts React Native file parts in FormData. Use its standard request and response objects; no One.fetch wrapper is required. Streaming is separate from One.Network, which reports connection state.