# OEM Integration Overview

> Embed the full Glassly experience (miniapps, the Glassly Miniapp Store, and the developer ecosystem) inside your own phone app, driving your own smart glasses.

Source: https://docs.glassly.ai/glasses-oems/overview/

**Status: planned.** The Glassly OEM Integration Engine is planned for release by the
**end of 2026**, so the adapter and capability samples below describe the design, not a
shipping API. To start an integration, reach out to [help@glassly.ai](mailto:help@glassly.ai).

## What it is

The **Glassly OEM Integration Engine** is all of Glassly's phone-side logic packaged as a library you embed in your **own** app. Your users stay in your app and on your brand, but they get the full Glassly experience: the Glassly Miniapp Store, installable miniapps, and the same developer ecosystem that powers the Glassly App.

The engine owns everything between your glasses and Glassly's backend services:

- **Glassly Miniapp Store + runtime**: discover, install, and run miniapps on the phone.
- **Glasses I/O**: display rendering, microphone/audio routing, and the rest of the glasses feature set.
- **Backend connectivity**: talking to Glassly's backend services for the store, transcription, translation, streaming, and photos.

You bring two things: **your glasses** (and however you talk to them over Bluetooth) and **your app** (its shell, navigation, and branding).

```mermaid
%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TB
  subgraph App["Your App: your branding, your user experience, your customer relationship"]
    direction TB
    subgraph Engine["Glassly OEM Integration Engine Library"]
      direction TB
      F1["Miniapp Runtime"]
      F2["Glassly Miniapp Store"]
      F3["Developer ecosystem"]
      F1 ~~~ F2
      F2 ~~~ F3
    end
    Adapter["Your Glasses Adapter"]
    Engine --> Adapter
  end

  Adapter --> Glasses["Your Smart Glasses"]

  classDef app fill:#f8fafc,stroke:#cbd5e1,stroke-width:1px,color:#0f172a
  classDef engine fill:#eef2ff,stroke:#6366f1,stroke-width:1.5px,color:#1e1b4b
  classDef feature fill:#ffffff,stroke:#a5b4fc,stroke-width:1px,color:#312e81
  classDef adapter fill:#ecfdf5,stroke:#10b981,stroke-width:1.5px,color:#064e3b
  classDef external fill:#f1f5f9,stroke:#64748b,stroke-width:1px,color:#0f172a

  class App app
  class Engine engine
  class F1,F2,F3 feature
  class Adapter adapter
  class Glasses external

  linkStyle 0 stroke:none
  linkStyle 1 stroke:none
  linkStyle default stroke:#94a3b8,stroke-width:1.5px
```

## Integrating in four moves

### 1. Install the engine

Add the engine to your app, using the path that matches how your app is built:

- **React Native / Expo**: install the engine as a module.
- **Native (iOS / Android)**: embed the native libraries (iOS framework, Android library) directly.
- **Flutter**: embed the native libraries and bridge them into Flutter through platform channels.

### 2. Configure the engine

You give the engine a single configuration when your app boots. The engine manages its own settings internally. The only things you hand it are what's yours:

- **Your identity**: how your users are signed in (see [Backend connectivity](#3-connect-to-the-backend-services)).
- **Optional proxy**: if you route Glassly's backend services through your own infrastructure, you pass your proxy here (see below).

### 3. Connect to the backend services

The engine talks to two tiers of Glassly backend services:

- **Glassly Runtime Services.** The capabilities the engine relies on: speech-to-text, text-to-speech, translation, live streaming, and photo handling. Self-hostable and/or proxyable (run your own, route through your proxy, or both).
- **Glassly Cloud Core Services.** The Glassly Miniapp Store, the developer console, and the OEM APIs. Proxyable only (always Glassly-hosted, optionally reached through your proxy).

The engine also includes **on-device STT/TTS** as a fallback for offline or degraded-network scenarios. Cloud STT/TTS is the recommended path for production quality; on-device is the safety net.

**Identity.** Your users sign in through *your* identity system. They never create a Glassly account. The engine exchanges your app's signed-in identity for a Glassly-scoped session, so your users see only your login.

**Routing through your proxy.** You don't stand up a separate proxy service. When you configure the engine, you give it your proxy details and it routes all backend traffic through your infrastructure. Without a proxy, the engine talks to the backend services directly.

### 4. Register your glasses

The engine talks to glasses through a **Glasses Adapter**: a contract that describes one model of glasses. You implement an adapter for your hardware, in your own app, against your own Bluetooth stack, and register it at startup. The engine then treats your glasses as a first-class device, exactly like the glasses Glassly ships.

An adapter declares two things: **capabilities** (what your glasses have) and **behavior** (how to drive each feature over your BLE link). You declare and implement only what your hardware actually has.

**Example: a display + mic device with a touchpad and an IMU (no camera).** This is the common OEM shape today (think Even Realities G2): a monochrome text display, a microphone, a capacitive touchpad, and an IMU, no camera. Here's the whole adapter for one.

**Declare your capabilities.** Same capability shape the engine uses for every device it supports. Fill it in for your hardware. This device declares a display, a microphone, a touch surface, and an IMU, and leaves the rest out:

```ts
const capabilities: Capabilities = {
  modelName: "Acme Vision One",

  // Every capability is a `hasX` flag plus an `x` block (null when absent).
  hasDisplay: true,
  display: {
    count: 1,
    isColor: false,
    color: "green",
    canDisplayBitmap: true,
    resolution: {width: 640, height: 200},
    fieldOfView: {horizontal: 25},
    maxTextLines: 5,
    adjustBrightness: true,

    // Scene API: the drawable canvas and what the firmware can draw.
    width: 640,
    height: 200,
    canPosition: true,
    maxTextElements: 6,
    maxImageElements: 4,
    shapes: ["rect"],
    intensityLevels: 16,
    partialUpdate: true,
  },

  hasMicrophone: true,
  microphone: {count: 1, hasVAD: false},

  // The touchpad is a button surface; input events are declared per button.
  hasButton: true,
  button: {
    count: 1,
    buttons: [
      {
        type: "swipe1d",
        events: ["TAP", "DOUBLE_TAP", "LONG_PRESS", "SWIPE_UP", "SWIPE_DOWN"],
        isCapacitive: true,
      },
    ],
  },

  hasIMU: true,
  imu: {hasAccelerometer: true, hasGyroscope: true, hasCompass: true},

  // A capability the device doesn't have is `false` + `null`.
  hasCamera: false,
  camera: null,
  hasSpeaker: false,
  speaker: null,
  hasLight: false,
  light: null,

  power: {hasExternalBattery: false},
  hasWifi: false,
  hasOta: false,
}
```

**Implement the behavior.** Each method drives your hardware over your BLE link. The engine never calls a method for a capability you didn't declare:

```ts
const acmeAdapter: GlassesAdapter = {
  model: "Acme Vision One",
  capabilities,
  displayProfile: acmeDisplayProfile,   // how your screen renders text (size, monochrome)

  // Connection lifecycle
  async scan(onFound)      { /* discover your glasses over BLE; call onFound per device */ return stopScan },
  async connect(device)    { /* your BLE connect */ },
  async disconnect()       { /* your BLE disconnect */ },
  async forget()           { /* unpair / clear the bond */ },
  onStatusChange(cb)       { /* connected, battery, firmware version, etc. */ return unsubscribe },

  // Display
  async displayText(text)            { /* push a text wall */ },
  async displayDoubleText(top, bot)  { /* two-region text layout */ },
  async displayBitmap(bmp)           { /* push a bitmap */ },
  async clearDisplay()               { /* clear the screen */ },
  async setBrightness(n, auto)       { /* set brightness (or auto) */ },
  async setHeadUpAngle(deg)          { /* angle at which content shows on head-up */ },

  // Dashboard (a built-in overlay the engine drives)
  async showDashboard()              { /* show the dashboard overlay */ },
  async setDashboardMenu(items)      { /* set dashboard menu entries */ },
  async setDashboardPosition(h, d)   { /* position the dashboard */ },

  // Microphone
  async setMicEnabled(on)  { /* turn the mic on/off */ },
  onAudio(cb)              { /* stream mic audio up to the engine */ return unsubscribe },

  // Input (touchpad + buttons)
  onInputEvent(cb)         { /* report any declared input event: taps, swipes, presses, head up / down */ return unsubscribe },

  // IMU (sensor feed, not input)
  async setImuEnabled(on)  { /* start/stop the IMU feed */ },
  onImuData(cb)            { /* stream orientation / motion when a miniapp subscribes */ return unsubscribe },
}

registerGlassesAdapter(acmeAdapter)
```

That's the whole integration. The engine handles everything above it: which miniapps run, how their content is laid out for your screen, routing your mic audio to speech-to-text.

Your adapter lives **in your app**: your Bluetooth protocol, your firmware, your transport stay private to you. You never submit glasses code to Glassly, and you never wait on a Glassly release to ship a hardware change.

## Why this works

- **Your hardware, no fork.** The Glasses Adapter is your private extension point. Add or change a model entirely within your app.
- **Your app, your brand.** Users never leave your app or see a Glassly account. The engine is a library inside your experience, not a separate app.
- **One shared ecosystem.** Every OEM's users and developers live in the same Glassly ecosystem. That's what makes the Glassly Miniapp Store worth being part of.
- **You decide what you host.** Use Glassly's backend services as-is or route them all through your own proxy.
