Discovery Widget

Discovery Widget brings topic-based content discovery to the pages people already visit. It helps brands and community teams surface relevant conversations on homepages, category pages, and other browsing surfaces, so users can discover the value of a community without first searching for it. Your team configures a topic in the social.plus Console, then your app uses that topic’s ID to display recommended community posts. Post previews and reaction and comment counts help readers decide what to explore. Your app controls where a selected post opens, providing a route into the conversation and community.

Discovery Widget is supported on iOS, Android, and Web. Flutter and React Native are not supported.

How it works

The widget fetches an ordered selection of posts for its configured topic and displays them in a read-only carousel. Readers can browse previews and select a card. Reacting, commenting, voting, and media playback happen outside the widget, at the destination your app provides. Recommendations use topic relevance as the main signal, with post engagement and freshness helping order relevant conversations. They are based on the topic rather than the reader’s personal interests. Eligibility rules and viewer-specific restrictions, such as blocked authors, can affect which posts appear. See Topic-based content discovery for the SDK integration.

Before you start

Configure a topic in the social.plus Console and obtain its topic ID. Set up your app’s UIKit integration and establish a user session or a visitor session before displaying the widget. Choose where a card should open in your app, such as a post detail page or your hosted community. Pass a topic ID and handle card selection with onCardClick.

import { AmityDiscoveryWidgetComponent } from '@amityco/ui-kit';

<AmityDiscoveryWidgetComponent
  topicId="your-topic-id"
  onCardClick={(topicId, post) => {
    // Navigate to the selected post in your app.
  }}
/>

AmityDiscoveryWidgetComponent(
    topicId: "your-topic-id",
    onCardClick: { topicId, post in
        // Navigate to the selected post in your app.
    }
)

AmityDiscoveryWidgetComponent(
    topicId = "your-topic-id",
    onCardClick = { topicId, post ->
        // Navigate to the selected post in your app.
    },
)

Parameters

Parameter	Type	Default	Platforms	Description
`topicId`	string	Required	iOS, Android, Web	The topic ID configured in the Console.
`showHeader`	boolean	`true`	iOS, Android, Web	Show the topic heading and navigation controls where supported.
`minVisibilityThreshold`	number	`3`	iOS, Android, Web	Minimum number of renderable posts needed to show the widget. Values below 1 are clamped to 1.
`onCardClick`	callback	None	iOS, Android, Web	Receives the topic ID and selected post. Overrides the behavior class for this instance.
`pageId`	`PageId?` / string	`nil` / `'*'`	iOS, Web	Page identifier for customization scoping.
`pageScope`	`AmityComposePageScope?`	`null`	Android	Compose page scope for customization.
`modifier`	`Modifier`	`Modifier`	Android	Standard Compose modifier.

Display behavior

The widget adapts to compact and expanded layouts. Readers swipe through cards; Web and Android also provide navigation arrows in the expanded layout. The widget renders nothing when the request fails or the number of renderable posts is below minVisibilityThreshold. It shows no heading, empty state, or error message in these cases. Avoid a separate decorative container that would remain visible when the widget hides.

Host container

The widget sizes itself from its content and does not set a height on its parent. Place it in a container that fits it:

Use a wrap-content container, or give the container a minimum height that fits the widget. A shorter container clips the cards, starting with the reaction and comment counts at the bottom.
Avoid a container with zero or undefined height. The widget still loads posts and reports its impression, but readers can’t see it.
Place the widget in a vertically scrolling or non-scrolling container. A horizontally scrolling parent is not supported, because the widget’s own horizontal scrolling competes with it for swipes.

Supported content

Post type	Display
Text	Text preview
Image	First attachment preview
Video or clip	First attachment preview with a play indicator
Poll	Read-only results preview
Livestream or room	Not rendered

Unsupported posts do not count toward the visibility threshold. For example, a response with four posts, including two unsupported posts, has only two renderable posts and remains hidden at the default threshold. Each card shows author and community information, a content preview, and reaction and comment counts. A card is one tap target: mentions, hashtags, links, and preview labels do not have separate actions. Media does not play inside the card, and readers cannot vote in a poll preview.

Handle card selection

Use onCardClick for navigation specific to one placement. For app-wide navigation, override the platform’s behavior class instead:

Platform	Behavior
Web	`AmityDiscoveryWidgetComponentBehavior.goToDestination({ topicId, post })`
Android	`AmityDiscoveryWidgetComponentBehavior.goToDestination(context, topicId, post)`
iOS	`AmityDiscoveryWidgetComponentBehavior.goToDestination(context)`

When onCardClick is provided, the behavior class is not called for that instance.

No platform has a default destination. If you provide neither onCardClick nor a behavior override, selecting a card does nothing. Provide a navigation handler so a card opens the intended content.

Analytics

The widget automatically reports its impression, visible post-card impressions, and card clicks. It reports each impression once per page load and reports clicks when readers select cards. You do not need to call the SDK analytics methods again for the widget. If you build a custom discovery surface with the SDK, report these interactions yourself. See Report interactions.

Customization

Use component parameters to control the topic, header, visibility threshold, and card navigation. The widget uses your app’s UIKit theme. See UIKit customization for general theming guidance.

Build your own discovery surface

Use the SDK’s topic-based content discovery APIs when you need a presentation other than the ready-made carousel. They return standard post objects and topic analytics handles so your app can render recommendations and measure interactions.

Powered by

Getting Started

Customization

Components

Release Notes

Support

How it works

Before you start

Embed the widget

Parameters

Display behavior

Host container

Supported content

Handle card selection

Analytics

Customization

Build your own discovery surface

​How it works

​Before you start

​Embed the widget

​Parameters

​Display behavior

​Host container

​Supported content

​Handle card selection

​Analytics

​Customization

​Build your own discovery surface

How it works

Before you start

Embed the widget

Parameters

Display behavior

Host container

Supported content

Handle card selection

Analytics

Customization

Build your own discovery surface