Dependencies

• Familiarity with fetching data from the game server - See Fetching Data from the Game Server for how to do this.
• Understanding how and when to use access permissions - If you use user roles, you'll need to understand how permissions work. Working with the LiveOps Dashboard HTTP API is a good primer for this.

Key Concepts

• A Subscription Option is a collection of policies and other configuration options that define how a subscription behaves.

Overview

The subscription system provides an easy way to efficiently fetch data from the game server and share it between dashboard components. One Subscription Option maps to one data source (i.e. one API endpoint) from the game server. There are many pre-defined Subscription Options to make it easy to fetch the most commonly used types of data. If you create your own API endpoints, you might also want to create your own Subscription Options for them.

Quick Guide

Using Subscriptions

It's easy to subscribe to data. Here we'll subscribe to the game server's backend status API:

import { useSubscription } from '@metaplay/subscriptions'
import { getBackendStatusSubscriptionOptions } from '@metaplay/core'

const {
  data: statusData,
} = useSubscription(() => getBackendStatusSubscriptionOptions())

Notice how we subscribe to the data using useSubscription(). We pass in an anonymous function that returns a SubscriptionOptions object from getBackendStatusSubscriptionOptions(). This is a pattern that we use to subscribe to all data sources. You'll find pre-configured subscriptions to most game server endpoints inside the src/subscription_configs folder of the core SDK module.

INFO

Note on Vue's lifecycles: We automatically set up an onUmounted hook to unsubscribe from the subscription when the component is destroyed. While handy, this requires subscriptions to be initialized during the setup function of a component.

Subscriptions with Arguments

Some Subscription Options need arguments to know what URL or query parameters to subscribe to. For example, if you want to subscribe to information about an individual player, the getSinglePlayerSubscriptionOptions() function needs to know the player's ID:

import { useSubscription } from '@metaplay/subscriptions'
import { getSinglePlayerSubscriptionOptions } from '@metaplay/core'

const props = defineProps<{
  playerId: string
}>()

const {
  data: playerData,
} = useSubscription(() => getSinglePlayerSubscriptionOptions(props.playerId))

There are a couple of key things to note here:

• The playerId property is passed to getSinglePlayerSubscriptionOptions() to get the Subscription Options for this specific player.
• If the value of the argument changes, the subscription system notices and automatically subscribes to the new data source. In this case, if playerId is changed to point to a different player then playerData will also be changed to return this new player's data.

Subscription Return Values

When you call the useSubscription() function, you are returned a SubscriptionObject. This object has the following fields:

// We can destructure the fields from the return value like this:
const {
  /**
   * A reactive reference to the data returned by this subscription.
   * This starts out as undefined and changes once the data has been fetched.
   */
  data,
  /**
   * An error object if there was an error fetching the data.
   * Defaults to undefined.
   */
  error,
  /**
   * A boolean value that tells you whether the current user
   * has permission to access this subscription.
   */
  hasPermission,
  /**
   * A function that you can call to refresh the data immediately.
   */
  refresh,
} = useSubscription(getBackendStatusSubscriptionOptions())

You'll already be familiar with data from the example above. But what about the others?

• error contains an Error object if there was an error when fetching the data. This will most likely be a 401 error (did you make a call to an endpoint that you don't have permission to reach?) or a 404 (did you request an endpoint that doesn't exist?).
• hasPermission is a boolean value that lets you know whether the current user has the relevant permissions for this subscription. See below for more details on permissions.
• refresh is a function that you can call to refresh the data immediately. This is useful if you have a slow polling subscription, but you know that the data has become stale.

Advanced Usage

Type Hints

If you know the return data type for a subscription, you can use a type hint to get better type checking and auto-completion. For example, if you know that the getBackendStatusSubscriptionOptions() function returns a BackendStatus object, you can pass it in as a type argument to useSubscription() like this:

import { useSubscription } from '@metaplay/subscriptions'
import { getBackendStatusSubscriptionOptions } from '@metaplay/core'

type BackendStatus = {
  exampleProperty: string
}

const {
  data: statusData,
} = useSubscription<BackendStatus>(getBackendStatusSubscriptionOptions())

// `data` is now a reactive reference to a `BackendStatus` object.

Subscribing to Custom API Endpoints

You can also define your own re-usable Subscription Options if you've added game-specific API endpoints. You can simply copy one of our core Subscription Options as an example and modify it to suit your needs.

For example, if you wanted to create a subscription that fetched the data for a single player every 5 seconds and kept it in the cache for 5 minutes, you could do something like this:

customSubscriptions.ts

import {
  type SubscriptionOptions,
  getFetcherPolicyGet,
  getCacheRetentionPolicyKeepForever,
  getCacheRetentionPolicyTimed,
  getPollingPolicyTimer,
} from '@metaplay/subscriptions'

export function getCustomPlayerSubscriptionOptions (playerId: string): SubscriptionOptions {
  return {
    // The user permission, if any, required to access the underlying data.
    permission: 'api.players.view',
    // How often is new data fetched?
    pollingPolicy: getPollingPolicyTimer(5000), // 5000ms, or 5 seconds
    // How is the data fetched?
    fetcherPolicy: getFetcherPolicyGet(`/players/${playerId}`),
    // How long is the data kept in the cache after polling has stopped?
    cacheRetentionPolicy: getCacheRetentionPolicyTimed(300000), // 300000ms, or 5 minutes
  }
}

The Anatomy of Subscription Options

A SubscriptionOptions object tells the subscription system how to fetch data from the server and what to do with it once it arrives.

export interface SubscriptionOptions {
  /**
   * Defines when to poll for new data from the server.
   */
  pollingPolicy: PollingPolicy

  /**
   * Defines how to fetch data for this subscription form the server.
   */
  fetcherPolicy: FetcherPolicy,

  /**
   * Optional: Data mutation function for this subscription.
   */
  dataMutator?: DataMutatorCallback

  /**
   * Optional: The permission required for the data fetch to succeed. 
   * If user does not have this permission then we can fail early and skip the fetch.
   */
  permission?: string

  /**
   * Cache retention policy (when to clear old data) 
   * for when there are no more subscribers.
   */
  cacheRetentionPolicy: CacheRetentionPolicy
}

• permission - Most game server API endpoints are protected by permissions. This means that only users who are permitted to use the endpoints can. If a user who is not permitted to use an endpoint tries to do so, the game server responds with a 401 error. For a more user-friendly experience, the subscription system can check that the user has the required permission before trying to fetch the data. To make that happen, you just need to set the permission field.
• pollingPolicy - The polling policy tells the subscription system when it should poll the game server for changes. The available polling policies are:
  • Timer - The polling takes places every n milliseconds. This is the most commonly used polling policy.
  • Once only - Polling never takes place. This is used for data that never changes.
  • Runtime options - Polling takes place whenever the game server's runtime options are updated. This is a rather specialist policy that doesn't have much use outside of the Metaplay core subscriptions.
• fetcherPolicy - The fetcher policy tells the subscription system how to fetch the data from the game server. There are two different fetcher policies available:
  • Get - This takes a URI and performs a GET on that URI to retrieve the data.
  • Fixed - This policy does not call the game server at all; instead, it returns a fixed set of data. This is not used in production code, but can be very useful when developing new features.
• dataMutator - After the data is fetched, there is an optional data mutation stage before it is returned to the client. You can use this stage to massage or fix up the data to put it into a desired state that is easier to handle in the rest of your dashboard code. Generally it is better practice to fix the data at source (i.e. inside the game server API controller) but we do use a data mutator in a couple of places to decorate data before returning it to the client.
• cacheRetentionPolicy - The cache retention policy tells the subscription system how long to keep the data in the cache after all subscribers have unsubscribed. The available cache retention policies are:
  • Timed - The data is evicted after n milliseconds. This is the most common cache retention policy and is used to ensure that data that is not frequently re-used (such as the details of a specific player) does not stay in the cache forever.
  • Keep forever - Some data is small, used in many places and never changes. This policy can be used to ensure that such data is always available from the cache by never evicting it.
  • Delete immediately - Conversely, some data is large and rarely re-used. This policy can be used to tell the subscription system to never keep that data in the cache.

Static Subscriptions

As discussed above, the subscription system automatically watches the subscription options and re-subscribes to the new data source if they change. There is a small amount of overhead associated with this. The overhead is so small that you normally don't need to worry about it, but you may notice in some of our core Dashboard code that we sometimes use a slightly different way to subscribe to data:

import { useSubscription } from '@metaplay/subscriptions'
import { getBackendStatusSubscriptionOptions } from '@metaplay/core'

const {
  data: statusData,
} = useSubscription(getBackendStatusSubscriptionOptions())

Note the small difference here - we pass in a SubscriptionOptions object directly, whereas previously we've passed in a function that returns a SubscriptionOptions object. Doing it this way means that the subscription object cannot watch for changes, which means that it can use a slightly optimized code path. And that's fine here because we know that getBackendStatusSubscriptionOptions will never change.

This isn't something that you need to worry about, but now you know why it's there should you spot it during a dive into our core code.