Skip to main content

Developer Mode

Developer Mode lets you build a Shuuka app against the live platform — with real user data, real field values, and the full SDK — without uploading a bundle. Your local dev server's HTML is proxied by the Shuuka backend, the platform context is injected directly into the page, and the result is served inside a normal iframe. No cross-origin plumbing, no special handshake.

Prerequisites​

Developer Mode requires Developer access. Enable it in Settings > App preferences before the Dev Mode option appears in the dashboard.

  1. Open My Apps in the dashboard sidebar.
  2. Switch to the My Developed Apps tab.
  3. Click the Dev Mode button at the top right of the tab.

This opens the Developer Mode page where you manage your local dev project entries.

Add a Project​

Each entry has two fields:

FieldDescription
Project nameA label for your own reference. Can be left blank.
URLThe full root URL of your local dev server, including protocol.

Click + Add project to create a new entry. Fields save automatically 700 ms after you stop typing — no save button required. Projects are stored server-side and survive hard refreshes, browser clears, and device switches.

The URL field accepts any http:// or https:// address. Common values:

  • http://localhost:5173 — Vite default
  • http://localhost:3000 — Create React App / Next.js default
  • http://myapp.local — MAMP or custom virtual host
  • http://myapp.test — Laravel Valet
  • https://myapp.local — local HTTPS with self-signed cert (supported — SSL verification is bypassed by the backend)

How Context Is Delivered​

When the platform loads your admin page or profile template, it does not use an iframe bridge. Instead:

  1. The Shuuka backend fetches your dev server's HTML file server-side (SSL verification disabled for local certs).
  2. It injects a <script> block with window.__shuukaCtx and window.ShuukaApi into the <head>.
  3. It serves the resulting HTML directly — your app runs in a normal iframe with all platform context already available on first load.

Your app does not need to do anything special to receive the context. Just read it:

// Context is already set when your script runs — no handshake needed
const ctx = window.__shuukaCtx;

// Field values saved by the account owner
const title = ctx.fieldValues?.en?.campaign_title;

// Pre-built API helpers
window.ShuukaApi.public.entries.submit({ formId: 'main', inputValues: { name: 'Alice' } });
window.ShuukaApi.admin.storage.set('winner', { name: 'Alice' });

What window.__shuukaCtx Contains​

KeyDescription
publicIdProfile owner's public identifier
billboardAppIdID of this app instance on the billboard
billboardUserIdUser ID of the billboard owner
apiBaseUrlAPI root (e.g. https://api.shuuka.com/en)
accessTokenBearer token for admin API calls (admin pages only)
localeActive locale (e.g. "en")
fieldValuesSaved app instance settings, keyed by locale
suppressIframeShadowtrue — do not add a box-shadow on document.body; the wrapper card already applies the shadow
shkApiSame as window.ShuukaApi — attached for convenience

window.ShuukaApi (and window.shkApi)​

Both names point to the same pre-built API client. It is ready immediately:

// Public endpoints — no auth token required
ShuukaApi.public.entries.submit(payload)
ShuukaApi.public.storage.getValue('promo_code')
ShuukaApi.public.access.verify('SECRET123')

// Admin endpoints — uses the injected accessToken automatically
ShuukaApi.admin.entries.list({ formId: 'main', perPage: 50 })
ShuukaApi.admin.entries.randomSelect({ formId: 'main' })
ShuukaApi.admin.storage.set('key', value)
ShuukaApi.admin.storage.get('key')
ShuukaApi.admin.storage.delete('key')
ShuukaApi.admin.access.set({ code: 'SECRET123' })

Template Placeholders​

If your template.html uses {{field_key}} placeholders (e.g. {{campaign_title}}), the Shuuka backend replaces them with the saved field values before serving the page. Nothing extra is needed — just use the tokens in your template and they will be filled in automatically.

Dev App Files Served​

Page typeFile fetched from your dev server
Profile / billboard{dev_url}/template.html
Admin page{dev_url}/admin/{page_key}.html

Your dev server must be running and reachable from the machine running the Shuuka API. The backend retries with a 5-second timeout; if the server is down, a 503 Dev server unreachable error is returned.

Visibility​

Dev apps are only visible to you — the authenticated account owner. Non-logged-in visitors and other logged-in users do not see dev apps on your profile page.

Publish Your App​

When your app is ready for testing as a proper Shuuka package:

  1. Build your production bundle (npm run build or equivalent).
  2. Add manifest.json, required images, and schema files to the output folder.
  3. ZIP the built package.
  4. Open My Apps → Create New App and upload the ZIP.

See App Quickstart for the full build and upload checklist.

Notes and Limits​

  • Dev Mode entries are stored per user account, not per device or browser.
  • You can register multiple projects simultaneously — useful when building several apps at once.
  • Removing a project entry does not affect any uploaded app.
  • Dev apps are never publicly visible — they require an authenticated owner session to render.
  • Your local server must be running when the platform fetches your files. The backend does not cache dev content.
  • Self-signed SSL certificates on local HTTPS servers are accepted — the backend bypasses certificate verification for dev URLs.