> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Topic-based Content Discovery

> Help users discover relevant community conversations through configured topics, using the SDK or the Discovery Widget.

Topic-based content discovery helps brands and community teams bring relevant conversations to the pages people already visit. Instead of relying on users to search for a community, surface posts about a topic on your homepage, category pages, or other browsing surfaces. Post previews help people understand what your community offers and decide which conversations to explore.

Your team configures a topic in the social.plus Console. The SDK uses its topic ID to fetch an ordered selection of community posts, called a **pool**. Build your own presentation with these posts, or use the UIKit's [Discovery Widget](/uikit/components/social/discovery-widget) for a ready-made carousel.

<Info>
  The SDK supports topic-based content discovery on **TypeScript**, **iOS**, and **Android**. Flutter and React Native are not supported.
</Info>

## How recommendations are selected

Recommendations use three main signals:

* **Topic relevance:** how closely a post matches the configured topic. This is the main signal.
* **Engagement:** activity on a post, such as reactions and comments, helps identify relevant conversations people are participating in.
* **Freshness:** newer posts help keep the selection timely.

Selection is based on the configured topic rather than a reader's personal interests or engagement history. Topic configuration and eligibility rules determine which posts can appear. Viewer-specific restrictions, such as blocked authors, can further affect the returned selection.

The SDK returns posts in recommendation order. Preserve that order when presenting the recommended selection.

## Before you start

Configure a topic in the social.plus Console and obtain its topic ID. Initialize the SDK and establish a [user session](/social-plus-sdk/getting-started/authentication) or a [visitor session](/social-plus-sdk/getting-started/visitor-mode) before fetching posts.

Topic configuration is managed in the Console. This page covers reading its recommendations and reporting interactions from your app.

## Parameters

| Parameter | Type     | Required | Platforms                | Description                                                                       |
| --------- | -------- | -------- | ------------------------ | --------------------------------------------------------------------------------- |
| `topicId` | `string` | Yes      | TypeScript, iOS, Android | The topic ID configured in the Console.                                           |
| `limit`   | integer  | No       | TypeScript, iOS, Android | Maximum number of posts to return, from 1 to 100. Omit to use the server default. |

## Fetch recommended posts

`getPool` returns the topic and its ordered posts in a single request. It is not a live collection and does not support pagination. Call it again when your app needs a new selection.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { CuratedContentRepository } from '@amityco/ts-sdk';

  const pool = await CuratedContentRepository.getPool('your-topic-id', 10);
  const topicName = pool.topic.topicName;
  const posts = pool.posts;
  ```

  ```swift iOS theme={null}
  let repository = AmityCuratedContentRepository()
  let pool = try await repository.getPool(topicId: "your-topic-id", limit: 10)

  let topicName = pool.topic.topicName
  let posts = pool.posts
  ```

  ```kotlin Android theme={null}
  val repository = AmityCoreClient.newCuratedContentRepository()

  repository.getPool(topicId = "your-topic-id", limit = 10)
      .subscribeOn(Schedulers.io())
      .observeOn(AndroidSchedulers.mainThread())
      .subscribe({ pool ->
          val topicName = pool.topic.topicName
          val posts = pool.posts
      }, { error ->
          // Handle the failed request in your app.
      })
  ```
</CodeGroup>

The returned posts are standard post objects that you can render in your own UI. Results may contain fewer posts than requested, including an empty list. An empty list is a successful response; omit the discovery surface when there is no content to display.

## Report interactions

When building your own discovery surface, use the topic's analytics handle to measure what readers see and open. Report views when the surface or card becomes visible, rather than when an off-screen element is mounted.

| Method                     | Report when                            |
| -------------------------- | -------------------------------------- |
| `markAsViewed()`           | The discovery surface becomes visible. |
| `markPostAsViewed(postId)` | A post card becomes visible.           |
| `markPostClick(postId)`    | The reader selects a post card.        |

<CodeGroup>
  ```typescript TypeScript theme={null}
  pool.topic.analytics.markAsViewed();
  pool.topic.analytics.markPostAsViewed(post.postId);
  pool.topic.analytics.markPostClick(post.postId);
  ```

  ```swift iOS theme={null}
  pool.topic.analytics.markAsViewed()
  pool.topic.analytics.markPostAsViewed(postId: post.postId)
  pool.topic.analytics.markPostClick(postId: post.postId)
  ```

  ```kotlin Android theme={null}
  val topic = pool.topic
  topic.analytics().markAsViewed()
  topic.analytics().markPostAsViewed(post.getPostId())
  topic.analytics().markPostClick(post.getPostId())
  ```
</CodeGroup>

Report the surface impression and each post impression once per page load. Report a click when the reader selects a card, and let navigation proceed without waiting for analytics.

The Discovery Widget reports these interactions automatically, so you do not need to report them again for that component.

## Related topics

<CardGroup cols={2}>
  <Card title="Discovery Widget" icon="window-maximize" href="/uikit/components/social/discovery-widget">
    Embed a ready-made carousel of topic-based recommendations.
  </Card>

  <Card title="Visitor mode" icon="user" href="/social-plus-sdk/getting-started/visitor-mode">
    Establish a session for readers who have not signed in.
  </Card>
</CardGroup>