onairos

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:

• The reversed Google iOS client ID scheme for native Google Sign-In
• 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", "[e-mail]");
if (result.success) {
  console.log("YouTube disconnected successfully");
}

// Disconnect multiple platforms
const results = await disconnectMultiplePlatforms(
  ["youtube", "reddit", "linkedin"],
  "[e-mail]"
);
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