Ranking

The ranking endpoint allows you to send arbitrary per-user keys to the server and request a ranked response of the most popular. The keys can be any string value.

Every rank has a ‘namespace’, which consists of lower-case alphanumeric characters and the hyphen ‘-’ character.

Ranking data expires automatically 1 day after the last entry is added. After that point, all rank values will be removed and sending data with the same ‘name’ will act as a new rank.

Sending Ranks

Rank data are unique per user; a user may only have one rank entry per ‘name’. Repeated requests to the rank endpoint with the same name will change the user’s stored value.

NOTE: prefixing a rank name with global will create an extension wide rank more info here

NOTE: We attempt to use the viewer’s real ID if it is known at the time the rank is sent, but will fall back to using their opaque ID. If your extension depends on absolutely correct ranking behavior, you should only allow viewers who have shared their ID to send values. Otherwise, it is possible for viewers to send multiple values by repeatedly sharing and unsharing their ID (this gives them a new opaque ID each time).

To send a ranking for a user:

const usersFavoriteColor = 'rebeccapurple';

const opts = new Muxy.DebuggingOptions();
opts.role('viewer');
Muxy.debug(opts);

const sdk = new Muxy.SDK();
sdk.rank('favorite_color', usersFavoriteColor).then(resp => {
  if (!resp.accepted) {
    console.error('Could not send this color');
  }
});

Response:

{
  "accepted": true
}

Get Ranking Data

The broadcaster can request the current user rankings for a specific rank name:

const opts = new Muxy.DebuggingOptions();
opts.role('broadcaster');
Muxy.debug(opts);

const sdk = new Muxy.SDK();
sdk.getRankingData('favorite_color').then(colors => {
  if (colors.data.length > 0) {
    colors.data.forEach(color => {
      console.log(`${color.key}: ${color.score}`);
    });
  }
});

The response has the structure:

{
  "data": [
    { "key": "rebeccapurple", "score": 5 },
    { "key": "arcticblue", "score": 2 },
    { "key": "olivedrab", "score": 1 }
  ]
}

data will be an ordered array sorted by the “score” (how many people submitted ranks for that key) for the top 100 keys.

Extension-Wide Rank

If keys are prefixed with global the rank will be shared across all instances of the extensions.

This is useful if multiple broadcasters are co-streaming an event with an extension so that every viewer’s rank entries count for the entire event.