External ranking parameters
Confused about "External ranking parameters"?
Let us know how we can improve our documentation:
External ranking parameters
Copied!Confused about "External ranking parameters"?
Let us know how we can improve our documentation:
The scoring algorithm is working off of data such as parameters on the activity itself, analytics counters or reaction counters. For most use cases this is enough to present a relevant ranked feed based on those (semi-static) parameters, but it's lacking the capabilities to rank a feed based on a users own preferences.
In order to rank a feed based on a users preferences (i.e a personalized feed) Stream now accepts external parameters that can be used at call time in the scoring algorithm.
Using external ranking parameters
Copied!Confused about "Using external ranking parameters"?
Let us know how we can improve our documentation:
In order to utilize external ranking parameters there's two things that needs to be done
define at least one external parameter in the scoring algorithm
use the external parameter(s) when fetching and ranking the feed
1. Define an external parameter in the scoring algorithm
External parameters are defined by using the reserved keyword external
in the scoring algorithm.
2. Use the external parameter
To use external parameters you need to supply a JSON encoded object (and properly url encoded) in the query string named ranking_vars
, like so: ranking_vars=urlencode({"X": 42})
. This will make the ranking assign external.X
the value 42
and thus get the total score of 43
.
Example: Music service
Consider the example of a music service that lets users upload songs and that they have a "global" front page feed that highlights the latest uploaded songs (activities). A naive approach might be to leave it unranked (i.e ranked by time) but this might not be front page worthy content. A better approach could be to rank the activities in this feed by the number of views or reactions on the activity, like a "new and hot" feed. The best approach is potentially to have a "new and hot" feed that also takes into account the type of activities (i.e type of music) that the user likes.
Consider two different users "the metalhead", which only listens to metal and "the classicist", which only listens classical music. Lets say we have this list of recent activities posted to the "global" feed.
We can then score these activities with the following scoring algorithm (external prefix dropped for brevity):
score = w_rock*classes.rock + w_pop*classes.pop + w_metal*classes.metal + w_classical*classes.classical + w_rap*classes.rap
and at call time we can supply the weights for a specific user, i.e for "the metalhead" we can specify the weights as
{"w_rock": 5, "w_pop": 1, "w_metal": 20, "w_classical": 4, "w_rap": 0}
which will put song4 and song1 at the top of the feed for that user.
"The classicist" only cares about classical music with these weights
{"w_rock": 0, "w_pop": 0, "w_metal": 0, "w_classical": 1, "w_rap": 0}
which will order the feed based on the classical score only so song6 and song5 will be at the top of the feed for that user.
Full example
Copied!Confused about "Full example"?
Let us know how we can improve our documentation:
Here follows a full example of the music service described above. The ranking algorithm, named docs_music_service
in the code, looks like this:
In the code (python) we simulate the music service by adding 10 activities to a feed with random values assigned to each of the classes. We also define three different users THE_METALHEAD
, THE_ALL_EATER
and ANYTHING_BUT_METAL
When you run this code it will perform the following steps
construct a new feed in the
user
feed groupadd 10 activities to the feed with random music genre classes assigned
rank and print the feed for each of the 3 users
The output, depending on the random classes, will look something like this:
As you can see, we get 3 different rankings depending on which user is fetching the feed.
Distance based ranking
Copied!Confused about "Distance based ranking"?
Let us know how we can improve our documentation:
The external ranking parameters can be used together with the function dist
from custom ranking to rank activities based on the distance the user is from them. For this to work each activity must have a latitude and longitude associated with them. If we just want to rank by distance we can use the following custom ranking (assumed to be named distance
below):
When we add activities we make sure they have fields lat
and lng
, like so:
Now, when we read the feed we can send in the reading users location (as denoted by external.lat
and external.lng
) in the custom ranking