# Quick Start

Stream lets you build activity feeds at scale. The largest apps using Stream have over 100 million users.
Stream Activity Feeds scales effectively while giving you more flexibility over the content shown in your feed.

>
> **Tip:** Stream Feeds has two halves. Feed groups, ranking, permissions and push setup are configured on your backend with a [server-side SDK](https://getstream.io/activity-feeds/docs/node/), authenticated with your API secret. The code you ship to your users is a [client SDK](https://getstream.io/activity-feeds/docs/javascript/), and it connects with a token signed on that backend. Whichever half you are here for, this sidebar carries an overview of the other.
>

## Start here

- [Activities](https://getstream.io/activity-feeds/docs/flutter/activities/): The core content units in Stream Feeds: posts, photos, videos, polls and any custom type you define.
- [Feeds](https://getstream.io/activity-feeds/docs/flutter/feeds/): Collections of activities: personal, timeline, notification or custom feeds for your use case.
- [Authentication and tokens](https://getstream.io/docs/platform/authentication/): Your backend signs the tokens users connect with, using your API secret.

## Getting started

```dart label="Dart"
// Import the package
import 'package:stream_feeds/stream_feeds.dart';

// Initialize the client
final client = StreamFeedsClient(
  apiKey: '<your_api_key>',
  user: const User(id: 'john'),
  tokenProvider: TokenProvider.static(UserToken('<user_token>')),
);
await client.connect();

// Create a feed (or get its data if exists)
final feed = client.feed(group: 'user', id: 'john');
final result = await feed.getOrCreate();

// Add activity
final activity = await feed.addActivity(
  request: const FeedAddActivityRequest(
    type: 'post',
    text: 'Hello, Stream Feeds!',
  ),
);
```

## Key concepts

### Activities

[Activities](https://getstream.io/activity-feeds/docs/flutter/activities/) are the core content units in Stream Feeds. They can represent posts, photos, videos, polls, and any custom content type you define.

### Feeds

[Feeds](https://getstream.io/activity-feeds/docs/flutter/feeds/) are collections of activities. They can be personal feeds, timeline feeds, [notification feeds](https://getstream.io/activity-feeds/docs/flutter/notification-feeds/), or custom feeds for your specific use case.

### Real-time updates

Stream Feeds provides [real-time updates](https://getstream.io/activity-feeds/docs/flutter/events/) through WebSocket connections, ensuring your app stays synchronized with the latest content.

### Social features

Built-in support for [reactions](https://getstream.io/activity-feeds/docs/flutter/reactions/), [comments](https://getstream.io/activity-feeds/docs/flutter/comments/), [bookmarks](https://getstream.io/activity-feeds/docs/flutter/bookmarks/), and [polls](https://getstream.io/activity-feeds/docs/flutter/polls/) makes it easy to build engaging social experiences.

## Server-side vs client-side

Most API calls can be made client-side. Client-side API calls use the permission system. Server-side API calls have full access.

```mermaid
flowchart LR
  subgraph app[Your app]
    client[Client SDK]
  end
  subgraph backend[Your backend]
    server[Server-side SDK]
  end
  client <--> api[Stream API]
  server --> api
  server -. user token .-> client
```

Most apps will default to making API calls client-side. Engineers will often use server-side to do the following tasks:

- Updating feed groups or feed views for ranking and aggregation
- Syncing users
- Returning tokens for authenticating users
- Writing to feeds that do not belong to the current user (since the user does not have access client side to do this)

## Common use cases

### Social media feed

```dart label="Dart"
// Create a timeline feed
final timeline = client.feed(group: 'timeline', id: 'john');
await timeline.getOrCreate();

// Add a reaction to activity
await timeline.addActivityReaction(
  activityId: 'activity_123',
  request: const AddReactionRequest(type: 'like'),
);

// Add a comment to activity
await timeline.addComment(
  request: const ActivityAddCommentRequest(
    comment: 'Great post!',
    activityId: 'activity_123',
  ),
);

// Add a reaction to comment
final activity = client.activity(
  activityId: 'activity_123',
  fid: const FeedId(group: 'timeline', id: 'john'),
);

await activity.addCommentReaction(
  commentId: 'commentId',
  request: const AddCommentReactionRequest(type: 'like'),
);
```

### Notification feed

```dart label="Dart"
// Create a notification feed
final notifications = client.feed(group: 'notification', id: 'john');
await notifications.getOrCreate();

// Mark notifications as read
await notifications.markActivity(
  request: const MarkActivityRequest(markAllRead: true),
);
```

### Polls

```dart label="Dart"
// Create a poll
const feedId = FeedId(group: 'timeline', id: 'john');
final feed = client.feedFromId(feedId);
final result = await feed.createPoll(
  request: const CreatePollRequest(
    name: "What's your favorite color?",
    options: [
      PollOptionInput(text: 'Red'),
      PollOptionInput(text: 'Blue'),
      PollOptionInput(text: 'Green'),
    ],
  ),
  activityType: 'poll',
);

// Vote on a poll
final activityData = result.getOrThrow();
final activity = client.activity(activityId: activityData.id, fid: feedId);
await activity.castPollVote(
  const CastPollVoteRequest(vote: VoteData(optionId: 'option_456')),
);
```

## Advanced features

### Custom activity types

Create custom activity types to represent your app's specific content:

```dart label="Dart"
final workoutActivity = await feed.addActivity(
  request: const FeedAddActivityRequest(
    text: 'Just finished my run',
    custom: {'distance': 5.2, 'duration': 1800, 'calories': 450},
    type: 'workout',
  ),
);
```

### Real-time updates with the state layer

Only for client-side SDKs

```dart label="Dart"
import 'package:flutter/widgets.dart';
import 'package:flutter_state_notifier/flutter_state_notifier.dart';
import 'package:stream_feeds/stream_feeds.dart';

class FeedView extends StatefulWidget {
  const FeedView({super.key, required this.feed});
  final Feed feed;

  @override
  State<FeedView> createState() => _FeedViewState();
}

class _FeedViewState extends State<FeedView> {
  @override
  void initState() {
    super.initState();
    widget.feed.getOrCreate();
  }

  @override
  void dispose() {
    widget.feed.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return StateNotifierBuilder(
      stateNotifier: widget.feed.notifier,
      builder: (BuildContext context, FeedState state, Widget? child) {
        return Text(state.feed?.name ?? '');
      },
    );
  }
}
```

## What's next

- [Follow and unfollow](https://getstream.io/activity-feeds/docs/flutter/follows/): Connect feeds with follow relationships to build timeline experiences.
- [Notification feeds](https://getstream.io/activity-feeds/docs/flutter/notification-feeds/): Create notification feeds and mark activities as read.
- [Permissions and roles](https://getstream.io/docs/platform/permissions/): The subject, resource and action model, built-in and custom roles.

## FAQ

**Which feed groups are built in?**

`user`, `timeline`, `foryou`, `notification`, `story` and `stories`. The [feeds page](https://getstream.io/activity-feeds/docs/flutter/feeds/#built-in-feed-groups) describes each.

**Can I rank a feed?**

Yes, on paid plans. A feed group takes a [ranking expression](https://getstream.io/activity-feeds/docs/node/custom-ranking/) such as `decay_linear(time) * popularity`.

**How much custom data fits on an activity?**

The whole activity, built-in and custom fields together, must stay under 10KB at write time. Bigger objects go in [collections](https://getstream.io/activity-feeds/docs/flutter/collections/), though collection data can't be used in ranking or aggregation.

**Can users comment on and react to activities?**

Yes. [Comments](https://getstream.io/activity-feeds/docs/flutter/comments/) support threading and [reactions](https://getstream.io/activity-feeds/docs/flutter/reactions/) work on activities and comments alike.

**How do I migrate from Feeds v2?**

From the [dashboard](https://getstream.io/signin/?product=feeds), which replicates live v2 traffic to v3 while you integrate. The [migration guide](https://getstream.io/activity-feeds/docs/node/v2-to-v3-migration/) covers the phases.

**Can feed content be moderated?**

Yes. Moderation is built in through `client.moderation`. See [moderation](https://getstream.io/activity-feeds/docs/flutter/moderation/).

---

For the most recent version of this documentation, visit [https://getstream.io/activity-feeds/docs/flutter/](https://getstream.io/activity-feeds/docs/flutter/).