FlameAPI Reference

Your mini-apps have access to native device capabilities through window.flameAPI. This API provides access to camera, location, sensors, storage, authentication, and backend services.

Getting Started

All API calls must be made after the bridge is ready:

window.addEventListener('miniApiReady', () => {
  const api = window.flameAPI;
  // API is now available
});

Available APIs

Device Hardware

• Camera - Take photos, select from gallery, pick multiple images
• Flashlight - Control device torch with intensity
• Accelerometer - Read motion sensor data
• Haptics - Trigger vibration and tactile feedback

Device Services

• Geolocation - Get current position, track movement
• Geocoder - Convert addresses to coordinates and vice versa
• Audio Recorder - Record voice and audio
• Native Audio - Play audio files with controls

Data & Backend

• Storage - Persistent key-value storage per app
• Auth - User authentication (email, social providers)
• Backend API - Call your deployed backend endpoints

---

Camera

Take photos or select images from the gallery.

// Check/request permissions
const hasPermission = await api.camera.requestPermissions();

// Take a photo
const photo = await api.camera.getPhoto({
  quality: 90, // 0-100
  source: 'camera', // 'camera' | 'photos' | 'prompt'
  resultType: 'uri', // 'uri' | 'base64' | 'dataUrl'
  allowEditing: false,
  width: 300, // optional resize
  height: 300,
});
// Returns: { webPath, dataUrl, base64String, format, saved }

// Pick multiple from gallery
const photos = await api.camera.pickImages({ limit: 5, quality: 90 });
// Returns: [{ webPath, format }, ...]

---

Flashlight

Control the device flashlight/torch.

// Check availability
const available = await api.flashlight.isAvailable();

// Turn on (with optional intensity 0.0-1.0)
await api.flashlight.switchOn({ intensity: 0.5 });

// Turn off
await api.flashlight.switchOff();

---

Accelerometer

Read device motion sensor data. Data is delivered via postMessage.

// Start receiving data
await api.accelerometer.start();

// Listen for updates
window.addEventListener('message', (event) => {
  if (event.data.type === 'accelerometerData') {
    const { x, y, z } = event.data.data;
    // Values in m/s²
  }
});

// Stop when done
await api.accelerometer.stop();

---

Haptics

Trigger tactile feedback and vibrations.

// Impact feedback
await api.haptics.impact('light'); // 'light' | 'medium' | 'heavy'

// Notification feedback
await api.haptics.notification('success'); // 'success' | 'warning' | 'error'

// Custom vibration (milliseconds)
await api.haptics.vibrate(300);

// Selection feedback (for pickers/scrolling)
await api.haptics.selectionChanged();

---

Geolocation

Access device location services.

// Request permission
const hasPermission = await api.geolocation.requestPermissions();

// Get current position
const pos = await api.geolocation.getCurrentPosition();
// Returns: { latitude, longitude, accuracy, altitude, heading, speed, timestamp }

// Watch position changes
const watchId = await api.geolocation.watchPosition();
window.addEventListener('message', (event) => {
  if (event.data.type === 'geolocationUpdate') {
    const { latitude, longitude } = event.data.data;
  }
});

// Stop watching
await api.geolocation.clearWatch(watchId);

---

Geocoder

Convert between addresses and coordinates.

// Address to coordinates
const results = await api.geocoder.forwardGeocode('1600 Amphitheatre Pkwy', 5);
// Returns: [{ latitude, longitude, formattedAddress, ... }]

// Coordinates to address
const addresses = await api.geocoder.reverseGeocode(37.42, -122.08, 1);
// Returns: [{ formattedAddress, locality, countryName, ... }]

---

Audio Recorder

Record audio from the device microphone.

// Request permission
const hasPermission = await api.audioRecorder.requestPermissions();

// Start recording
await api.audioRecorder.startRecording();

// Pause/resume
await api.audioRecorder.pauseRecording();
await api.audioRecorder.resumeRecording();

// Stop and get result
const result = await api.audioRecorder.stopRecording();
// Returns: { uri, duration, blob }

// Check status
const status = await api.audioRecorder.getRecordingStatus();
// Returns: 'INACTIVE' | 'RECORDING' | 'PAUSED'

---

Native Audio

Play audio files with advanced controls.

// Load audio (required before playing)
await api.nativeAudio.preloadFromUrl('my-sound', '/audio/sound.mp3', 1.0);

// Playback controls
await api.nativeAudio.play('my-sound');
await api.nativeAudio.pause('my-sound');
await api.nativeAudio.resume('my-sound');
await api.nativeAudio.stop('my-sound');

// Volume (0.0-1.0)
await api.nativeAudio.setVolume('my-sound', 0.5);

// Get info
const duration = await api.nativeAudio.getDuration('my-sound');
const currentTime = await api.nativeAudio.getCurrentTime('my-sound');
const playing = await api.nativeAudio.isPlaying('my-sound');

// Cleanup
await api.nativeAudio.unload('my-sound');

---

Storage

Persistent key-value storage scoped to each mini-app.

// Store a value (auto-serialized to JSON)
await api.storage.kv.set('preferences', { theme: 'dark', fontSize: 16 });

// Get a value (returns null if not found)
const prefs = await api.storage.kv.get('preferences');

// Remove a value
await api.storage.kv.remove('preferences');

// Clear all storage for this app
await api.storage.kv.clear();

---

Auth

User authentication via Firebase. Requires a deployed backend.

// Email/password
const user = await api.auth.signUp(email, password);
const user = await api.auth.signIn(email, password);
await api.auth.signOut();

// Social providers
const user = await api.auth.signInWithGoogle();
const user = await api.auth.signInWithApple();

// Get current user
const user = await api.auth.getCurrentUser();

// Get token for API calls
const token = await api.auth.getToken();

// Listen for auth changes
const unsubscribe = api.auth.onAuthStateChanged((user) => {
  if (user) console.log('Signed in:', user.email);
});

---

Backend API

Make authenticated calls to your deployed backend.

// Check if backend is deployed
if (!api.backend.workerUrl) {
  console.log('Backend not deployed');
}

// Make API calls
const token = await api.auth.getToken();

// GET request
const data = await api.backend.api('/api/items', { token });

// POST request
await api.backend.api('/api/items', {
  method: 'POST',
  body: { title: 'New Item' },
  token,
});

---

Best Practices

Always Check API Availability

if (!api?.camera) {
  console.log('Camera not available');
  return;
}

Handle Permissions Gracefully

const hasPermission =
  (await api.camera.checkPermissions()) || (await api.camera.requestPermissions());
if (!hasPermission) {
  alert('Camera permission required');
  return;
}

Clean Up Event Listeners

const handler = (e) => {
  /* ... */
};
window.addEventListener('message', handler);

// When done:
window.removeEventListener('message', handler);
await api.accelerometer.stop();

Wrap API Calls in Try-Catch

try {
  await api.flashlight.switchOn();
} catch (error) {
  console.error('Flashlight error:', error);
}

For more detailed examples and patterns, see the Device Hardware and Device Services guides.