Stories

Stories are activities with an expiration date, usually used to share information that is available for a limited amount of time. Most often there is a dedicated feed for users to post expiring activities, and there is a separate timeline for reading stories.

Built-in story groups

There are two built-in story groups:

  • story for users to post their stories to
  • stories for users to follow others' stories

It's possible to update the built-in story groups or create custom ones.

Creating story groups

If you prefer to create your own story feed groups, you can do so with custom feed groups.

Creating or updating feed groups is only possible server-side.

The following example defines two feed groups:

  • my-story for users to post their stories to
  • my-stories for users to follow others' stories

There are two settings specific to story feed groups:

  • You can enable tracking watched activities: this makes it possible to track which stories a user has seen or not (please note that this is different from notification configurations, typically you don't need that for stories)
  • You can decide if watched stories should be removed from the feed. It's false for the built-in story groups
require 'getstream_ruby'

client = GetStreamRuby.manual(
  api_key: 'api_key',
  api_secret: 'api_secret'
)

# Create my-story feed group
story_request = GetStream::Generated::Models::CreateFeedGroupRequest.new(
  id: 'my-story',
  stories: GetStream::Generated::Models::StoriesConfig.new(
    skip_watched: false,
    track_watched: true
  )
)
client.feeds.create_feed_group(story_request)

# Create my-stories feed group
stories_request = GetStream::Generated::Models::CreateFeedGroupRequest.new(
  id: 'my-stories',
  stories: GetStream::Generated::Models::StoriesConfig.new(
    skip_watched: false,
    track_watched: true
  ),
  aggregation: GetStream::Generated::Models::AggregationConfig.new(
    format: '{{ user_id }}'
  ),
  activity_selectors: [
    GetStream::Generated::Models::ActivitySelectorConfig.new(type: 'following')
  ]
)
client.feeds.create_feed_group(stories_request)

Posting stories

Usually stories are activities containing a single image or video. But you can implement them any way you want.

val johnStoryFeed = client.feed(group = "story", id = "john")
johnStoryFeed.getOrCreate()

val tomorrow = Calendar.getInstance().apply {
    add(Calendar.DAY_OF_YEAR, 1)
}

johnStoryFeed.addActivity(
    request = FeedAddActivityRequest(
        type = "post",
        attachments = listOf(
            Attachment(
                imageUrl = "https://example.com/image.jpg",
            )
        ),
        expiresAt = tomorrow.toInstant().toString()
    )
)

Activities on story feeds are ordered cronologically.

Following story feeds

Following someone's story feed is the same as following any other feed:

val saraStoryTimeline = client.feed(
    query = FeedQuery(group = "stories", id = "sara", watch = true)
)
saraStoryTimeline.getOrCreate()

saraStoryTimeline.follow(johnStoryFeed.fid)

Reading story timeline and marking activities as watched

val saraStoryTimeline = client.feed(
    query = FeedQuery(group = "stories", id = "sara", watch = true)
)
saraStoryTimeline.getOrCreate()

// Since story timeline is aggregated by user id, we read aggregated activities
val johnStories = saraStoryTimeline.state.aggregatedActivities.value[0]

// Display all of John's active stories
johnStories.activities.forEach { activity ->
    // True if we watched a given story
    println(activity.isWatched)
}

// Mark a story as watched
saraStoryTimeline.markActivity(
    MarkActivityRequest(
        markWatched = listOf(johnStories.activities[0].id)
    )
)

Story groups in story timelines are sorted by unread count. Watched story groups are returned last (unless the feed group is configured not to return watched stories).

When marking an activity as watched, feeds.stories_feed.updated WebSocket event is dispatched to clients of the user who marked the activity (Sara in this example). There are no WebSocket events sent when a user adds to their story, you need to reread the feed to get updates.

While there is no limit of how many active stories a user can have, aggregated_activities return the latest 100 activities for each group.

Pagination for story groups work the same way as for any other feeds. This is how you can load the next page of story groups:

feed = client.feed('user', 'jack')

# First page
first_page = feed.get_or_create_feed(
  GetStream::Generated::Models::GetOrCreateFeedRequest.new(
    user_id: 'jack',
    limit: 10
  )
)

# Second page using next cursor from first page
if first_page.next
  second_page = feed.get_or_create_feed(
    GetStream::Generated::Models::GetOrCreateFeedRequest.new(
      user_id: 'jack',
      limit: 10,
      next: first_page.next
    )
  )
end

Reading story feed

Following someone's story feed is one way to read stories. However, it's also possible to read someone's story feed directly:

// Sara reads John's story feed
// By default new activities are added to the start of the list, but this is not what we want for stories
val johnStoryFeed = saraClient.feed(
    query = FeedQuery(group = "story", id = "john", activityLimit = 100, watch = true),
    onNewActivity = { _, _, _ -> InsertionAction.AddToEnd }
)
johnStoryFeed.getOrCreate()

val johnStories = johnStoryFeed.state.activities.value

// Display all of John's active stories
johnStories.forEach { activity ->
    // True if we watched a given story
    println(activity.isWatched)
}

// Mark a story as watched
johnStoryFeed.markActivity(
    MarkActivityRequest(
        markWatched = listOf(johnStories[0].id)
    )
)

When marking an activity as watched, feeds.stories_feed.updated WebSocket event is dispatched to clients of the user who marked the activity (Sara in this example). If a new story is added to the feed, a feeds.activity.added event is dispatched.

Reading expired stories

Users can list the expired stories that they created, but it's not possible to read other users' expired stories:

val now = Date()
val query = ActivitiesQuery(
    filter = Filters.and(
        ActivitiesFilterField.expiresAt.lessOrEqual(now.toInstant().toString()),
        ActivitiesFilterField.userId.equal(john.id)
    ),
    sort = listOf(ActivitiesSort(ActivitiesSortField.CreatedAt, SortDirection.REVERSE))
)
val activityList = client.activityList(query)
val result = activityList.get()