App Instance Settings

App Instance Settings is the Shuuka term for the per-app sidebar settings of one installed app instance.

Use this term consistently. Do not call this surface the settings page or global settings page.

What It Is

App Instance Settings let the owner configure one specific app card on the profile.

Typical examples:

• app title
• subtitle
• button label
• button color
• card layout
• image or cover media

If the owner installs the same app twice, each installed card can have different App Instance Settings.

What Drives It

For simple and smart HTML apps, App Instance Settings are defined in manifest.json with:

• groups
• placeholders

Shuuka renders those fields in the app sidebar for that installed app instance.

Minimal Example

{
  "groups": [
    { "id": "content", "title": "Content" },
    {
      "id": "design",
      "title": "Design",
      "sections": [
        { "id": "colors", "title": "Colors" }
      ]
    }
  ],
  "placeholders": [
    {
      "key": "title",
      "type": "text",
      "required": true,
      "default": "My Card Title",
      "group": "content"
    },
    {
      "key": "button_label",
      "type": "text",
      "default": "Open",
      "group": "content"
    },
    {
      "key": "button_color",
      "type": "color",
      "default": "#1d4ed8",
      "group": "design",
      "section": "colors"
    }
  ]
}

How Values Reach the App

For simple and smart HTML apps, Shuuka resolves App Instance Settings into the app runtime.

You usually read them in two ways:

1. template tokens such as {{title}} or {{button_color}}
2. runtime values inside window.__shuukaCtx.fieldValues

Example in a template:

<div class="my-app" data-title="{{title}}">
  <h2>{{title}}</h2>
  <button style="background: {{button_color}}">{{button_label}}</button>
</div>

Example from runtime context:

var ctx = window.__shuukaCtx || {};
var fieldValues = ctx.fieldValues || {};
var title = fieldValues.title;

Common Placeholder Types

Type	Good for
text | string	title, subtitle, button label
textarea	copy blocks, descriptions
select	layout mode, display variant
color	button color, text color, accent color
number	spacing, size, count
image	cover image or media
url	external link fields
switch | boolean	enable or disable one behavior
list	repeater fields that allow adding multiple items (e.g. testimonials, links)
user_link	allows the user to select one of their existing profile social links

Advanced Field Types

List (Repeater) fields

For settings where you want the user to click "Add more" to add multiple items, such as a slider of testimonials or a list of custom links, use the list type with a defined sub_fields array.

Example:

{
  "key": "testimonials",
  "type": "list",
  "default": [
    {
      "name": "Jane",
      "text": "Great product!"
    }
  ],
  "sub_fields": [
    {
      "key": "name",
      "type": "string"
    },
    {
      "key": "text",
      "type": "textarea"
    }
  ]
}

In your simple app HTML, Shuuka provides an {{#each}} block helper to iterate over list fields:

<div class="slider">
  {{#each testimonials}}
    <div class="card">
      <h3>{{name}}</h3>
      <p>{{text}}</p>
    </div>
  {{/each}}
</div>

User Link fields

The user_link type lets a user select from their verified social links. This creates multiple automatic placeholders per field. For a field keyed "my_link", you can access:

• {{my_link_url}}: The tracking-wrap URL to the chosen link.
• {{my_link_title}}: The title of the chosen link.
• {{my_link_icon}}: The system URL to the appropriate platform icon.

Default Values

Always provide a sensible default for your placeholders so your app looks great immediately out-of-the-box. The frontend SDK and backend renderer will use the default value if the user hasn't touched the setting yet.

For text, colors, and numbers, simply provide the value: "default": "#ff0000" or "default": 12

For booleans, use true/false: "default": true

For list types, optionally provide a predefined initial array covering the sub-fields: "default": [{"name": "Default item"}]

Conditional Instance Settings

Use show_if when one App Instance Settings field should only appear after another field is enabled.

Example:

{
  "key": "gradient_color",
  "type": "color",
  "group": "design",
  "show_if": {
    "field": "background_mode",
    "value": "gradient"
  }
}

Runtime Context (Metadata)

Beyond standard instance setting options like texts and colors, the Shuuka platform automatically injects environment metadata and API routes so your app is fully aware of where it lives.

Through either window.__shuukaCtx or window.shuukaConfig in an app, or standard {{placeholders}}, you have access to:

App Context Data

• Public Profile ID (window.__shuukaCtx.publicId): The unique ID of the profile hosting your app.
• Locale (window.__shuukaCtx.locale): The UI language (e.g. en, de) currently selected by the viewer. Use this to change UI dates or custom external links.
• Billboard App ID (window.__shuukaCtx.billboardAppId): The unique instance ID of this specific app insertion.
• App Data Object (window.__shuukaCtx.appData): Contains id, name, version, and unique_key matching your manifest.
• Shared Profile Object (window.__shuukaCtx.profile): Reusable profile identity payload including localized description, display_name, avatar_url, category, verification status, and plan fields. Use this instead of asking the owner to re-enter profile identity data in app settings.
• Social Links (window.__shuukaCtx.links): An array of the user's active social profile models.
• API Base URL (window.shuukaConfig.apiBaseUrl): Prepared API endpoint pre-prefixed with the locale (e.g. https://api.shuuka.local/en).

Theme Context Data

If you need to strictly match your app colors to the parent theme dynamically (rather than just using CSS classes), you can read the active Profile Theme configuration:

• Color Scheme (window.__shuukaCtx.themeMode): Either dark or light. Shuuka also auto-injects an <html class="dark"> wrapper inside your iframe when appropriate.
• Full Theme Object (window.shuukaConfig.theme): In custom Theme SDK modes, this provides access to config.background.color, config.layout.structure, config.iframe.border_radius, and other parent environment styling choices.

For native apps, the same payload is passed as profile in the mounted component props. The source is the same shared contract; only the delivery mechanism differs.

What Not To Put Here

Do not use App Instance Settings for:

• API keys
• shared app-wide integration settings
• secure secrets
• exports, moderation, or analytics workflows

Use App Global Settings for shared configuration and App Admin Pages for custom owner tools.

Builder Rule

If the owner should be able to configure one card differently from another card of the same app, that belongs in App Instance Settings.