Ranking

Stream allows you to configure your own ranking method to determine the order of activities inside a feed.

An example ranking config is shown below:

const response = await serverClient.feeds.createFeedGroup({
  id: "mytimeline",
  ranking: { type: "expression", score: "decay_linear(time) * popularity" },
  activity_selectors: [
    {
      type: "following",
    },
  ],
});

Supported types for configuration:

Read on to learn the syntax for expression and interest based ranking.

The result of the ranking expression should be a number (called score). Activities in the feed will be ordered by score (highest score first).

Example of a simple ranking expression, order activities by popularity:

await serverClient.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [{ type: "following" }],
  ranking: {
    type: "expression",
    score: "popularity",
  },
});

Ranking expression syntax

Activity data

It’s not possible to access all fields of an ActivityResponse inside the ranking context. Below you’ll find the list of supported fields:

It’s possible to set default values if you expect that some data might be undefined for some activities:

await serverClient.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [{ type: "following" }],
  ranking: {
    type: "expression",
    score: "popularity * (custom.isBoosted ? 1.5 : 1)",
    defaults: {
      custom: {
        isBoosted: false,
      },
    },
  },
});

Data types

The following data types are supported in the ranking expression context:

Functions

The following functions can be used in ranking expressions:

Operators

The following operators can be used in ranking expressions:

• Arithmetic operators: +, -, *, /, % (modulus), ^, ** (exponent)

• Logical operators: not/!, &&/ and, ||/or

• Conditional: x ? y : z, ??, if/else

• Comparison: ==, !=, <, >, <=, >=

• Control order of evaluation with parentheses ()

• Array/map operators: [] (index), ., ?., in (checks if an array/map has an item/key)

• String operators: + (concatenation), contains, startsWith, endsWith

This lets you construct a scoring algorithm like this:

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

Constants

The following constants and helpers are also available to use in ranking expressions:

Decay & Ranking

Stream supports linear, exponential, and Gaussian 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

The example below defines a simple_gauss with the following parameters:

• scale: 5 days

• offset: 1 day

• decay: 0.3

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 example:

await serverClient.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [{ type: "following" }],
  ranking: {
    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",
      },
    },
    score: "simple_gauss(time)*popularity_gauss(popularity)",
  },
});

Interest weights

Interest weights help customize the ranking to users’ interests. If you want to create a ranking expression that relies on interest weights, use interest type ranking.

serverClient.feeds.createFeedGroup({
  id: "myid",
  ranking: {
    type: "interest",
    score: "interest_score * popularity",
  },
});

interest_score is computed by combining activity topics and the specific user’s interests. The result is a number between 0-1.

Activity topics

The topic of an activity can be computed automatically using activity processors or by setting the interest_tags field via the Stream API.

User interests

A user’s interests can be computed automatically by the Stream API based on which activities a user interacts with. It’s also possible to provide interest weights when reading the feed (which override the automatically computed weights):

await timeline.getOrCreate({
  interest_weights: {
    travel: 1,
    food: 0.5,
    exercise: -1,
  },
});

await timeline.getOrCreate({
  interest_weights: {
    travel: 1,
    food: 0.5,
    exercise: -1,
  },
  user_id: "<user id>",
});

The range for interest weights is between -1 and 1. 1 means a user is very interested in a topic.

External data

External data lets you add dynamic data to your ranking expressions. External data is provided when reading the feed, so you can provide user-specific data here.

Accessing external data in ranking expressions

serverClient.feeds.createFeedGroup({
  id: "myid",
  ranking: {
    type: "expression",
    score:
      "popularity * external.popularity_multiplier + share_count * external.share_multiplier",
    defaults: {
      external: {
        // Provide default values if external data isn't provided when reading the feed
        popularity_multiplier: 1,
        share_multiplier: 1,
      },
    },
  },
});

Providing external data when reading the feed

await timeline.getOrCreate({
  external_ranking: {
    popularity_multiplier: 1, // normal weight for popularity
    share_multiplier: 100, // very high boost for share_count
  },
});

await timeline.getOrCreate({
  external_ranking: {
    popularity_multiplier: 1, // normal weight for popularity
    share_multiplier: 100, // very high boost for share_count
  },
  user_id: "<user id>",
});

Inspecting ranking variables

When reading the feed, you can access the:

• score of each activity (this is the result of the ranking expression)
• reaction count of each activity (the sum of all reactions)
• standard fields like popularity can also be observed when reading the feed

These variables can help you understand the result of the ranking expression.

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

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

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

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

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

Experimenting with ranking

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.