Configuring Your Widget

Before you start sending player data, configure how your widget looks in the Developer Portal. This is where you choose layouts for each surface, set up which fields to display, and preview the result.

Open the Developer Portal and select your application to create your widget config which can be found under Games > Widget in the left sidebar.

The widget editor uses a hierarchy of concepts:

• Surface: a location where game stats are rendered (e.g. the top or bottom of the profile widget, the widget preview in the mini profile popout)
• Layout: the visual template for a surface; each surface has one active layout
• Component: a logical group of fields within a layout (e.g. the six stat slots in the stats grid)
• Field: a single displayed value within a component (e.g. a stat's value, label, or icon)

The editor is split into panels:

• Left sidebar: the Design tab selects the layout for the active surface, and the Content tab configures the chosen layout's components. The Content tab appears once you've selected a layout.
• Right sidebar: shows the fields for the component selected in the Content tab.
• Bottom panel: the Validation tab shows any components that need to be completed, and the Sample Data tab provides mock player data to populate the preview.

Use the dropdown at the top of the left sidebar to switch between surfaces.

A widget config has five surfaces, each rendered in a different place in the Discord client:

Select each surface from the dropdown and choose a layout in the Design tab. Each layout has a different arrangement of components and fields, so choose the one that best fits the stats you want to show and how you want to show them.

Switch to the Content tab and click a component in the list to open its fields in the right sidebar.

Text-based fields have a Presentation Type that controls how the value is displayed. Each field offers the options that make sense for it (for example, a stat value offers Duration but a subtitle doesn't):

The presentation type you pick determines which value types are available for that field:

• Number and Duration accept User Data only
• Text accepts User Data or Custom String

Image fields don't have a presentation type; whether a field displays an image is determined by the layout. An image field accepts a Value Type of User Data (a media field, such as rank_image) or Application Asset.

Each field has a Value Type that determines where its content comes from:

Application Assets are static images you upload to the portal. Manage them from the Assets page in the portal sidebar, or use the inline asset picker when configuring an Application Asset field. Check out our comprehensive Image Asset Guidelines that covers best practices for images in the game stats widget with visual examples of how they show up.

Asset keys are validated when the asset is created: max 50 characters, using letters, numbers, underscores, and hyphens.

Common use cases:

• A branded hero image to use as a fallback when a player has no character data
• Static game logo or cover art in the widget top
• A default rank badge for unranked players
• A static image for the Add Widget Preview surface to show in the Add Profile Widget modal

Some fields are optional and have a toggle switch like Description or Max Value. Toggle it on to configure that field or leave it off to omit it from the widget.

User Data fields support a Fallback toggle. When enabled, configure a fallback value that renders when the player's data is missing. The fallback can be a Custom String or an Application Asset.

Examples:

• Show rank_name from the player's data. Fall back to the Custom String "Unranked" if it's missing.
• Show the player's favorite character image. Fall back to an Application Asset placeholder of a default character if no character has been chosen.

The Sample Data tab in the bottom panel lets you provide mock player data to preview your widget without sending real API data.

1. Click Add Field and enter a key matching the data field name used in a User Data field config.
2. Select the field type (string, number, or media) and enter a sample value.
3. The preview updates to show the value wherever that field is referenced.

Unpublished widgets can be viewed and added by members of your developer team.

Members of your developer team can test your widget in Discord while it's still a draft.

1. Enable Developer Mode in Discord settings (Settings > Advanced > Developer Mode).
2. Choose a layout for Widget Top, Widget Bottom, and Add Widget Preview (full field configuration is not required).
3. In Discord, open your own full profile and click Add Widget to open the Add Profile Widget modal.
4. Under Game Widgets, find your game's widget and click Add to profile.

Publishing your Game Stats Widget will make the widget discoverable and allows players to add it to their profile after account linking with your game's Discord app.

In order to publish your widget, all three of these surfaces must have a layout chosen and all required fields configured:

• Widget Top
• Widget Bottom
• Add Widget Preview

Once complete, click Publish in the top-right header to make it available to your players.

Once your widget is configured, move on to Sending Game Data to start populating it with live player stats.