App Data, Storage, and Access

Shuuka gives apps a generic storage and entry system per installed app instance.

Storage Visibility

Visibility	Readable by	Use for
Private	App owner only	internal state, sensitive workflow data
Public	Anyone	winner nickname, public status, public draw history

Never store PII in public storage.

Recommended Storage Keys

Key	Typical value
winner	current winner object
draws	full draw history
entry_count	public-safe participant count
campaign_status	active, closed, or custom app state
settings	app-specific structured configuration

Recommended Builder Pattern

Use the package schemas for structure, then use shkApi or SDK helpers for runtime reads and writes.

Need	Start with
App Global Settings	settings.json
secure App Global Settings	settings-global.json
App Instance Settings	groups and placeholders in manifest.json
visitor submissions	inputs.json
runtime reads and writes	SDK helpers or shkApi

Entry Submission Contract

Typical payload:

{
  "form_id": "giveaway",
  "input_values": { "email": "[email protected]" },
  "display_value": "janed",
  "metadata": { "consent": true }
}

display_value vs input_values

Field	Encrypted at rest	Public-safe
input_values.email	Yes	No
input_values.full_name	Yes	No
display_value	No	Yes

Use display_value only for data the participant intentionally makes public.

Access Code Flow

Use access codes when the campaign is invite-only.

1. Verify the code with shkApi.public.access.verify(code).
2. Keep the returned token in memory only.
3. Pass it as accessToken into shkApi.public.entries.submit(...).

Do not store the token in localStorage or sessionStorage.

Deduplication Model

Mode	Behavior
single_entry	one submission per participant
daily_entries	one submission per participant per day

Best Practice

Keep app state small and intentional:

• store only what the workflow needs
• keep public storage strictly public-safe
• treat shkApi as the only builder-facing storage/entry contract