Onairos SDK v5.8

Connect user data to your applications with privacy-first identity sharing

The Onairos SDK enables applications to connect and communicate data with Onairos Identities via user authorization. Integration is seamless for React, Vue, Laravel, Framer, and mobile applications.

✨ Key Features

• 🔐 Privacy-First Data Sharing - Users authorize exactly what data to share
• ⚛️ React 18 & 19 Support - Full compatibility with latest React versions
• 📱 Mobile Ready - Native Capacitor support for iOS & Android
• 🎨 Laravel Integration - First-class Blade, Vue, and Vite support
• 🖼️ Framer Support - No-build CDN integration for Framer projects
• 💬 Telegram Mini Apps - Build data-connected Telegram bots
• 🔄 AutoFetch - Automatic API calls after user approval
• 📝 TypeScript - Full type definitions included
• 🎯 Test Mode - Development testing without live data

📦 Installation

npm install onairos

Peer Dependencies

# Required
npm install react react-dom

# Optional (for specific features)
npm install tailwindcss  # For styled components
npm install socket.io-client  # For real-time features

🚀 Quick Start

1. Create a Developer Account

Register at onairos.uk/dev-board to get your API key and register your domain.

2. Basic Usage (React)

import { OnairosButton } from "onairos";

function App() {
  return (
    <OnairosButton
      requestData={["email", "profile", "social"]}
      webpageName="My Application"
      onComplete={(result) => {
        console.log("User data:", result.apiResponse);
        console.log("Token:", result.token);
      }}
    />
  );
}

That's it! The button handles authentication, user consent, and data retrieval automatically.

📖 Component Reference

OnairosButton

The primary component for data requests.

<OnairosButton
  // Required
  requestData={["basic", "personality", "preferences"]}  // Data options shown on consent screen
  webpageName="My App"                 // Your app name (shown to users)
  
  // Data fetching
  autoFetch={true}                     // Auto-fetch after approval (default: true)
  inferenceData={null}                 // Input for AI model (required if using inference + autoFetch)
  
  // Mode settings
  testMode={false}                     // Enable test mode for development
  proofMode={false}                    // Enable verification proofs
  
  // Button customization
  buttonType="pill"                    // "pill" | "icon" | "rectangle"
  buttonText="Connect Data"            // Custom button text
  showIcon={true}                      // Show/hide Onairos logo
  textColor="white"                    // "black" | "white"
  
  // Auto sign-in (optional)
  autoSignIn={false}                   // Set localStorage auth after completion
  signInKey="authenticated"            // localStorage key for auth state
  redirectUrl="/dashboard"             // Redirect after completion
  
  // Callbacks
  onComplete={(result) => {
    // Always available:
    console.log("Token:", result.token);
    console.log("API URL:", result.apiUrl);
    console.log("Approved:", result.approved);
    console.log("User Data:", result.userData);
    
    // Only when autoFetch=true:
    console.log("API Response:", result.apiResponse);
  }}
/>

OnairosReconnectButton

Allow users to manage their connected data sources.

import { OnairosReconnectButton } from "onairos";

<OnairosReconnectButton
  buttonText="Manage Data Sources"
  appName="My App"
  buttonClass="custom-button-class"
  
  onComplete={(result) => {
    console.log("Connected accounts:", result.connectedAccounts);
    console.log("User data:", result.userData);
  }}
  
  onNoUserData={() => {
    console.log("No existing user data found");
  }}
/>

📊 requestData & inferenceData

requestData

Defines what data options appear on the consent screen. Users can toggle these on/off.

| Type | Description | |------|-------------| | basic | Basic profile information (required, always on) | | preferences | User preferences towards your app | | personality | Personality traits and interests | | rawMemories | Raw LLM data from connected AI apps (ChatGPT, Claude, etc.) |

inferenceData (for AI-powered recommendations)

If your requestData includes inference types (personality, preferences) AND autoFetch=true, you should provide inferenceData - the input for the AI model to generate personalized recommendations.

// ⚠️ IMPORTANT: If requestData includes inference types AND autoFetch=true,
//    provide inferenceData for AI recommendations

<OnairosButton
  requestData={["basic", "personality", "preferences"]}
  webpageName="My Store"
  autoFetch={true}
  inferenceData={[
    { text: "Wireless Headphones", category: "Electronics" },
    { text: "Running Shoes", category: "Sports" },
    { text: "Coffee Maker", category: "Kitchen" }
  ]}
  onComplete={(result) => {
    // result.apiResponse contains personalized recommendations
    console.log(result.apiResponse);
  }}
/>

autoFetch Behavior

| Scenario | What Happens | |----------|--------------| | autoFetch=true + inferenceData provided | SDK fetches personalized inference results | | autoFetch=true + no inferenceData | SDK falls back to traits-only (no inference) | | autoFetch=false | SDK returns token + apiUrl for you to make your own API call |

onComplete Result Object

{
  token: string;           // JWT for API authentication (always included)
  apiUrl: string;          // API endpoint (always included)
  approved: string[];      // Data types user approved (always included)
  userData: object;        // User data including email, connectedAccounts
  apiResponse?: object;    // Fetched data (only when autoFetch=true)
}

Copy-Paste Templates

Standard (traits only):

<OnairosButton
  requestData={["basic", "personality"]}
  webpageName="My App"
  autoFetch={true}
  onComplete={(result) => {
    console.log("Traits:", result.apiResponse);
  }}
/>

Inference + autoFetch (AI recommendations):

<OnairosButton
  requestData={["basic", "personality", "preferences"]}
  webpageName="My Store"
  autoFetch={true}
  inferenceData={[
    { text: "Product 1", category: "Category A" },
    { text: "Product 2", category: "Category B" }
  ]}
  onComplete={(result) => {
    console.log("Recommendations:", result.apiResponse);
  }}
/>

Manual fetch (host app makes API call):

<OnairosButton
  requestData={["basic", "personality"]}
  webpageName="My App"
  autoFetch={false}
  onComplete={(result) => {
    // Make your own API call with the token and URL
    fetch(result.apiUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${result.token}`
      },
      body: JSON.stringify({
        email: result.userData.email,
        approved: result.approved
      })
    });
  }}
/>

🔧 Platform Integrations

Laravel + Blade

// vite.config.js
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import { onairosLaravelPlugin } from "onairos/vite-plugin";

export default defineConfig({
  plugins: [
    laravel({
      input: ["resources/css/app.css", "resources/js/app.js"],
      refresh: true,
    }),
    onairosLaravelPlugin({ bladeSupport: true }),
  ],
});

// resources/js/app.js
import { initializeOnairosForBlade } from "onairos/blade";

document.addEventListener("DOMContentLoaded", () => {
  initializeOnairosForBlade({
    testMode: import.meta.env.DEV,
    autoDetectMobile: true,
  });
});

{{-- resources/views/dashboard.blade.php --}}
<div id="onairos-button"></div>

<script>
createOnairosButton('onairos-button', {
    requestData: ['email', 'profile'],
    webpageName: 'My Laravel App',
    onComplete: function(result) {
        console.log('Connection successful!', result);
    }
});
</script>

Laravel + Vue

// vite.config.js
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import vue from "@vitejs/plugin-vue";
import { onairosVuePlugin } from "onairos/vite-plugin";

export default defineConfig({
  plugins: [
    laravel({
      input: ["resources/css/app.css", "resources/js/app.js"],
      refresh: true,
    }),
    vue(),
    onairosVuePlugin(),
  ],
});

<!-- In your Vue component -->
<template>
  <onairos-button
    :request-data="['email', 'profile']"
    webpage-name="Laravel Vue App"
    @complete="handleComplete"
  />
</template>

Capacitor (iOS/Android)

Capacitor requires one-time native setup for Google Sign-In and native ChatGPT import:

npm install onairos @capgo/capacitor-social-login @onairosofficial/capacitor-llm-onairos
npx cap sync ios

Then initialize the SDK before rendering OnairosButton:

import { initializeApiKey, OnairosButton } from "onairos";

window.onairosOAuthReturnOrigin = "myapp://auth/callback";

await initializeApiKey({
  apiKey: "YOUR_ONAIROS_KEY",
  environment: "production",
  platform: "capacitor-ios",
  googleClientIds: {
    webClientId: "your-web-client-id.apps.googleusercontent.com",
    iosClientId: "your-ios-client-id.apps.googleusercontent.com",
    serverClientId: "your-server-client-id.apps.googleusercontent.com",
  },
});

function MobileApp() {
  return (
    <OnairosButton
      requestData={["email", "profile", "social"]}
      webpageName="My Mobile App"
      onComplete={(result) => {
        console.log("User data:", result.apiResponse);
      }}
    />
  );
}

Mobile Notes:

• ✅ OAuth flows use mobile-friendly redirects (not popups)
• ✅ Touch interactions fully supported
• ✅ Tested on iOS 13+ and Android 8+

iOS URL Schemes

Your iOS app must register two URL schemes in Info.plist:

1. The reversed Google iOS client ID scheme for native Google Sign-In
2. Your app callback scheme, which must match window.onairosOAuthReturnOrigin

Example:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.googleusercontent.apps.1234567890-abcdefg</string>
    </array>
  </dict>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

The Onairos callback scheme is not a fixed global scheme. It is your app's own deep-link return path. onairosevents://auth/callback is only the sample app value used in mobile-preview.

Why The Callback Scheme Exists

This is standard for native mobile OAuth flows. After Google Sign-In or a browser-based return step finishes, iOS needs a registered app URL scheme to reopen your app and hand control back to the SDK.

Vite Configuration

For Vite applications, exclude onairos from optimization:

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ["onairos"],
  },
});

Framer (No-Build Integration)

Perfect for Framer projects - no package manager needed! Uses CDN loading:

import { addPropertyControls, ControlType } from "framer"
import { useEffect, useState } from "react"

export default function OnairosConnect(props) {
    const [OnairosButton, setOnairosButton] = useState(null)

    useEffect(() => {
        const script = document.createElement("script")
        script.src = "https://unpkg.com/onairos@latest/dist/onairos.bundle.js"
        script.onload = () => setOnairosButton(() => window.Onairos.OnairosButton)
        document.head.appendChild(script)
    }, [])

    return (
        <>
            <link rel="stylesheet" href="https://unpkg.com/onairos@latest/dist/onairos.css" />
            {OnairosButton && (
                <OnairosButton
                    requestData={props.requestData}
                    webpageName={props.webpageName}
                    testMode={props.testMode}
                    onComplete={(result) => console.log(result)}
                />
            )}
        </>
    )
}

📖 Complete Framer Integration Guide →

Framer Notes:

• ✅ No dependencies to install - works with CDN
• ✅ Full property controls in Framer UI
• ✅ Copy-paste ready Code Component
• ✅ Mobile-responsive out of the box

🔌 Platform Management API

Disconnect Platforms

import { disconnectPlatform, disconnectMultiplePlatforms } from "onairos";

// Disconnect a single platform
const result = await disconnectPlatform("youtube", "[email protected]");
if (result.success) {
  console.log("YouTube disconnected successfully");
}

// Disconnect multiple platforms
const results = await disconnectMultiplePlatforms(
  ["youtube", "reddit", "linkedin"],
  "[email protected]"
);
console.log(`Disconnected ${results.successful.length} platforms`);

Check Platform Support

import { getSupportedPlatforms, isPlatformSupported } from "onairos";

const platforms = getSupportedPlatforms();
console.log("Supported platforms:", platforms);

if (isPlatformSupported("youtube")) {
  // YouTube is available
}

⚙️ OAuth Configuration

Google OAuth

import { updateGoogleClientIds, getGoogleClientIds } from "onairos";

// Configure Google OAuth (required for Google Sign-In)
updateGoogleClientIds({
  webClientId: "your-web-client-id.apps.googleusercontent.com",
  iosClientId: "your-ios-client-id.apps.googleusercontent.com",
});

// Get current configuration
const clientIds = getGoogleClientIds();

YouTube OAuth

import { updateYoutubeClientId, getYoutubeClientId } from "onairos";

// Configure YouTube OAuth (separate from Google Sign-In)
updateYoutubeClientId("your-youtube-client-id.apps.googleusercontent.com");

🔍 TypeScript Support

Full TypeScript definitions are included:

import { 
  OnairosButton, 
  OnairosCompleteData,
  OnairosProps,
  DisconnectPlatformResponse 
} from "onairos";

const handleComplete = (data: OnairosCompleteData) => {
  // TypeScript knows all available properties
  const { token, apiUrl, approvedData, userData } = data;
  
  if (data.apiResponse) {
    // Process API response
  }
};

Key Types

interface OnairosCompleteData {
  token: string;              // JWT for authenticated requests
  apiUrl: string;             // API endpoint URL
  userHash?: string;          // Unique user identifier
  approvedData?: string[];    // Approved data types
  apiResponse?: any;          // API response data
  userData?: any;             // User profile data
  success?: boolean;          // Request success status
  error?: string;             // Error message if failed
}

🌐 Browser & Platform Compatibility

| Platform | Version | |----------|---------| | Chrome | 80+ | | Firefox | 75+ | | Safari | 13+ | | Edge | 80+ | | iOS Safari | 13+ | | Chrome Mobile | Latest | | Capacitor | iOS 13+ / Android 8+ | | React | 18.x, 19.x | | Framer | All versions | | Tailwind CSS | 3.x, 4.x |

🐛 Troubleshooting

Popup Blocked

Ensure popups are allowed for your domain. On mobile, OAuth automatically uses redirects.

API Calls Failing

• Verify your domain is registered in the developer portal
• Check that your API key is valid
• Ensure HTTPS is used in production

Mobile Issues

• OAuth flows automatically convert to redirects on mobile
• Ensure localStorage is enabled in Capacitor configuration

Tailwind CSS Conflicts

The SDK is compatible with both Tailwind v3 and v4. No special configuration needed.

📚 Additional Resources

• Developer Portal: onairos.uk/dev-board
• Homepage: onairos.uk
• Issues: GitHub Issues

📄 License

Apache-2.0 © Zion Darko