@onairosofficial/onairos-capacitor

Capacitor-first Onairos SDK package for React, Vite, iOS, and Android apps.

The package root exports the Capacitor-safe SDK entry:

import { OnairosButton, SUPPORTED_PLATFORMS } from '@onairosofficial/onairos-capacitor';

Install

npm install @onairosofficial/onairos-capacitor
npm install @capacitor/core @capacitor/app @capacitor/browser @capgo/capacitor-social-login
npx cap sync ios

The package includes the Capacitor iOS plugin files for native WKWebView connectors such as Spotify and ChatGPT. Consumers do not need to install a separate Onairos native connector package.

Build This Package

npm install
npm run build

The default build is Capacitor-only and produces:

dist/onairos.capacitor.esm.js
dist/onairos.capacitor.esm.turbopack.js

Use npm run build:protected when you want the optional obfuscated production bundle.

Vite Setup

// vite.config.ts
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const appNodeModules = path.resolve(__dirname, 'node_modules');

export default defineConfig({
  plugins: [react()],
  resolve: {
    dedupe: ['react', 'react-dom', 'react/jsx-runtime'],
    alias: {
      react: path.resolve(appNodeModules, 'react'),
      'react-dom': path.resolve(appNodeModules, 'react-dom'),
      'react/jsx-runtime': path.resolve(appNodeModules, 'react/jsx-runtime.js'),
    },
  },
  optimizeDeps: {
    include: ['react', 'react-dom', 'react/jsx-runtime'],
    exclude: ['@onairosofficial/onairos-capacitor'],
  },
});

When testing through a local file: link, the React dedupe block is important: it keeps the SDK and host app on the same React instance so hooks render correctly in WKWebView.

Capacitor Setup

npm run build
npx cap sync ios
npx cap open ios

Recommended iOS server scheme:

// capacitor.config.ts
server: {
  iosScheme: 'https',
}

Register an app URL scheme for OAuth returns in ios/App/App/Info.plist, then pass the same scheme to the SDK as returnLink:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

returnLink="myapp://oauth-callback"

This is what brings users back from OAuth connectors like YouTube, TikTok, Pinterest, and Reddit into the UniversalOnboarding connector screen.

Google Sign-In

A packaged Capacitor project is a native mobile app for Google OAuth. It does not need to be listed in the App Store or Google Play, but the developer must create native OAuth credentials for the app's identity:

• iOS: create an iOS OAuth client using the exact bundle ID from capacitor.config.* (appId).
• Android: create an Android OAuth client using the same package name plus the SHA-1 fingerprint of the debug or release signing certificate.

The developer passes only those native client IDs to the SDK:

import { updateGoogleClientIds } from '@onairosofficial/onairos-capacitor';

updateGoogleClientIds({
  iosClientId: import.meta.env.VITE_ONAIROS_GOOGLE_IOS_CLIENT_ID,
  androidClientId: import.meta.env.VITE_ONAIROS_GOOGLE_ANDROID_CLIENT_ID,
});

Do not set webClientId or serverClientId to an iOS or Android client ID. Since 0.1.3, the SDK owns those values and defaults both to the Onairos web OAuth client that the backend verifies. The native client identifies the installed app; the web/server client is the ID token's aud value. Mixing them causes Google token audience mismatch.

Google Cloud setup

1. Configure the OAuth consent screen in the Google Cloud project used for the native app.
2. For iOS, create an iOS OAuth client using the exact appId/bundle ID. Add Google's reversed iOS client ID as a URL scheme in ios/App/App/Info.plist, then run npx cap sync ios.
3. For Android, create an Android OAuth client using the exact appId/package name and signing SHA-1. Use cd android && ./gradlew signingReport (or .\gradlew signingReport on Windows) to obtain the debug SHA-1, and create a separate credential for the production signing key. Add the Google-generated native configuration required by @capgo/capacitor-social-login, then run npx cap sync android.
4. Keep native client IDs in environment configuration. They are OAuth identifiers rather than client secrets, but environment configuration prevents accidental cross-app reuse.

The app does not need to be published in either store for these credentials to work in local development, TestFlight, or internal testing.

Basic Usage

import { OnairosButton } from '@onairosofficial/onairos-capacitor';

export default function App() {
  return (
    <OnairosButton
      webpageName="My Capacitor App"
      requestData={['email', 'profile', 'preferences', 'personality']}
      allowedPlatforms={null}
      recommendedPlatforms={['Spotify', 'ChatGPT', 'YouTube', 'TikTok']}
      apiKey={import.meta.env.VITE_ONAIROS_API_KEY}
      returnLink="myapp://oauth-callback"
      trainingScreenMode="fast"
      onComplete={(result) => {
        console.log('Onairos complete:', result);
      }}
    />
  );
}

Connectors Included

ChatGPT, YouTube, LinkedIn, Pinterest, Reddit, Spotify, and TikTok.

Temporarily paused behind TEMP_DISABLED_CONNECTORS: Claude, Gemini, Grok, Perplexity, Sephora, InstagramData, Gmail, Hinge, and Netflix. These implementations are still in the codebase and can be re-enabled once the mobile connector UX is ready.

Connector IDs are exported in SUPPORTED_PLATFORMS.

In native Capacitor builds, Spotify uses the React Native-style WKWebView scraping connector, not the web SDK Chromium hosted connector path. The SDK looks for OnairosSpotifyNative.connectSpotifyNative() and stores data through /platform-data/store as mobile-spotify. The local test plugin includes ChatGPT and Spotify native iOS implementations; Netflix remains in the native package as a clear stub but is temporarily hidden from the SDK picker.

Training uses the same backend pipeline as the web/RN SDK. trainingScreenMode="fast" shows the mobile-style loading screen and resolves when fast traits are ready; use "real" to wait for full model training or "none" with backgroundLoadData when the host app owns the loading state.

Use requestData={['email', 'profile', 'preferences', 'personality']} for the standard personalization/training flow. Add rawMemories only for apps approved for raw-memory export; otherwise raw-export connectors can be hidden by policy.

Publish

The package version is declared in package.json. Run the release checks before publishing:

npm install
npm run build
npm run test:package
npm publish

The package is currently prepared as 0.1.3.

Local Test App

This repo includes test-app, a Vite + Capacitor app that links to this package by local file dependency:

cd test-app
npm install
npm run ios:open

npm run ios:open builds the Vite app, syncs Capacitor, and opens the iOS project in Xcode.

For local development, create test-app/.env.local with:

VITE_ONAIROS_API_KEY=...
VITE_ONAIROS_GOOGLE_IOS_CLIENT_ID=...
VITE_ONAIROS_GOOGLE_ANDROID_CLIENT_ID=...

.env.local and generated Capacitor web assets are intentionally ignored so secrets do not get committed.