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

Ranking

Ranking feeds is only available on the server-side SDKs.

Stream allows you to configure your own ranking method. You can add multiple ranking methods to a given feed group.

Ranked feeds are only available on Standard plans and higher. Contact support after upgrading your account to enable ranked feeds for your organization.

An example ranking config is shown below:

const view = await serverClient.feeds.createFeedView({
  view_id: uuidv4(),
  ranking: {
    {
      type: "expression"
      score: "decay_linear(time) * popularity ^ 0.5",
      defaults: {
        "popularity": 1
      }
    }
  }
});

Available Functions

obs: functions are parsed in lowercase

name	description
Basic Arithmetic	The following are supported: + - * / ( ) ^
ln(x)	Log Function natural base
log(x)	Log Function base 10
sin(x)	Trigonometric sine function
cos(x)	Trigonometric cosine function
tan(x)	Trigonometric tangent function
abs(x)	Absolute value
min(a,b)	Minimum value
max(a,b)	Maximum value
trunc(x)	Truncates to the nearest integer value
round(x)	Rounds to the nearest integer value
decay_linear(t)	Linear Decay
decay_exp(t)	Exponential Decay
decay_gauss(t)	Gauss Decay
rand_normal()	Returns a normally distributed number in the range [-inf, +inf] with standard normal distribution (stddev = 1, mean = 0)
rand_normal(a,b,σ,µ)	Returns a normally distributed number in the range [a, b] with specific normal distribution (stddev = σ, mean = µ)
rand()	Returns a random number in the range [0, 1.0)
rand(a,b)	Returns a random number in the range [a, b)
to_unix_timestamp(t)	Converts a time value to a unix timestamp
dist(lat1,lng1,lat2,lng2,unit)	Returns the distance between the two points given by (lat1,lng1) and (lat2,lng2). By default the unit is in kilometers, but the unit can also be M for miles or N nautical miles. This function can be combined with the external ranking parameters to rank activities based on a users distance to them.

Operators

The scoring algorithm has support for simple control flows and logical operators.

Logical operators && and ||
Ternary conditional x ? y : z
Control order of evaluation with parens ()

This lets you construct a scoring algorithm like this

"score":"(a > 2 || (b > 4 && c > 3)) ? 1 : -1"

Adding Activities

Below is an example of how to add activities with custom data that you can use for ranking as well:

const activity = await feed.addActivity({
  type: "post",
  text: "Great content",
  custom: {
    quality_score: 0.95,
    engagement_prediction: 0.8,
  },
});

const activity = await client.feeds.addActivity({
  fids: [feed.fid],
  type: "post",
  text: "Great content",
  custom: {
    quality_score: 0.95,
    engagement_prediction: 0.8,
  },
  user_id: "<user id>",
});

Retrieving Activities

Below is an example of how to retrieve activities sorted by custom ranking:

const feed = client.feed("user", "sara");

// Reads feed with the default view configured for the given feed group (user group in this case)
const response = await feed.getOrCreate();
// Provide a custom view when reading the feed
const response = await feed.getOrCreate({ view: "myview" });

const feed = client.feeds.feed("user", "sara");

// Reads feed with the default view configured for the given feed group (user group in this case)
const response = await feed.getOrCreate({ user_id: "sara" });
// Provide a custom view when reading the feed
const response = await feed.getOrCreate({ user_id: "sara", view: "myview" });

You can only use limit and offset for pagination with custom ranking.

Configuring ranking can be complex. Feel free to reach out to support if you have questions.

More visibility into ranking variables

The score field of an activity contains the result of the ranking algorithm.

const feed = client.feed("user", "sara");
const response = await feed.getOrCreate();

console.log(response.activities[0].score);

const feed = client.feeds.feed("user", "sara");
const response = await feed.getOrCreate({ user_id: "sara" });

console.log(response.activities[0].score);

Stream supports a Linear, Exponential, and Gauss decay. For each decay function, we support 4 arguments: Origin, Scale, Offset, and Decay. You can pass either a timedelta string (such as 3d, 4w), or a numeric value.

Parameters

name	description	default
origin	The best possible value. If the value is equal to the origin the decay function will return 1.	now
scale	Determines how quickly the score drops from 1.0 to the decay value. If the scale is set to “3d” the score will be equal to the decay value after 3 days.	5d
offset	Values below the offset will start to receive a lower score.	0
decay	The score that a value at scale distance from the origin should receive.	0.5
direction	left, right or both. If right is specified only apply the decay for the right part of the graph.	both

You can use s, m, h, d and w to specify seconds, minutes, hours, days and weeks respectively.

The example below defines a simple_gauss with the following params:

scale : 5 days
offset : 1 day
decay : 0.3 day

This means that an activity younger than 1 day (the offset) will return a score of 1. An activity that is exactly 6 days old (offset + scale) will get a score of 0.3 (the decay factor). The full JSON config is shown below:

{
  "type": "expression",
  "functions": {
    "simple_gauss": {
      "base": "decay_gauss",
      "scale": "5d",
      "offset": "1d",
      "decay": "0.3"
    },
    "popularity_gauss": {
      "base": "decay_gauss",
      "scale": "100",
      "offset": "5",
      "decay": "0.5"
    }
  },
  "defaults": {
    "popularity": 1
  },
  "score": "simple_gauss(time)*popularity"
}

You can specify defaults for the variables you use. The example above sets popularity to 1 if it’s missing from the activity. We highly recommend setting up defaults to prevent errors when retrieving activities without these variables.

Custom ranking is only working on the last 1000 activities of the feed.

Configuring ranking can be complex. Feel free to reach out to support if you have questions!

Analytics & Reaction Counts

Analytics and Reaction Counts can be used in ranking easily, contact support to get them enabled.

{
  "type": "expression",
  "defaults": {
    "analytics": {
        "view": 0
    },
    "reaction_counts": {
      "like": 0,
      "comment": 0
    }
 },
 "score":"simple_gauss(time)*(0.1*analytics.view+0.5*reaction_counts.like+reaction_counts.comment)"
}

In this example, we define defaults for activities that might be missing any analytics or reactions on it. Then, a linear combination of these numbers is adjusted according to passed time.

Reaction counts are cached for 30 minutes. Therefore, when using this as a ranking criteria, you can anticipate a small delay between when a new reaction is added / removed and the recalculation of the score of the activity.

Aggregation

Selectors