Dynamic Configuration

Dynamic Config from Studio

The SDK can receive visual and behavioral configuration from JOIN Studio.

If no manual configuration is provided in the app, the SDK applies the Studio configuration when available.
If a Studio setting is missing, the SDK falls back to its default value.
If a manual configuration is provided in the app, it always takes priority over the Studio configuration.

Configuration priority

Manual configuration in app
        ↓
Studio configuration
        ↓
SDK default value

If a value is manually configured in the app, it always overrides the Studio value.
If no manual value is provided, the SDK uses the Studio value when available.
If no Studio value is available, the SDK uses its default value.

Studio settings mapping

Studio setting	Applies to	Visual effect	Default	Manual override in app
Item spacing	Bubbles, Cards	Space between items	Bubbles: 12, Cards: 8	Bubbles: `JoinStoriesBubbleConfigurations.thumbViewSpacing`; Cards (grid): `TriggerCardConfigurationValues.spacing`; Cards (list): `TriggerListConfigurationValues.spacing`
Show play icon	Bubbles, Cards	Show/hide play glyph overlay	On	Bubbles: `JoinStoriesBubbleConfigurations.showPlayButton`; Cards (grid/list): `showPlayButton`
Play icon style	Bubbles	Choose icon style (e.g., minimalist/outline/fill)	Minimalist	`JoinStoriesBubbleConfigurations.playIcon`
Show labels	Bubbles, Cards	Show/hide labels under items	On	Bubbles: `JoinStoriesBubbleConfigurations.showLabel`; Cards (grid/list): `showLabel`
Card corner radius	Cards	Card rounding	8	`TriggerCardConfigurationValues.cardRadius` (grid); `TriggerListConfigurationValues.cardRadius` (list)
Player corner radius	Player	Player view rounding	0	`JoinStoriesPlayerConfigurations.playerCornerRadius`
Show cover and title (player)	Player	Show/hide cover/title overlay	On	Not exposed for manual override
Read / unread effect	Bubbles, Cards	Enables read state behavior for stories	Off	Controlled by the SDK read state behavior
Reorder read stories	Bubbles, Cards	Displays unread stories first	Off	`JoinStoriesBubbleConfigurations.reorderedReadStories, CardConfiguration.reorderedReadStories`
Viewed indicator	Bubbles	Displays a viewed indicator on read bubbles	Off	`JoinStoriesBubbleConfigurations.storyViewedIndicatorColor`
Loader ring colors (brand)	Bubbles	Gradient around bubble	JOIN default gradient	`JoinStoriesBubbleConfigurations.loaderColors`

Note: Widget type (“shape”) is always selected in code (manual integration), not from Studio.

Read / unread behavior

Reorder read stories and Viewed indicator are only applied when Read / unread effect is enabled in Studio.

If Read / unread effect is disabled, these settings are ignored.

To let Studio control these behaviors, enable Read / unread effect in Studio and avoid forcing the related values manually in the app.

JoinStoriesBubbleConfigurations(
    reorderedReadStories: nil,
    storyViewedIndicatorColor: nil
)

If the app explicitly overrides a value, the manual configuration takes priority:

let configuration = JoinStoriesBubbleConfigurations(
    storyViewedIndicatorColor: .gray
)

In this case, Studio cannot enable Reorder read stories dynamically.

For the viewed indicator, setting a manual color also overrides the Studio behavior:

let configuration = JoinStoriesBubbleConfigurations(
    storyViewedIndicatorColor: .gray
)

To let Studio fully control the viewed indicator, keep the value unset:

let configuration = JoinStoriesBubbleConfigurations(
    storyViewedIndicatorColor: nil
)