OMobile v1.0.0

What OMobile does

A complete mobile backend as a WordPress plugin — 19 database tables, a full REST API, three push drivers, and an analytics suite. No external service accounts needed beyond your push provider credentials.

Getting installed

PHP// Override the JWT secret (takes precedence over the wp_options stored secret)
define( 'OMOBILE_JWT_SECRET', 'your-256-bit-secret-here' );

// Keep all data when deleting the plugin
define( 'OMOBILE_KEEP_DATA_ON_UNINSTALL', true );

19 database tables

All tables use the WordPress table prefix (default wp_). Created on activation via dbDelta.

Auth overview

Two authentication methods: JWT (for mobile users) and API Keys (for server-to-server and CI). All mobile endpoints also require the X-Om-Install-Id header.

JWT authentication

OMobile uses HS256 JWTs — pure PHP with base64url encoding, no external library.

HTTPPOST /wp-json/omobile/v1/auth/login
Content-Type: application/json
X-Om-Install-Id: <your-device-uuid>

{
  "username": "user@example.com",
  "password": "secret"
}

RESPONSE{
  "access_token":  "eyJ…",
  "refresh_token": "eyJ…",
  "user": {
    "id":           1,
    "display_name": "Jane Doe",
    "email":        "user@example.com"
  }
}

HTTPAuthorization: Bearer <access_token>
X-Om-Install-Id: <your-device-uuid>

HTTPPOST /wp-json/omobile/v1/auth/refresh
Content-Type: application/json

{ "refresh_token": "eyJ…" }

Refresh token rotation

Refresh tokens use a rotation + reuse detection pattern designed to catch token theft in real time.

• Each refresh issues a new token and invalidates the old one immediately.
• A 30-second reuse window tolerates race conditions where two requests use the same token near-simultaneously.
• If a consumed token is presented outside the reuse window, the entire chain is revoked — all sessions for that user on that device are ended immediately, indicating the old token was stolen and replayed.

Login throttling

Failed login attempts are rate-limited per identifier (username/email) and per IP simultaneously.

Implemented with WordPress transients. The omobile_login_attempts table records the events for the audit log; the transient drives the actual blocking logic.

API keys

An alternative to JWT for server-to-server or CI integrations. Only the SHA-256 hash is ever stored — the raw key is shown once at creation and never again.

BASHwp omobile create-api-key --name="My App"

REST API reference

Base URL: https://yoursite.com/wp-json/omobile/v1/. All mobile endpoints require X-Om-Install-Id with a unique per-install UUID.

RESPONSE{
  "flags": {
    "new_checkout_flow": {
      "value": true, "rollout_pct": 50, "in_rollout": true
    }
  },
  "remote_config": {
    "min_cart_value": 10,
    "support_email": "help@example.com"
  },
  "announcements": [],
  "version_check": {
    "status": "supported", "force_update": false, "message": ""
  }
}

Feature flags

Key/value pairs returned under flags in the /config response. Support gradual rollouts down to individual devices.

Remote config

Arbitrary key/value pairs returned under remote_config in the /config response. Change values without a new app release.

• Feature toggles without code deploys
• Store URLs, support emails, deep-link URIs
• Minimum cart values, discount thresholds
• Any server-controlled constant

Supports the same 4 types as feature flags: string, number, boolean, json.

Push notifications

Three push drivers — choose one based on your app stack.

BASHwp omobile dispatch-push

FCM HTTP v1

OMobile uses the FCM HTTP v1 API — not the deprecated legacy server key. Credentials are exchanged for an OAuth2 access token and cached for 55 minutes.

APNS token-based

Uses .p8 key files — token-based auth never expires like certificates do. The ES256 JWT is cached for 55 minutes (Apple allows up to 1 hour).

Expo push setup

Select Expo as the push driver. No credentials needed — OMobile posts to the Expo Push API at https://exp.host/--/api/v2/push/send.

Devices must use the expo-notifications SDK and register their Expo push token via POST /devices/register.

Versioning & force update

Define version rules in the Versions tab. Each rule controls how the app behaves based on the version and platform reported in the /config request.

The /config response includes a version_check object based on the requesting app's version and platform query params.

Crash reporting & grouping

Crashes are submitted by the app and de-duplicated server-side using SHA-256 fingerprinting — duplicate crashes never create new rows.

JSONPOST /omobile/v1/crashes/report
{
  "message":     "NullPointerException in CartScreen",
  "stack_trace": "...",
  "platform":    "android",
  "app_version": "2.1.0",
  "os_version":  "14"
}

Analytics methods

Computed from omobile_sessions, omobile_telemetry_rollup, and omobile_devices. All methods available from WP-CLI via wp omobile analytics.

Event telemetry

Apps submit events in batches. Raw events are rolled up daily into omobile_telemetry_rollup.

JSONPOST /omobile/v1/telemetry/events
{
  "events": [
    { "name": "product_view", "properties": { "sku": "ABC123" } },
    { "name": "add_to_cart",  "properties": { "sku": "ABC123", "qty": 2 } }
  ]
}

Each rollup row contains: date, platform, app_version, event_name, event_count. Run the rollup manually:

BASHwp omobile rollup

Devices & segments

JSON{ "platform": "ios" }
{ "platform": "android", "min_app_version": "2.0.0" }
{ "locale": "en-US" }

In-app announcements

Returned in the /config response. Displayed client-side as banners, modals, or toasts.

Announcements support title, body, an active flag, and an optional expires_at timestamp that auto-hides the announcement.

Content health

A cron-scheduled checker that flags WordPress posts with content issues — surfaced in the Content Health tab with direct edit links.

• Missing featured image
• Empty excerpt
• Empty post content

Outbound webhooks

Register webhook URLs to receive real-time HMAC-signed events from OMobile.

JSON{
  "event":     "crash.new",
  "timestamp": "2026-04-25T10:00:00Z",
  "data": { ... }
}

HTTPX-OMobile-Signature: sha256=<HMAC-SHA256 of raw body using webhook secret>

Config snapshots

Snapshots capture the current state of all feature flags and remote config at a point in time. Use them as a safety net before releases.

BASHwp omobile snapshot --label="Before v2.1 release"

Onboarding wizard

Guides new installations through 6 steps. Progress stored in wp_options under omobile_onboarding_step.

PHP// Reset the wizard (also available in Setup tab)
OMobile_Onboarding::reset();

Demo mode

One-click demo data seeding for exploring the plugin without a connected app.

BASHwp omobile seed-demo   # seed demo data
wp omobile clear-demo  # remove all demo data

Both operations are also available in the admin UI under the Demo tab.

WP-CLI commands

All commands use the wp omobile prefix.

SDK quick start

Copy-paste integration for the two most common mobile stacks. Store tokens in secure storage — never in plain AsyncStorage or shared preferences.

JSimport * as SecureStore from 'expo-secure-store';
import { Platform } from 'react-native';
import Constants from 'expo-constants';

const BASE_URL  = 'https://yoursite.com/wp-json/omobile/v1/';
const INSTALL_ID = Constants.installationId; // stable UUID per install

async function authHeaders() {
  const token = await SecureStore.getItemAsync('access_token');
  return {
    'Authorization': `Bearer ${token}`,
    'X-Om-Install-Id': INSTALL_ID,
    'Content-Type': 'application/json',
  };
}

// Login
export async function login(username, password) {
  const res  = await fetch(`${BASE_URL}auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Om-Install-Id': INSTALL_ID },
    body: JSON.stringify({ username, password }),
  });
  const data = await res.json();
  if (data.access_token) {
    await SecureStore.setItemAsync('access_token',  data.access_token);
    await SecureStore.setItemAsync('refresh_token', data.refresh_token);
  }
  return data;
}

// Get config (flags + remote config)
export async function getConfig() {
  const res = await fetch(
    `${BASE_URL}config?platform=${Platform.OS}&version=${Constants.expoConfig.version}`,
    { headers: await authHeaders() }
  );
  return res.json();
}

// Register device + push token
export async function registerDevice(pushToken) {
  const res = await fetch(`${BASE_URL}devices/register`, {
    method: 'POST',
    headers: await authHeaders(),
    body: JSON.stringify({
      platform:    Platform.OS,
      app_version: Constants.expoConfig.version,
      push_token:  pushToken,
      locale:      'en-US',
      timezone:    Intl.DateTimeFormat().resolvedOptions().timeZone,
    }),
  });
  return res.json();
}

// Submit telemetry events
export async function trackEvents(events) {
  await fetch(`${BASE_URL}telemetry/events`, {
    method: 'POST',
    headers: await authHeaders(),
    body: JSON.stringify({ events }),
  });
}

// Report crash
export async function reportCrash(error) {
  await fetch(`${BASE_URL}crashes/report`, {
    method: 'POST',
    headers: await authHeaders(),
    body: JSON.stringify({
      message:     error.message,
      stack_trace: error.stack,
      platform:    Platform.OS,
      app_version: Constants.expoConfig.version,
      os_version:  Platform.Version.toString(),
    }),
  });
}

DARTimport 'package:http/http.dart' as http;
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'dart:convert';
import 'dart:io';

const baseUrl  = 'https://yoursite.com/wp-json/omobile/v1/';
final _storage = FlutterSecureStorage();
const installId = 'YOUR-UUID-HERE'; // generate once, store persistently

Future<Map<String, String>> authHeaders() async {
  final token = await _storage.read(key: 'access_token') ?? '';
  return {
    'Authorization': 'Bearer $token',
    'X-Om-Install-Id': installId,
    'Content-Type': 'application/json',
  };
}

// Login
Future<Map<String, dynamic>> login(String username, String password) async {
  final res = await http.post(
    Uri.parse('${baseUrl}auth/login'),
    headers: { 'Content-Type': 'application/json', 'X-Om-Install-Id': installId },
    body: jsonEncode({ 'username': username, 'password': password }),
  );
  final data = jsonDecode(res.body) as Map<String, dynamic>;
  if (data['access_token'] != null) {
    await _storage.write(key: 'access_token',  value: data['access_token']);
    await _storage.write(key: 'refresh_token', value: data['refresh_token']);
  }
  return data;
}

// Get config
Future<Map<String, dynamic>> getConfig(String version) async {
  final platform = Platform.isIOS ? 'ios' : 'android';
  final res = await http.get(
    Uri.parse('${baseUrl}config?platform=$platform&version=$version'),
    headers: await authHeaders(),
  );
  return jsonDecode(res.body);
}

// Register device
Future<void> registerDevice(String pushToken, String version) async {
  final platform = Platform.isIOS ? 'ios' : 'android';
  await http.post(
    Uri.parse('${baseUrl}devices/register'),
    headers: await authHeaders(),
    body: jsonEncode({ 'platform': platform, 'app_version': version, 'push_token': pushToken }),
  );
}

// Track events
Future<void> trackEvents(List<Map<String, dynamic>> events) async {
  await http.post(
    Uri.parse('${baseUrl}telemetry/events'),
    headers: await authHeaders(),
    body: jsonEncode({ 'events': events }),
  );
}

// Report crash
Future<void> reportCrash(Object error, StackTrace stack) async {
  final platform = Platform.isIOS ? 'ios' : 'android';
  await http.post(
    Uri.parse('${baseUrl}crashes/report'),
    headers: await authHeaders(),
    body: jsonEncode({
      'message':     error.toString(),
      'stack_trace': stack.toString(),
      'platform':    platform,
    }),
  );
}

Admin UI

Accessed via OMobile in the WordPress admin menu. Single page at admin.php?page=omobile — no WP sidebar sub-items.

Filters & actions

PHP// Override the storage adapter (default: transients)
add_filter( 'omobile_storage_adapter', function( $adapter ) {
    return new My_Redis_Adapter(); // must implement OMobile_Storage_Interface
} );

// Modify config payload before it's returned to the app
add_filter( 'omobile_config_payload', function( $payload, $install_id ) {
    $payload['custom_key'] = 'custom_value';
    return $payload;
}, 10, 2 );

// Control which capability manages OMobile (default: 'manage_omobile')
add_filter( 'omobile_admin_cap', function() {
    return 'manage_options';
} );

PHP// Fires after a crash is reported
add_action( 'omobile_crash_reported', function( $crash_id, $data ) {
    // notify Slack, create GitHub issue, etc.
}, 10, 2 );

// Fires after a push notification is dispatched
add_action( 'omobile_push_dispatched', function( $queue_id, $result ) {
    // log result, update campaign stats, etc.
}, 10, 2 );

// Fires after a feature flag is updated
add_action( 'omobile_flag_updated', function( $flag_key, $new_value ) {
    // trigger downstream cache invalidation, etc.
}, 10, 2 );

Uninstall & cleanup

Deactivating leaves all data intact for a clean reactivation. Deleting the plugin via the WordPress UI runs uninstall.php and removes everything.