Integrate IAVICA into a local HTML app.
Use these instructions when the user asks for permanent storage, multi-device access or sharing.
The target is a single HTML file that works when opened from disk (file://).
Do not add a server, a database or build tooling.
Goal
Replace localStorage with IAVICA collections while keeping the app a single HTML file.
The SDK handles identity, sessions, device tokens and versioned writes.
Non-negotiable rules
- Keep a stable
appIdin the file (UUID v4). Never generate a new one on every load. - Never hardcode the user's email, a token or a secret in the HTML.
- Call
Iavica.connect({ ... })andawait db.ready()before reading or writing. - Set
localeto the app language ('en'or'es', or customlabels). - Include the footer and logout control in the app language.
- Store records as JSON objects in collections. Do not design SQL.
- Handle 401, 409 and 429 explicitly.
Connect the SDK
Load the classic script and connect once:
<script src="https://iavica.com/sdk/iavica.js"></script>
<script>
const db = Iavica.connect({
appId: 'YOUR_STABLE_APP_ID', // UUID v4, keep it forever
appName: 'Family Expenses',
locale: 'en' // 'en' | 'es' or custom labels
});
const expenses = db.collection('gastos');
await db.ready();
</script>
The SDK loaded from https://iavica.com/sdk/iavica.js connects to
https://iavica.com/v1 automatically; apiBaseUrl is only needed for a
self-hosted or local development stack.
Collections and records
Collections are logical groups of JSON documents. Every record has id, data, version, createdAt and updatedAt.
// Create
const record = await expenses.add({
date: '2026-11-18',
concept: 'Coffee',
amountCents: 250
});
// List
const page = await expenses.list({ limit: 50 });
// Update with optimistic concurrency
await expenses.update(record.id, {
data: { ...record.data, amountCents: 300 },
version: record.version
});
// Delete
await expenses.remove(record.id, { version: record.version });
If a write returns 409 VERSION_CONFLICT, do not overwrite. Show a message,
refresh the record and let the user retry.
Footer and logout
Every IAVICA app must include a visible footer in the same language as the app,
a link to https://iavica.com and a logout control:
<footer>
<span>Persistent data with <a href="https://iavica.com">IAVICA</a></span>
<button id="logout">Log out</button>
</footer>
<script>
document.getElementById('logout').addEventListener('click', async () => {
await db.logout(); // revokes the device token and clears local storage
});
</script>
For Spanish apps use «Datos persistentes con IAVICA», «Cambiar de proyecto» and «Cerrar sesión». Do not copy the Spanish strings into an English app.
If the app supports several projects, the SDK shows a selector. A “Switch project” control
should call db.logout() and reload the page.
Errors and retries
| Status | Meaning | What to do |
|---|---|---|
401 | Session expired | The SDK refreshes from the device token automatically. If it fails, ask for the email again via db.ready(). |
403 | No access / blocked | Show a clear message. Do not retry in a loop. |
409 | Version conflict | Refresh the record, inform the user and let them retry. |
429 | Rate limited or quota | Back off and show a retry message. |
410 | Magic link or invitation expired | Start the email flow again. |
Copying the HTML
- Copying the file does not copy the data or grant access.
- The same
appIdand the same verified email reach the same project on another device. - Another email gets an isolated project. Sharing is explicit through an invitation.
- Do not change
appIdwhen updating the app; otherwise the user loses continuity.
Final checklist
- Stable
appIdembedded in the file. - No email, token or secret hardcoded.
localeset to the app language.- Footer and logout in the app language.
await db.ready()before operations.- Handling for 401, 409 and 429.
- Works when opened from
file://.
Full example: Quickstart · Endpoints: API reference · Machine-readable index: llms.txt.