Activity Feeds V3 is in closed alpha — do not use it in production (just yet).

Activity selectors

Activity selectors give you control over which data is shown in a feed. For example you can decide to show only popular activities, or activities that fit the current user’s interests.

This page details what kind of activity selectors are supported by the Stream API, and how can you configure them.

Selector types

Current Feed Selector

Shows activities from the current feed. This is the selector used when reading a user feed.

Parameters

Name	Type	Description	Default	Required
`cutoff_time`	string, must be formatted as an RFC3339 timestamp	Activities older than this date won’t be selected	Last 7 days	No

Scope

The feed we’re currently reading

Example

const last10Days = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "current_feed",
      // Optionally provide cutoff time
      cutoff_time: last10Days.toISOString(),
    },
  ],
});

package main

import (
    "context"
    "log"
    "time"

    "github.com/GetStream/getstream-go/v3"
)

func main() {
    client, err := getstream.NewClient("<your_api_key>", "<your_api_secret>")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    feedsClient := client.Feeds()

    // Calculate cutoff time (10 days ago)
    last10Days := time.Now().Add(-10 * 24 * time.Hour)

    // Create view with current feed selector
    view, err := feedsClient.CreateFeedView(ctx, &getstream.CreateFeedViewRequest{
        ViewId: getstream.PtrTo("current_feed_view"),
        ActivitySelectors: []getstream.ActivitySelector{
            {
                Type: getstream.PtrTo("current_feed"),
                // Optionally provide cutoff time
                CutoffTime: getstream.PtrTo(last10Days.Format(time.RFC3339)),
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Current feed view created: %s", *view.Data.ViewId)

    // Create feed group with the view
    response, err := feedsClient.CreateFeedGroup(ctx, &getstream.CreateFeedGroupRequest{
        FeedGroupId:   getstream.PtrTo("myid"),
        DefaultViewId: view.Data.ViewId,
        Custom: map[string]interface{}{
            "description": "Feed group with current feed selector",
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Feed group created: %+v", response.Data)
}

Following Feed Selector

Shows activities from feeds the current feed follows. This is the selector used when reading a timeline feed.

Parameters

Name	Type	Description	Default	Required
`cutoff_time`	string, must be formatted as an RFC3339 timestamp	Activities older than this date won’t be selected	Last 7 days	No

Scope

Feeds followed by the feed we’re currently reading

Example

const last10Days = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "following",
      // Optionally provide cutoff time
      cutoff_time: last10Days.toISOString(),
    },
  ],
});

Popular Activity Selector

Selects popular activities from public and visible feeds.

Popularity is computed by the following formula:

activity.popularity = reactions + comments * 2 + bookmarks * 3 + shares * 3;

Parameters

Name	Type	Description	Default	Required
`min_popularity`	number (only positive numbers are accepted)	Minimum popularity an activity should have to be selected	`0`	No
`cutoff_time`	string, must be formatted as an RFC3339 timestamp	Activities older than this date won’t be selected	-	No

Scope

Any feed with public or visible visibility level.

const last10Days = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "popular",
      // Optional parameters
      min_popularity: 70,
      cutoff_time: last10Days.toISOString(),
    },
  ],
});

Proximity Activity Selector

Shows activities based on geographic proximity

Parameters

Name	Type	Description	Default	Required
`filter`	object, see Filter	You must provide either `near` or `within_bounds` keys when using `filter`	-	No (if not provided, you need to set location data for user, see example below)
`cutoff_time`	string, must be formatted as an RFC3339 timestamp	Activities older than this date won’t be selected	Last 7 days	No
`min_popularity`	number (only positive numbers are accepted)	Minimum popularity an activity should have to be selected	`0`	No

Scope

The feed we’re currently reading

Example

// Provide filter when reading the feed
await feed.getOrCreate({
  filter: {
    within_bounds: {
      $eq: {
        ne_lat: 52.43017,
        ne_lng: 4.924821,
        sw_lat: 52.334272,
        sw_lng: 4.822116,
      },
    },
    // Optionally provide other filter properties, just like when querying activities
    activity_type: "hike",
  },
});

// Use either within_bounds or near filter
await feed.getOrCreate({
  filter: {
    near: { $eq: { lat: 52.373558, lng: 4.885261, distance: 10 } },
  },
});

// You can omit filter if location is set for user
const me = client.state.getLatestValue().connected_user;
await client.updateUsersPartial({
  users: [
    {
      id: me.id,
      set: {
        lat: 52.373558,
        lng: 4.885261,
      },
    },
  ],
});

await feed.getOrCreate({
  // If filter is not provided, but feed group has proximity selector, API searches based on user's location
});

const last1Day = new Date(Date.now() - 1 * 24 * 60 * 60 * 1000);

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "proximity",
      // Optional parameters
      min_popularity: 40,
      cutoff_time: last1Day.toISOString(),
    },
  ],
});

// Provide filter when reading the feed
await feed.getOrCreate({
  filter: {
    within_bounds: {
      $eq: {
        ne_lat: 52.43017,
        ne_lng: 4.924821,
        sw_lat: 52.334272,
        sw_lng: 4.822116,
      },
    },
  },
  user_id: "<user id>",
});

// Use either within_bounds or near filter
await feed.getOrCreate({
  filter: {
    near: { $eq: { lat: 52.373558, lng: 4.885261, distance: 10 } },
  },
  user_id: "<user id>",
});

Interest Activity Selector

Selects activities that match the logged-in user’s interests. Interest is automatically calculated by Stream API based on which activities the user interacts with.

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`min_popularity`	number (only positive numbers are accepted)	Minimum popularity an activity should have to be selected	`0`	No

Scope

Feeds that are visible to the logged-in user.

Examples

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "interest",
      // Optional parameters
      sort: [{ field: "popularity", direction: -1 }],
      filter: {
        activity_type: "post",
      },
    },
  ],
});

Query Activity Selector

Selects activities using the provided filter query.

Parameters

Name	Type	Description	Default	Required
`filter`	object, see Filter	Filter conditions	-	Yes
`sort`	array, see Sort	Sort options	Newest first	No

Scope

Feeds that are visible to the logged-in user.

Example

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "interest",
      filter: { search_data: { $contains: { workout_type: "hike" } } },
      // Optional parameters
      sort: [{ field: "created_at", direction: -1 }],
    },
  ],
});

Selector parameters

Supported values for sort and filter objects.

Sort

The following sort options are available:

Fields:

created_at
popularity

Direction: 1 or -1

Filter

The following filter options are available:

name	type	description	supported operations	example
`id`	string or list of strings	The ID of the activity	`$in`, `$eq`	`{ id: { $in: [ 'abc', 'xyz' ] } }`
`activity_type`	string or list of strings	The type of the activity	`$in`, `$eq`	`{ activity_type: { $in: [ 'abc', 'xyz' ] } }`
`user_id`	string or list of strings	The ID of the user who created the activity	`$in`, `$eq`	`{ user_id: { $in: [ 'abc', 'xyz' ] } }`
`text`	string	The text content of the activity	`$eq`, `$q`, `$autocomplete`	`{ text: { $q: 'popularity' } }`
`search_data`	object	The extra metadata for search indexing	`$contains`, `$path_exists`	`{ search_data: { $contains: { 'category': 'sports', 'status': 'active' } } }`
`interest_tags`	list of strings	Tags for user interests	`$eq`, `$contains`	`{ interest_tags: { $in: [ 'sports', 'music' ] } }`
`filter_tags`	list of strings	Tags for filtering	`$eq`, `$contains`	`{ filter_tags: { $in: [ 'categoryA', 'categoryB' ] } }`
`created_at`	string, must be formatted as an RFC3339 timestamp	The time the activity was created	`$eq`, `$gt`, `$lt`, `$gte`, `$lte`	`{ created_at: { $gte: '2023-12-04T09:30:20.45Z' } }`
`popularity`	number	The popularity score of the activity	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	`{ popularity: { $gte: 70 } }`
`near`	object	Indicates the GEO point to search nearby activities	`$eq`	`{ near: { $eq: { lat: 40.0, lng: -74.0, distance: 200 } } }`
`within_bounds`	object	Indicates the GEO bounds to search for activities within	`$eq`	`{ within_bounds: { $eq: { ne_lat: 40.0, ne_lng: -115.0, sw_lat: 32.0, sw_lng: -125.0 } } }`
`visible_to_user`	boolean	Indicate whether the activity is visible to the user	`$eq`	`{ visible_to_user: { $eq: true } }`

Combining selectors

You can combine multiple selectors. The example below will include:

popular activities from public and visible feeds
activities from feeds the user follows
activities from feeds the user has access to, and matches the user’s interest

You can set up ranking to decide how these activities are ordered in the resulting feed.

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    { type: "popular" },
    { type: "following" },
    { type: "interest" },
  ],

  ranking: { type: "expression", score: "decay_linear(time) * popularity" },
});

Experimenting with selectors

Feed groups let you define what activities should be included in the feed and the ranking to sort these activities.

By default all feeds in the given group will have the same settings. However, you might want to experiment with different selectors and rankings. Feed views let you do that by overriding the group’s default settings.

Ranking

Notification Feeds