Skip to content

QUICKSTART.md

Latest commit

 

History

History
202 lines (145 loc) · 6.03 KB

QUICKSTART.md

File metadata and controls

202 lines (145 loc) · 6.03 KB
Raw

Quick Start Guide

Get started with the Offline Protocol SDK in 5 minutes.

Want to see a complete working example? Check out the React Native Example App that demonstrates all SDK features.

For React Native Developers

1. Install

npm install @offline-protocol/mesh-sdk
cd ios && pod install  # iOS only

2. Initialize

import { OfflineProtocol, MessagePriority } from '@offline-protocol/mesh-sdk';

const protocol = new OfflineProtocol({
  appId: 'my-app',
  userId: 'current-user-id',
});

await protocol.start();

3. Send Messages

const messageId = await protocol.sendMessage({
  recipient: 'friend-user-id',
  content: 'Hello!',
  priority: MessagePriority.Medium,
});

4. Receive Messages

protocol.on('message_received', (event) => {
  console.log(`From ${event.sender}: ${event.content}`);
  // Update your UI here
});

5. Monitor Status

protocol.on('transport_switched', (event) => {
  console.log(`Now using ${event.to}`);
});

// Fires once this device has actually been carrying traffic for other
// devices — it reports what happened, not what the device is capable of.
protocol.on('relay_promoted', () => {
  console.log('This device is now relaying for the mesh!');
});

6. Report the Battery

No transport can observe the host's battery, so the SDK only learns it from you. Until it does, DORS energy scoring skips its battery term, the floor that stops a dying phone carrying other people's traffic never applies, and mesh forwarding runs at full effort on every device — a healthy laptop and a phone at 20% carry an equal share, rather than the laptop carrying more.

(The relay events are the exception: they report traffic this device has actually carried, so they fire with or without a battery reading.)

// On start, and again on each platform battery notification.
await protocol.setBatteryState(level, isCharging);

Report isCharging where the platform provides it: a charging device is deliberately excused the soft minBatteryForRelay floor, so sending the level alone strips relay duty from plugged-in devices that should keep it.

That's it! Your app now works offline with automatic transport switching.

For Android Developers

Native (no React Native) integration needs the full ProtocolConfig, permission setup, and a call to initializeMls(secureStorage, protocolStateStorage) with two storage providers you supply — there is no auto-initialization on the native path, and encryption is fail-closed, so sends fail until MLS is initialized. See the Android Integration Guide for the complete walkthrough — the snippet below is just the shape.

1. Build Rust Library

cargo build --release --target aarch64-linux-android

This produces liboffline_protocol_uniffi.so.

2. Add to Android Project

Copy it into app/src/main/jniLibs/arm64-v8a/ as libuniffi_offline_protocol.so (the name UniFFI's loader expects). The scripts/build-uniffi-android.sh helper builds every ABI and renames automatically.

3. Use in Kotlin

import uniffi.offline_protocol.*

// Build `config` with the full ProtocolConfig(...) — see the Android integration guide.
val protocol = OfflineProtocol(config)
protocol.start()

val messageId = protocol.sendMessage(
    recipient = "friend",
    content = "Hello!",
    priority = MessagePriority.HIGH,
    replyToMsg = null,
)

For iOS Developers

Native (no React Native) integration needs the full ProtocolConfig, permission setup, and a call to initializeMls(secureStorage:protocolStateStorage:) with two storage providers you supply — there is no auto-initialization on the native path, and encryption is fail-closed, so sends fail until MLS is initialized. See the iOS Integration Guide for the complete walkthrough — the snippet below is just the shape.

1. Build Rust Library

cargo build --release --target aarch64-apple-ios

This produces liboffline_protocol_uniffi.a.

2. Add to Xcode

Add liboffline_protocol_uniffi.a (or the device/simulator slices from scripts/build-uniffi-ios.sh) and the generated offline_protocol.swift to your project.

3. Use in Swift

// Build `config` with the full ProtocolConfig(...) — see the iOS integration guide.
let mesh = try OfflineProtocol(config: config)
try mesh.start()

let messageId = try mesh.sendMessage(
    recipient: "friend",
    content: "Hello!",
    priority: .high,
    replyToMsg: nil
)

Next Steps

Common Issues

React Native: "Module not found"

Make sure you've run:

  • iOS: cd ios && pod install
  • Android: Rebuild the app

Android: "Library not found"

Ensure libuniffi_offline_protocol.so is in the correct jniLibs folder for your architecture.

iOS: "Undefined symbols"

Link against the Rust static library in Xcode Build Settings.

Getting Help