onairos 4.2.12 → 4.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +474 -474
- package/dist/670.js +1 -1
- package/dist/670.js.map +1 -1
- package/dist/onairos.esm.js +1 -1
- package/dist/onairos.esm.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,474 +1,474 @@
|
|
|
1
|
-
## Onairos Developer Documentation v2.0.0
|
|
2
|
-
|
|
3
|
-
### 🚀 What's New in v2.0.0
|
|
4
|
-
|
|
5
|
-
- **Popup-based Data Requests**: No more cutoff issues with improved popup window implementation
|
|
6
|
-
- **AutoFetch by Default**: Automatic API calls after user approval - no manual handling required
|
|
7
|
-
- **Simplified Integration**: Much cleaner and easier to use
|
|
8
|
-
- **Enhanced UX**: Better positioning, loading states, and error handling
|
|
9
|
-
- **Laravel Vite Support**: First-class integration with Laravel Vite applications
|
|
10
|
-
|
|
11
|
-
### 1. Create a Developer Account
|
|
12
|
-
|
|
13
|
-
Create a Developer account to access Onairos services at:
|
|
14
|
-
|
|
15
|
-
https://Onairos.uk/dev-board
|
|
16
|
-
|
|
17
|
-
**Important:** Once you have a developer account and API key, domain registration is handled manually by the Onairos team. If you don't have an API key yet, you'll need to register your domain through the developer portal for secure API access.
|
|
18
|
-
|
|
19
|
-
### 2. Installation
|
|
20
|
-
|
|
21
|
-
#### Standard Installation
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
npm install onairos
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
#### Laravel Vite Installation
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
npm install onairos
|
|
31
|
-
# For Vue.js integration
|
|
32
|
-
npm install --save-dev @vitejs/plugin-vue
|
|
33
|
-
# For React integration
|
|
34
|
-
npm install --save-dev @vitejs/plugin-react
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
### 3. Basic Usage
|
|
38
|
-
|
|
39
|
-
#### React/Standard Integration
|
|
40
|
-
|
|
41
|
-
Import and use the OnairosButton component:
|
|
42
|
-
|
|
43
|
-
```jsx
|
|
44
|
-
import { OnairosButton } from "onairos";
|
|
45
|
-
|
|
46
|
-
function MyApp() {
|
|
47
|
-
return (
|
|
48
|
-
<OnairosButton
|
|
49
|
-
requestData={["email", "profile", "social"]}
|
|
50
|
-
webpageName="My Application"
|
|
51
|
-
autoFetch={true} // Default - automatically makes API calls
|
|
52
|
-
onComplete={(result) => {
|
|
53
|
-
console.log("Data approved:", result.approved);
|
|
54
|
-
console.log("API Response:", result.apiResponse); // Available when autoFetch is true
|
|
55
|
-
|
|
56
|
-
if (result.apiResponse) {
|
|
57
|
-
// Use the API response data directly
|
|
58
|
-
console.log("User data:", result.apiResponse);
|
|
59
|
-
}
|
|
60
|
-
}}
|
|
61
|
-
/>
|
|
62
|
-
);
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
#### Laravel Blade Integration
|
|
67
|
-
|
|
68
|
-
For Laravel applications using Blade templates:
|
|
69
|
-
|
|
70
|
-
```js
|
|
71
|
-
// vite.config.js
|
|
72
|
-
import { defineConfig } from "vite";
|
|
73
|
-
import laravel from "laravel-vite-plugin";
|
|
74
|
-
import { onairosLaravelPlugin } from "onairos/vite-plugin";
|
|
75
|
-
|
|
76
|
-
export default defineConfig({
|
|
77
|
-
plugins: [
|
|
78
|
-
laravel({
|
|
79
|
-
input: ["resources/css/app.css", "resources/js/app.js"],
|
|
80
|
-
refresh: true,
|
|
81
|
-
}),
|
|
82
|
-
onairosLaravelPlugin({
|
|
83
|
-
bladeSupport: true,
|
|
84
|
-
}),
|
|
85
|
-
],
|
|
86
|
-
});
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
```js
|
|
90
|
-
// resources/js/app.js
|
|
91
|
-
import { initializeOnairosForBlade } from "onairos/blade";
|
|
92
|
-
|
|
93
|
-
document.addEventListener("DOMContentLoaded", () => {
|
|
94
|
-
initializeOnairosForBlade({
|
|
95
|
-
testMode: import.meta.env.DEV,
|
|
96
|
-
autoDetectMobile: true,
|
|
97
|
-
});
|
|
98
|
-
});
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
```blade
|
|
102
|
-
{{-- resources/views/dashboard.blade.php --}}
|
|
103
|
-
<div id="onairos-button"></div>
|
|
104
|
-
|
|
105
|
-
<script>
|
|
106
|
-
createOnairosButton('onairos-button', {
|
|
107
|
-
requestData: ['email', 'profile'],
|
|
108
|
-
webpageName: 'My Laravel App',
|
|
109
|
-
onComplete: function(result) {
|
|
110
|
-
console.log('Connection successful!', result);
|
|
111
|
-
}
|
|
112
|
-
});
|
|
113
|
-
</script>
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
#### Laravel Vue Integration
|
|
117
|
-
|
|
118
|
-
For Laravel applications using Vue.js:
|
|
119
|
-
|
|
120
|
-
```js
|
|
121
|
-
// vite.config.js
|
|
122
|
-
import { defineConfig } from "vite";
|
|
123
|
-
import laravel from "laravel-vite-plugin";
|
|
124
|
-
import vue from "@vitejs/plugin-vue";
|
|
125
|
-
import { onairosVuePlugin } from "onairos/vite-plugin";
|
|
126
|
-
|
|
127
|
-
export default defineConfig({
|
|
128
|
-
plugins: [
|
|
129
|
-
laravel({
|
|
130
|
-
input: ["resources/css/app.css", "resources/js/app.js"],
|
|
131
|
-
refresh: true,
|
|
132
|
-
}),
|
|
133
|
-
vue(),
|
|
134
|
-
onairosVuePlugin(),
|
|
135
|
-
],
|
|
136
|
-
});
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
```js
|
|
140
|
-
// resources/js/app.js
|
|
141
|
-
import { createApp } from "vue";
|
|
142
|
-
import OnairosVue from "onairos/src/laravel/OnairosVue.vue";
|
|
143
|
-
|
|
144
|
-
const app = createApp({});
|
|
145
|
-
app.component("onairos-button", OnairosVue);
|
|
146
|
-
app.mount("#app");
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
#### Vite Optimization Configuration
|
|
150
|
-
|
|
151
|
-
For Vite applications, add the following configuration to ensure proper asset handling:
|
|
152
|
-
|
|
153
|
-
```ts
|
|
154
|
-
// vite.config.ts
|
|
155
|
-
import { defineConfig } from "vite";
|
|
156
|
-
|
|
157
|
-
export default defineConfig({
|
|
158
|
-
optimizeDeps: {
|
|
159
|
-
exclude: ["onairos"],
|
|
160
|
-
},
|
|
161
|
-
});
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
#### Capacitor Mobile App Integration (React Native, iOS, Android)
|
|
165
|
-
|
|
166
|
-
For mobile applications using Capacitor with React + Vite:
|
|
167
|
-
|
|
168
|
-
```jsx
|
|
169
|
-
// Works identically to web - no special configuration needed
|
|
170
|
-
import { OnairosButton } from "onairos";
|
|
171
|
-
|
|
172
|
-
function MyMobileApp() {
|
|
173
|
-
return (
|
|
174
|
-
<OnairosButton
|
|
175
|
-
requestData={["email", "profile", "social"]}
|
|
176
|
-
webpageName="My Mobile App"
|
|
177
|
-
autoFetch={true}
|
|
178
|
-
onComplete={(result) => {
|
|
179
|
-
if (result.apiResponse) {
|
|
180
|
-
// Handle user data in your mobile app
|
|
181
|
-
console.log("User data:", result.apiResponse);
|
|
182
|
-
}
|
|
183
|
-
}}
|
|
184
|
-
/>
|
|
185
|
-
);
|
|
186
|
-
}
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
**Mobile-Specific Notes:**
|
|
190
|
-
- ✅ All React components work identically in Capacitor
|
|
191
|
-
- ✅ API calls and authentication work the same
|
|
192
|
-
- ✅ OAuth flows automatically use mobile-friendly redirects instead of popups
|
|
193
|
-
- ✅ Touch interactions are fully supported
|
|
194
|
-
- ✅ **LLM data collection available via native method** (no browser extension needed)
|
|
195
|
-
- 📱 Tested on iOS 13+ and Android 8+
|
|
196
|
-
|
|
197
|
-
**LLM Data Collection in Capacitor:**
|
|
198
|
-
```jsx
|
|
199
|
-
import { storeCapacitorLLMData } from 'onairos';
|
|
200
|
-
|
|
201
|
-
// Store LLM conversation data directly (no browser extension needed)
|
|
202
|
-
const result = await storeCapacitorLLMData(
|
|
203
|
-
{
|
|
204
|
-
messages: [
|
|
205
|
-
{ role: 'user', content: 'Hello!' },
|
|
206
|
-
{ role: 'assistant', content: 'Hi there!' }
|
|
207
|
-
],
|
|
208
|
-
timestamp: new Date().toISOString()
|
|
209
|
-
},
|
|
210
|
-
userInfo, // From OnairosButton onComplete callback
|
|
211
|
-
'chatgpt' // Platform: 'chatgpt', 'claude', 'gemini', or 'grok'
|
|
212
|
-
);
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
For detailed Capacitor integration including LLM data collection, see:
|
|
216
|
-
- 🚀 [Capacitor Quick Start Guide](./CAPACITOR_QUICK_START.md) - 5-minute setup
|
|
217
|
-
- 📖 [Full Capacitor Integration Guide](./CAPACITOR_IOS_INTEGRATION.md) - Complete documentation
|
|
218
|
-
|
|
219
|
-
#### Custom Persona Images
|
|
220
|
-
|
|
221
|
-
The library includes default persona images that change based on connected platforms. In Vite dev environments, these may show as gradient fallbacks due to asset processing. To use custom images:
|
|
222
|
-
|
|
223
|
-
```jsx
|
|
224
|
-
import { OnairosButton } from "onairos";
|
|
225
|
-
|
|
226
|
-
function MyApp() {
|
|
227
|
-
return (
|
|
228
|
-
<OnairosButton
|
|
229
|
-
requestData={["email", "profile", "social"]}
|
|
230
|
-
webpageName="My Application"
|
|
231
|
-
personaImages={{
|
|
232
|
-
1: "/path/to/persona1.png",
|
|
233
|
-
2: "/path/to/persona2.png",
|
|
234
|
-
3: "/path/to/persona3.png",
|
|
235
|
-
4: "/path/to/persona4.png",
|
|
236
|
-
5: "/path/to/persona5.png",
|
|
237
|
-
}}
|
|
238
|
-
onComplete={(result) => {
|
|
239
|
-
console.log("Data approved:", result.approved);
|
|
240
|
-
}}
|
|
241
|
-
/>
|
|
242
|
-
);
|
|
243
|
-
}
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
```blade
|
|
247
|
-
{{-- In your Blade template --}}
|
|
248
|
-
<div id="app">
|
|
249
|
-
<onairos-button
|
|
250
|
-
:request-data="['email', 'profile']"
|
|
251
|
-
webpage-name="Laravel Vue App"
|
|
252
|
-
@complete="handleComplete"
|
|
253
|
-
></onairos-button>
|
|
254
|
-
</div>
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
### 4. Configuration Options
|
|
258
|
-
|
|
259
|
-
#### OnairosButton Props
|
|
260
|
-
|
|
261
|
-
- **`requestData`** (Array): Specific data types to request
|
|
262
|
-
- Available types: `'email'`, `'profile'`, `'social'`, `'activity'`, `'preferences'`
|
|
263
|
-
- **`webpageName`** (String): Your application name displayed to users
|
|
264
|
-
- **`autoFetch`** (Boolean, default: `true`): Enable automatic API calls after approval
|
|
265
|
-
- **`onComplete`** (Function): Callback when data request completes
|
|
266
|
-
- **`proofMode`** (Boolean, default: `false`): Enable proof mode for verification
|
|
267
|
-
- **`testMode`** (Boolean, default: `false`): Enable test mode for development
|
|
268
|
-
|
|
269
|
-
#### Laravel-Specific Props
|
|
270
|
-
|
|
271
|
-
- **`buttonType`** (String): `'pill'`, `'icon'`, or `'rounded'`
|
|
272
|
-
- **`size`** (String): `'small'`, `'medium'`, or `'large'`
|
|
273
|
-
- **`textColor`** (String): Button text color
|
|
274
|
-
- **`disabled`** (Boolean): Disable the button
|
|
275
|
-
|
|
276
|
-
### 5. Laravel Integration Guide
|
|
277
|
-
|
|
278
|
-
For complete Laravel integration examples and advanced configuration, see our [Laravel Integration Guide](./LARAVEL_INTEGRATION_GUIDE.md).
|
|
279
|
-
|
|
280
|
-
The guide covers:
|
|
281
|
-
|
|
282
|
-
- ✅ **Blade Templates**: Direct integration with PHP templates
|
|
283
|
-
- ✅ **Vue.js Components**: Reactive Vue components
|
|
284
|
-
- ✅ **React Components**: React integration patterns
|
|
285
|
-
- ✅ **Vite Plugins**: Custom Vite plugins for Laravel
|
|
286
|
-
- ✅ **Mobile Optimization**: Automatic mobile detection
|
|
287
|
-
- ✅ **Production Deployment**: Build and deployment strategies
|
|
288
|
-
|
|
289
|
-
### 6. Migration from v1.x
|
|
290
|
-
|
|
291
|
-
**Before (v1.x - Complex)**:
|
|
292
|
-
|
|
293
|
-
```jsx
|
|
294
|
-
// Old complex setup with manual event listeners
|
|
295
|
-
useEffect(() => {
|
|
296
|
-
const handleMessage = (event) => {
|
|
297
|
-
if (
|
|
298
|
-
event.data?.source === "content-script" &&
|
|
299
|
-
event.data?.type === "API_URL_RESPONSE"
|
|
300
|
-
) {
|
|
301
|
-
const { APIurl, accessToken } = event.data;
|
|
302
|
-
// Manual API call handling
|
|
303
|
-
fetch(APIurl, {
|
|
304
|
-
method: "POST",
|
|
305
|
-
headers: { Authorization: `Bearer ${accessToken}` },
|
|
306
|
-
body: JSON.stringify(InputData),
|
|
307
|
-
});
|
|
308
|
-
}
|
|
309
|
-
};
|
|
310
|
-
window.addEventListener("message", handleMessage);
|
|
311
|
-
return () => window.removeEventListener("message", handleMessage);
|
|
312
|
-
}, []);
|
|
313
|
-
|
|
314
|
-
<Onairos requestData={complexRequestObject} webpageName={webpageName} />;
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
**After (v2.0 - Simple)**:
|
|
318
|
-
|
|
319
|
-
```jsx
|
|
320
|
-
// New simplified approach
|
|
321
|
-
<OnairosButton
|
|
322
|
-
requestData={["email", "profile"]}
|
|
323
|
-
webpageName="My App"
|
|
324
|
-
onComplete={(result) => {
|
|
325
|
-
// API call already made automatically
|
|
326
|
-
console.log("User data:", result.apiResponse);
|
|
327
|
-
}}
|
|
328
|
-
/>
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
### 7. Data Types Available
|
|
332
|
-
|
|
333
|
-
- **`email`**: Email address for account identification
|
|
334
|
-
- **`profile`**: Basic profile information and preferences
|
|
335
|
-
- **`social`**: Connected social media accounts
|
|
336
|
-
- **`activity`**: Usage patterns and interactions
|
|
337
|
-
- **`preferences`**: User settings and customization choices
|
|
338
|
-
|
|
339
|
-
### 8. Error Handling
|
|
340
|
-
|
|
341
|
-
The component includes comprehensive error handling:
|
|
342
|
-
|
|
343
|
-
```jsx
|
|
344
|
-
<OnairosButton
|
|
345
|
-
requestData={["email"]}
|
|
346
|
-
webpageName="My App"
|
|
347
|
-
onComplete={(result) => {
|
|
348
|
-
if (result.apiError) {
|
|
349
|
-
console.error("API Error:", result.apiError);
|
|
350
|
-
// Handle error appropriately
|
|
351
|
-
} else if (result.apiResponse) {
|
|
352
|
-
console.log("Success:", result.apiResponse);
|
|
353
|
-
// Process data
|
|
354
|
-
}
|
|
355
|
-
}}
|
|
356
|
-
/>
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
### 9. Browser & Platform Compatibility
|
|
360
|
-
|
|
361
|
-
**Desktop Browsers:**
|
|
362
|
-
- ✅ Chrome 80+
|
|
363
|
-
- ✅ Firefox 75+
|
|
364
|
-
- ✅ Safari 13+
|
|
365
|
-
- ✅ Edge 80+
|
|
366
|
-
|
|
367
|
-
**Mobile Browsers:**
|
|
368
|
-
- ✅ iOS Safari 13+
|
|
369
|
-
- ✅ Chrome Mobile (Android)
|
|
370
|
-
- ✅ Samsung Internet
|
|
371
|
-
- ✅ Firefox Mobile
|
|
372
|
-
|
|
373
|
-
**Mobile Frameworks:**
|
|
374
|
-
- ✅ Capacitor (iOS/Android)
|
|
375
|
-
- ✅ React Native WebView
|
|
376
|
-
- ✅ Ionic
|
|
377
|
-
|
|
378
|
-
### 10. Troubleshooting
|
|
379
|
-
|
|
380
|
-
**Popup Blocked**: Ensure popups are allowed for your domain in browser settings. On mobile devices, OAuth automatically uses redirects instead of popups.
|
|
381
|
-
|
|
382
|
-
**API Calls Failing**:
|
|
383
|
-
- If you have a developer account with an API key, domain registration is handled manually by the Onairos team
|
|
384
|
-
- If you don't have an API key, verify your domain is registered in the [developer console](https://Onairos.uk/dev-board)
|
|
385
|
-
- Check that your API key is included in requests if using the SDK
|
|
386
|
-
|
|
387
|
-
**Data Not Loading**: Check browser console for errors and ensure proper integration.
|
|
388
|
-
|
|
389
|
-
**Mobile/Capacitor Issues**:
|
|
390
|
-
- OAuth popups automatically convert to redirects on mobile
|
|
391
|
-
- Browser extension features are not available in Capacitor apps
|
|
392
|
-
- Ensure localStorage is enabled in your Capacitor configuration
|
|
393
|
-
|
|
394
|
-
### 11. Support
|
|
395
|
-
|
|
396
|
-
For issues or questions:
|
|
397
|
-
|
|
398
|
-
- Check the [troubleshooting guide](./POPUP_IMPLEMENTATION_README.md)
|
|
399
|
-
- Review browser console for errors
|
|
400
|
-
- Contact support with detailed error information
|
|
401
|
-
|
|
402
|
-
---
|
|
403
|
-
|
|
404
|
-
## Legacy Documentation (v1.x)
|
|
405
|
-
|
|
406
|
-
_The following sections document the previous complex implementation for reference:_
|
|
407
|
-
|
|
408
|
-
### Legacy Request Object Format
|
|
409
|
-
|
|
410
|
-
Previously required complex request objects:
|
|
411
|
-
|
|
412
|
-
```json
|
|
413
|
-
"RequestObject":{
|
|
414
|
-
"Small": {
|
|
415
|
-
"type":"Personality",
|
|
416
|
-
"descriptions":"Insight into your Interests",
|
|
417
|
-
"reward":"10% Discount"
|
|
418
|
-
},
|
|
419
|
-
"Medium":{
|
|
420
|
-
"type":"Personality",
|
|
421
|
-
"descriptions":"Insight into your Interests",
|
|
422
|
-
"reward":"2 USDC"
|
|
423
|
-
},
|
|
424
|
-
"Large":{
|
|
425
|
-
"type":"Personality",
|
|
426
|
-
"descriptions":"Insight into your Interests",
|
|
427
|
-
"reward":"2 USDC"
|
|
428
|
-
}
|
|
429
|
-
}
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
### Legacy API Usage
|
|
433
|
-
|
|
434
|
-
Previously required manual event handling:
|
|
435
|
-
|
|
436
|
-
```jsx
|
|
437
|
-
export default async function UseAPIURL(event) {
|
|
438
|
-
if (
|
|
439
|
-
event.data &&
|
|
440
|
-
event.data.source === "content-script" &&
|
|
441
|
-
event.data.type === "API_URL_RESPONSE"
|
|
442
|
-
) {
|
|
443
|
-
const { APIurl, accessToken } = event.data;
|
|
444
|
-
await fetch(APIurl, {
|
|
445
|
-
method: "POST",
|
|
446
|
-
headers: {
|
|
447
|
-
"Content-Type": "application/json",
|
|
448
|
-
Authorization: `Bearer ${accessToken}`,
|
|
449
|
-
},
|
|
450
|
-
body: JSON.stringify(InputData),
|
|
451
|
-
})
|
|
452
|
-
.then(async (data) => {
|
|
453
|
-
// process Onairos Data
|
|
454
|
-
})
|
|
455
|
-
.catch((error) => console.error(error));
|
|
456
|
-
}
|
|
457
|
-
}
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
_This manual approach is no longer needed with v2.0's autoFetch functionality._
|
|
461
|
-
|
|
462
|
-
### Legacy Output Format
|
|
463
|
-
|
|
464
|
-
API still responds with the same format:
|
|
465
|
-
|
|
466
|
-
```json
|
|
467
|
-
{
|
|
468
|
-
"output": [[[0.9998]], [[0.9999]], [[0.9922]], [[0.0013]]]
|
|
469
|
-
}
|
|
470
|
-
```
|
|
471
|
-
|
|
472
|
-
### Integration Notes
|
|
473
|
-
|
|
474
|
-
When integrating the onairos package into your application, ensure your Webpack configuration handles dynamic imports correctly and serves the necessary chunk files from `node_modules/onairos/dist`.
|
|
1
|
+
## Onairos Developer Documentation v2.0.0
|
|
2
|
+
|
|
3
|
+
### 🚀 What's New in v2.0.0
|
|
4
|
+
|
|
5
|
+
- **Popup-based Data Requests**: No more cutoff issues with improved popup window implementation
|
|
6
|
+
- **AutoFetch by Default**: Automatic API calls after user approval - no manual handling required
|
|
7
|
+
- **Simplified Integration**: Much cleaner and easier to use
|
|
8
|
+
- **Enhanced UX**: Better positioning, loading states, and error handling
|
|
9
|
+
- **Laravel Vite Support**: First-class integration with Laravel Vite applications
|
|
10
|
+
|
|
11
|
+
### 1. Create a Developer Account
|
|
12
|
+
|
|
13
|
+
Create a Developer account to access Onairos services at:
|
|
14
|
+
|
|
15
|
+
https://Onairos.uk/dev-board
|
|
16
|
+
|
|
17
|
+
**Important:** Once you have a developer account and API key, domain registration is handled manually by the Onairos team. If you don't have an API key yet, you'll need to register your domain through the developer portal for secure API access.
|
|
18
|
+
|
|
19
|
+
### 2. Installation
|
|
20
|
+
|
|
21
|
+
#### Standard Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install onairos
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
#### Laravel Vite Installation
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install onairos
|
|
31
|
+
# For Vue.js integration
|
|
32
|
+
npm install --save-dev @vitejs/plugin-vue
|
|
33
|
+
# For React integration
|
|
34
|
+
npm install --save-dev @vitejs/plugin-react
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### 3. Basic Usage
|
|
38
|
+
|
|
39
|
+
#### React/Standard Integration
|
|
40
|
+
|
|
41
|
+
Import and use the OnairosButton component:
|
|
42
|
+
|
|
43
|
+
```jsx
|
|
44
|
+
import { OnairosButton } from "onairos";
|
|
45
|
+
|
|
46
|
+
function MyApp() {
|
|
47
|
+
return (
|
|
48
|
+
<OnairosButton
|
|
49
|
+
requestData={["email", "profile", "social"]}
|
|
50
|
+
webpageName="My Application"
|
|
51
|
+
autoFetch={true} // Default - automatically makes API calls
|
|
52
|
+
onComplete={(result) => {
|
|
53
|
+
console.log("Data approved:", result.approved);
|
|
54
|
+
console.log("API Response:", result.apiResponse); // Available when autoFetch is true
|
|
55
|
+
|
|
56
|
+
if (result.apiResponse) {
|
|
57
|
+
// Use the API response data directly
|
|
58
|
+
console.log("User data:", result.apiResponse);
|
|
59
|
+
}
|
|
60
|
+
}}
|
|
61
|
+
/>
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
#### Laravel Blade Integration
|
|
67
|
+
|
|
68
|
+
For Laravel applications using Blade templates:
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
// vite.config.js
|
|
72
|
+
import { defineConfig } from "vite";
|
|
73
|
+
import laravel from "laravel-vite-plugin";
|
|
74
|
+
import { onairosLaravelPlugin } from "onairos/vite-plugin";
|
|
75
|
+
|
|
76
|
+
export default defineConfig({
|
|
77
|
+
plugins: [
|
|
78
|
+
laravel({
|
|
79
|
+
input: ["resources/css/app.css", "resources/js/app.js"],
|
|
80
|
+
refresh: true,
|
|
81
|
+
}),
|
|
82
|
+
onairosLaravelPlugin({
|
|
83
|
+
bladeSupport: true,
|
|
84
|
+
}),
|
|
85
|
+
],
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```js
|
|
90
|
+
// resources/js/app.js
|
|
91
|
+
import { initializeOnairosForBlade } from "onairos/blade";
|
|
92
|
+
|
|
93
|
+
document.addEventListener("DOMContentLoaded", () => {
|
|
94
|
+
initializeOnairosForBlade({
|
|
95
|
+
testMode: import.meta.env.DEV,
|
|
96
|
+
autoDetectMobile: true,
|
|
97
|
+
});
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```blade
|
|
102
|
+
{{-- resources/views/dashboard.blade.php --}}
|
|
103
|
+
<div id="onairos-button"></div>
|
|
104
|
+
|
|
105
|
+
<script>
|
|
106
|
+
createOnairosButton('onairos-button', {
|
|
107
|
+
requestData: ['email', 'profile'],
|
|
108
|
+
webpageName: 'My Laravel App',
|
|
109
|
+
onComplete: function(result) {
|
|
110
|
+
console.log('Connection successful!', result);
|
|
111
|
+
}
|
|
112
|
+
});
|
|
113
|
+
</script>
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
#### Laravel Vue Integration
|
|
117
|
+
|
|
118
|
+
For Laravel applications using Vue.js:
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
// vite.config.js
|
|
122
|
+
import { defineConfig } from "vite";
|
|
123
|
+
import laravel from "laravel-vite-plugin";
|
|
124
|
+
import vue from "@vitejs/plugin-vue";
|
|
125
|
+
import { onairosVuePlugin } from "onairos/vite-plugin";
|
|
126
|
+
|
|
127
|
+
export default defineConfig({
|
|
128
|
+
plugins: [
|
|
129
|
+
laravel({
|
|
130
|
+
input: ["resources/css/app.css", "resources/js/app.js"],
|
|
131
|
+
refresh: true,
|
|
132
|
+
}),
|
|
133
|
+
vue(),
|
|
134
|
+
onairosVuePlugin(),
|
|
135
|
+
],
|
|
136
|
+
});
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```js
|
|
140
|
+
// resources/js/app.js
|
|
141
|
+
import { createApp } from "vue";
|
|
142
|
+
import OnairosVue from "onairos/src/laravel/OnairosVue.vue";
|
|
143
|
+
|
|
144
|
+
const app = createApp({});
|
|
145
|
+
app.component("onairos-button", OnairosVue);
|
|
146
|
+
app.mount("#app");
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
#### Vite Optimization Configuration
|
|
150
|
+
|
|
151
|
+
For Vite applications, add the following configuration to ensure proper asset handling:
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
// vite.config.ts
|
|
155
|
+
import { defineConfig } from "vite";
|
|
156
|
+
|
|
157
|
+
export default defineConfig({
|
|
158
|
+
optimizeDeps: {
|
|
159
|
+
exclude: ["onairos"],
|
|
160
|
+
},
|
|
161
|
+
});
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
#### Capacitor Mobile App Integration (React Native, iOS, Android)
|
|
165
|
+
|
|
166
|
+
For mobile applications using Capacitor with React + Vite:
|
|
167
|
+
|
|
168
|
+
```jsx
|
|
169
|
+
// Works identically to web - no special configuration needed
|
|
170
|
+
import { OnairosButton } from "onairos";
|
|
171
|
+
|
|
172
|
+
function MyMobileApp() {
|
|
173
|
+
return (
|
|
174
|
+
<OnairosButton
|
|
175
|
+
requestData={["email", "profile", "social"]}
|
|
176
|
+
webpageName="My Mobile App"
|
|
177
|
+
autoFetch={true}
|
|
178
|
+
onComplete={(result) => {
|
|
179
|
+
if (result.apiResponse) {
|
|
180
|
+
// Handle user data in your mobile app
|
|
181
|
+
console.log("User data:", result.apiResponse);
|
|
182
|
+
}
|
|
183
|
+
}}
|
|
184
|
+
/>
|
|
185
|
+
);
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
**Mobile-Specific Notes:**
|
|
190
|
+
- ✅ All React components work identically in Capacitor
|
|
191
|
+
- ✅ API calls and authentication work the same
|
|
192
|
+
- ✅ OAuth flows automatically use mobile-friendly redirects instead of popups
|
|
193
|
+
- ✅ Touch interactions are fully supported
|
|
194
|
+
- ✅ **LLM data collection available via native method** (no browser extension needed)
|
|
195
|
+
- 📱 Tested on iOS 13+ and Android 8+
|
|
196
|
+
|
|
197
|
+
**LLM Data Collection in Capacitor:**
|
|
198
|
+
```jsx
|
|
199
|
+
import { storeCapacitorLLMData } from 'onairos';
|
|
200
|
+
|
|
201
|
+
// Store LLM conversation data directly (no browser extension needed)
|
|
202
|
+
const result = await storeCapacitorLLMData(
|
|
203
|
+
{
|
|
204
|
+
messages: [
|
|
205
|
+
{ role: 'user', content: 'Hello!' },
|
|
206
|
+
{ role: 'assistant', content: 'Hi there!' }
|
|
207
|
+
],
|
|
208
|
+
timestamp: new Date().toISOString()
|
|
209
|
+
},
|
|
210
|
+
userInfo, // From OnairosButton onComplete callback
|
|
211
|
+
'chatgpt' // Platform: 'chatgpt', 'claude', 'gemini', or 'grok'
|
|
212
|
+
);
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
For detailed Capacitor integration including LLM data collection, see:
|
|
216
|
+
- 🚀 [Capacitor Quick Start Guide](./CAPACITOR_QUICK_START.md) - 5-minute setup
|
|
217
|
+
- 📖 [Full Capacitor Integration Guide](./CAPACITOR_IOS_INTEGRATION.md) - Complete documentation
|
|
218
|
+
|
|
219
|
+
#### Custom Persona Images
|
|
220
|
+
|
|
221
|
+
The library includes default persona images that change based on connected platforms. In Vite dev environments, these may show as gradient fallbacks due to asset processing. To use custom images:
|
|
222
|
+
|
|
223
|
+
```jsx
|
|
224
|
+
import { OnairosButton } from "onairos";
|
|
225
|
+
|
|
226
|
+
function MyApp() {
|
|
227
|
+
return (
|
|
228
|
+
<OnairosButton
|
|
229
|
+
requestData={["email", "profile", "social"]}
|
|
230
|
+
webpageName="My Application"
|
|
231
|
+
personaImages={{
|
|
232
|
+
1: "/path/to/persona1.png",
|
|
233
|
+
2: "/path/to/persona2.png",
|
|
234
|
+
3: "/path/to/persona3.png",
|
|
235
|
+
4: "/path/to/persona4.png",
|
|
236
|
+
5: "/path/to/persona5.png",
|
|
237
|
+
}}
|
|
238
|
+
onComplete={(result) => {
|
|
239
|
+
console.log("Data approved:", result.approved);
|
|
240
|
+
}}
|
|
241
|
+
/>
|
|
242
|
+
);
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
```blade
|
|
247
|
+
{{-- In your Blade template --}}
|
|
248
|
+
<div id="app">
|
|
249
|
+
<onairos-button
|
|
250
|
+
:request-data="['email', 'profile']"
|
|
251
|
+
webpage-name="Laravel Vue App"
|
|
252
|
+
@complete="handleComplete"
|
|
253
|
+
></onairos-button>
|
|
254
|
+
</div>
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
### 4. Configuration Options
|
|
258
|
+
|
|
259
|
+
#### OnairosButton Props
|
|
260
|
+
|
|
261
|
+
- **`requestData`** (Array): Specific data types to request
|
|
262
|
+
- Available types: `'email'`, `'profile'`, `'social'`, `'activity'`, `'preferences'`
|
|
263
|
+
- **`webpageName`** (String): Your application name displayed to users
|
|
264
|
+
- **`autoFetch`** (Boolean, default: `true`): Enable automatic API calls after approval
|
|
265
|
+
- **`onComplete`** (Function): Callback when data request completes
|
|
266
|
+
- **`proofMode`** (Boolean, default: `false`): Enable proof mode for verification
|
|
267
|
+
- **`testMode`** (Boolean, default: `false`): Enable test mode for development
|
|
268
|
+
|
|
269
|
+
#### Laravel-Specific Props
|
|
270
|
+
|
|
271
|
+
- **`buttonType`** (String): `'pill'`, `'icon'`, or `'rounded'`
|
|
272
|
+
- **`size`** (String): `'small'`, `'medium'`, or `'large'`
|
|
273
|
+
- **`textColor`** (String): Button text color
|
|
274
|
+
- **`disabled`** (Boolean): Disable the button
|
|
275
|
+
|
|
276
|
+
### 5. Laravel Integration Guide
|
|
277
|
+
|
|
278
|
+
For complete Laravel integration examples and advanced configuration, see our [Laravel Integration Guide](./LARAVEL_INTEGRATION_GUIDE.md).
|
|
279
|
+
|
|
280
|
+
The guide covers:
|
|
281
|
+
|
|
282
|
+
- ✅ **Blade Templates**: Direct integration with PHP templates
|
|
283
|
+
- ✅ **Vue.js Components**: Reactive Vue components
|
|
284
|
+
- ✅ **React Components**: React integration patterns
|
|
285
|
+
- ✅ **Vite Plugins**: Custom Vite plugins for Laravel
|
|
286
|
+
- ✅ **Mobile Optimization**: Automatic mobile detection
|
|
287
|
+
- ✅ **Production Deployment**: Build and deployment strategies
|
|
288
|
+
|
|
289
|
+
### 6. Migration from v1.x
|
|
290
|
+
|
|
291
|
+
**Before (v1.x - Complex)**:
|
|
292
|
+
|
|
293
|
+
```jsx
|
|
294
|
+
// Old complex setup with manual event listeners
|
|
295
|
+
useEffect(() => {
|
|
296
|
+
const handleMessage = (event) => {
|
|
297
|
+
if (
|
|
298
|
+
event.data?.source === "content-script" &&
|
|
299
|
+
event.data?.type === "API_URL_RESPONSE"
|
|
300
|
+
) {
|
|
301
|
+
const { APIurl, accessToken } = event.data;
|
|
302
|
+
// Manual API call handling
|
|
303
|
+
fetch(APIurl, {
|
|
304
|
+
method: "POST",
|
|
305
|
+
headers: { Authorization: `Bearer ${accessToken}` },
|
|
306
|
+
body: JSON.stringify(InputData),
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
};
|
|
310
|
+
window.addEventListener("message", handleMessage);
|
|
311
|
+
return () => window.removeEventListener("message", handleMessage);
|
|
312
|
+
}, []);
|
|
313
|
+
|
|
314
|
+
<Onairos requestData={complexRequestObject} webpageName={webpageName} />;
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
**After (v2.0 - Simple)**:
|
|
318
|
+
|
|
319
|
+
```jsx
|
|
320
|
+
// New simplified approach
|
|
321
|
+
<OnairosButton
|
|
322
|
+
requestData={["email", "profile"]}
|
|
323
|
+
webpageName="My App"
|
|
324
|
+
onComplete={(result) => {
|
|
325
|
+
// API call already made automatically
|
|
326
|
+
console.log("User data:", result.apiResponse);
|
|
327
|
+
}}
|
|
328
|
+
/>
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
### 7. Data Types Available
|
|
332
|
+
|
|
333
|
+
- **`email`**: Email address for account identification
|
|
334
|
+
- **`profile`**: Basic profile information and preferences
|
|
335
|
+
- **`social`**: Connected social media accounts
|
|
336
|
+
- **`activity`**: Usage patterns and interactions
|
|
337
|
+
- **`preferences`**: User settings and customization choices
|
|
338
|
+
|
|
339
|
+
### 8. Error Handling
|
|
340
|
+
|
|
341
|
+
The component includes comprehensive error handling:
|
|
342
|
+
|
|
343
|
+
```jsx
|
|
344
|
+
<OnairosButton
|
|
345
|
+
requestData={["email"]}
|
|
346
|
+
webpageName="My App"
|
|
347
|
+
onComplete={(result) => {
|
|
348
|
+
if (result.apiError) {
|
|
349
|
+
console.error("API Error:", result.apiError);
|
|
350
|
+
// Handle error appropriately
|
|
351
|
+
} else if (result.apiResponse) {
|
|
352
|
+
console.log("Success:", result.apiResponse);
|
|
353
|
+
// Process data
|
|
354
|
+
}
|
|
355
|
+
}}
|
|
356
|
+
/>
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
### 9. Browser & Platform Compatibility
|
|
360
|
+
|
|
361
|
+
**Desktop Browsers:**
|
|
362
|
+
- ✅ Chrome 80+
|
|
363
|
+
- ✅ Firefox 75+
|
|
364
|
+
- ✅ Safari 13+
|
|
365
|
+
- ✅ Edge 80+
|
|
366
|
+
|
|
367
|
+
**Mobile Browsers:**
|
|
368
|
+
- ✅ iOS Safari 13+
|
|
369
|
+
- ✅ Chrome Mobile (Android)
|
|
370
|
+
- ✅ Samsung Internet
|
|
371
|
+
- ✅ Firefox Mobile
|
|
372
|
+
|
|
373
|
+
**Mobile Frameworks:**
|
|
374
|
+
- ✅ Capacitor (iOS/Android)
|
|
375
|
+
- ✅ React Native WebView
|
|
376
|
+
- ✅ Ionic
|
|
377
|
+
|
|
378
|
+
### 10. Troubleshooting
|
|
379
|
+
|
|
380
|
+
**Popup Blocked**: Ensure popups are allowed for your domain in browser settings. On mobile devices, OAuth automatically uses redirects instead of popups.
|
|
381
|
+
|
|
382
|
+
**API Calls Failing**:
|
|
383
|
+
- If you have a developer account with an API key, domain registration is handled manually by the Onairos team
|
|
384
|
+
- If you don't have an API key, verify your domain is registered in the [developer console](https://Onairos.uk/dev-board)
|
|
385
|
+
- Check that your API key is included in requests if using the SDK
|
|
386
|
+
|
|
387
|
+
**Data Not Loading**: Check browser console for errors and ensure proper integration.
|
|
388
|
+
|
|
389
|
+
**Mobile/Capacitor Issues**:
|
|
390
|
+
- OAuth popups automatically convert to redirects on mobile
|
|
391
|
+
- Browser extension features are not available in Capacitor apps
|
|
392
|
+
- Ensure localStorage is enabled in your Capacitor configuration
|
|
393
|
+
|
|
394
|
+
### 11. Support
|
|
395
|
+
|
|
396
|
+
For issues or questions:
|
|
397
|
+
|
|
398
|
+
- Check the [troubleshooting guide](./POPUP_IMPLEMENTATION_README.md)
|
|
399
|
+
- Review browser console for errors
|
|
400
|
+
- Contact support with detailed error information
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## Legacy Documentation (v1.x)
|
|
405
|
+
|
|
406
|
+
_The following sections document the previous complex implementation for reference:_
|
|
407
|
+
|
|
408
|
+
### Legacy Request Object Format
|
|
409
|
+
|
|
410
|
+
Previously required complex request objects:
|
|
411
|
+
|
|
412
|
+
```json
|
|
413
|
+
"RequestObject":{
|
|
414
|
+
"Small": {
|
|
415
|
+
"type":"Personality",
|
|
416
|
+
"descriptions":"Insight into your Interests",
|
|
417
|
+
"reward":"10% Discount"
|
|
418
|
+
},
|
|
419
|
+
"Medium":{
|
|
420
|
+
"type":"Personality",
|
|
421
|
+
"descriptions":"Insight into your Interests",
|
|
422
|
+
"reward":"2 USDC"
|
|
423
|
+
},
|
|
424
|
+
"Large":{
|
|
425
|
+
"type":"Personality",
|
|
426
|
+
"descriptions":"Insight into your Interests",
|
|
427
|
+
"reward":"2 USDC"
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
### Legacy API Usage
|
|
433
|
+
|
|
434
|
+
Previously required manual event handling:
|
|
435
|
+
|
|
436
|
+
```jsx
|
|
437
|
+
export default async function UseAPIURL(event) {
|
|
438
|
+
if (
|
|
439
|
+
event.data &&
|
|
440
|
+
event.data.source === "content-script" &&
|
|
441
|
+
event.data.type === "API_URL_RESPONSE"
|
|
442
|
+
) {
|
|
443
|
+
const { APIurl, accessToken } = event.data;
|
|
444
|
+
await fetch(APIurl, {
|
|
445
|
+
method: "POST",
|
|
446
|
+
headers: {
|
|
447
|
+
"Content-Type": "application/json",
|
|
448
|
+
Authorization: `Bearer ${accessToken}`,
|
|
449
|
+
},
|
|
450
|
+
body: JSON.stringify(InputData),
|
|
451
|
+
})
|
|
452
|
+
.then(async (data) => {
|
|
453
|
+
// process Onairos Data
|
|
454
|
+
})
|
|
455
|
+
.catch((error) => console.error(error));
|
|
456
|
+
}
|
|
457
|
+
}
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
_This manual approach is no longer needed with v2.0's autoFetch functionality._
|
|
461
|
+
|
|
462
|
+
### Legacy Output Format
|
|
463
|
+
|
|
464
|
+
API still responds with the same format:
|
|
465
|
+
|
|
466
|
+
```json
|
|
467
|
+
{
|
|
468
|
+
"output": [[[0.9998]], [[0.9999]], [[0.9922]], [[0.0013]]]
|
|
469
|
+
}
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
### Integration Notes
|
|
473
|
+
|
|
474
|
+
When integrating the onairos package into your application, ensure your Webpack configuration handles dynamic imports correctly and serves the necessary chunk files from `node_modules/onairos/dist`.
|