Developer manual

Build interfaces, background automations and complete apps using documented Dikciz APIs. The platform shares one command executor across JavaScript, Lua, HTTP, WebSocket and MCP. Android permissions and hardware availability still govern each operation.

Pick a runtime

Build Interface Background logic State and lifetime Start here
Home widget HTML/CSS/browser JavaScript A separate script or app backend when needed Page/widget instance state; WebView follows page visibility JavaScript API
Standalone automation Optional separate widget Lua on_event or headless JavaScript onEvent Script state, policy and event subscriptions Lua API, background JavaScript
Complete custom app HTML/CSS/browser JavaScript Lua or headless JavaScript Independent app state/files, subscriptions, native one-shot timers and alerts App lifecycle and bundle format
External controller or agent Your client Your process Scoped bearer identity, transport sessions and operation-specific retained work Remote connection, token grants

The browser API is window.dikciz and window.selfWidget. A headless backend uses context, not window.dikciz. JavaScript UI calls return Promises; Lua/headless JavaScript command calls are synchronous. All use the same ordinary command names and JSON fields. Their helper names and result-unwrapping behavior differ, as the language references explain.

Complete references

Reference Defines
JavaScript API Every injected bridge/helper, WebView readiness, current widget/item state, file helpers, events, Promise/error behavior and background context.
Lua API Handler, context functions/fields, event envelope, JSON/table conversion, state, actions and runtime limits.
Command reference Every discovered MCP tool, ordinary command type, complete input schema and parameters, token scopes and language invocation pattern.
Token permission reference Every grant ID and definition, exact operation/action/resource coverage, broad authority and limits.
Configuration schema Home/page/widget/script files, policies, subscriptions, validation, persistence and reload.
Android access Runtime grants, special access, foreground requirements, roles and platform limits.
Public Android SDK Class/overload discovery, typed values, handles, callbacks and read-only execution.
MCP resources Short packaged guides and searchable manual sections for agents.

Schemas from the installed build are authoritative. A new APK can add commands that an older build does not expose. Unknown commands/fields and unsupported enum values are errors. Treat optional defaults as defined by each schema, rather than inventing arguments from a similar API.

Build an app step by step

  1. Follow the GPS todo tutorial for a complete five-file app whose background location event updates its UI state.
  2. Follow the scripting tutorial for a custom event flowing from an HTML button to Lua and back into a widget.
  3. Choose a bundled template, add an independent copy, then edit its complete source and state.
  4. For a remote client, create only the scopes needed, inspect remoteAccessInfo, discover visible tools and use their exact input schemas. Direct hidden-tool calls are checked too.
  5. Check the operation's own result, retained status and Activity/logs. A queued command, submitted intent or accepted SMS does not prove the external effect completed.

Phone API families

Family Detailed behavior and results
Home, semantic UI, configuration and events Automation control, HTML DOM, event scripts
Apps, files, APK installation, shell and jobs Apps, files/APKs, shell sessions, jobs
Contacts, calendar, SMS, calls, SIM and clipboard Native data and provider resources
Sensors, camera, audio, speech and location Hardware, camera, audio, speech, location
Bluetooth, Wi-Fi, NFC and USB Bluetooth, Wi-Fi, NFC, USB
Notifications, media, device settings and SDK Notifications, hardware, SDK
Safety, journeys, health and document capture Companion, journeys, coverage
Chat, search, operations and recovery Chat, search, operations, backups

Result contract

Ordinary success responses contain type: "result", matching requestId and an operation-specific result. Launcher responses also include revision; app-local native command paths can omit it. Ordinary failures contain type: "error", requestId, stable code, human-readable message and optional permission-recovery data. MCP exposes the canonical result as structuredContent and marks operation errors with isError. HTTP authentication failures can occur before an ordinary command response. WebSocket also carries independent event messages.

Use the operation's focused guide above for its result fields and terminal states. Read hasMore, cursor/history-gap and completion/cleanup fields where present. Camera availability, carrier delivery, external apps and Android permission screens are observed separately from command acceptance. Read-only hints describe operations; the trusted executor independently enforces read-only execution.

Authority and persistence

Remote scopes authorize commands and finite action/resource choices. They do not grant Android permissions. Code installation, shell, generic SDK calls, arbitrary intents and credential administration can delegate broad authority; selecting a narrow operation name does not sandbox the code or object it controls. Full definitions are in the token table.

Local HTML, Lua and JavaScript bindings use the owner authority already granted to Dikciz. A custom app is not a separately isolated Android package. Keep secrets out of shared state, screenshots and reusable app source. Use the existing protected provider/authentication storage for credentials. A token's scope cannot undo effects already submitted to Android.

Table of contents