Selectors Filtering

Selectors are optional filtering data that you can include in your session creation request to filter the deployments that will be considered to host the session. To make it simple, we will only choose a deployment to host your session that has all the specified tags in the request. You can also use tags to dynamically add environment variables to your deployment.

When You Should Consider the Selectors

Probably always is the right answer because sooner or later, you may need to manage different things in your filtering, such as maps, game type, player statistics, and so on. However, we understand that sometimes you may only want to test things quickly. Therefore, here are some common use cases of selectors:

• Filter deployments with specific tags to host your session.

• Tag your session to identify them.

• Dynamically inject environment variables when using the autodeploy option.

You can achieve mostly the same results as using selectors by creating multiple application versions with different configurations in each. However, using selectors can simplify your development since you will need to manage fewer application versions, as you can use the same version with different selectors and contexts.

How to Use Them

These concepts can build on top of each other, but we will go through each one in its own section.

All the filtering will be applied within the range established at the start of the session request. This means that if there is a deployment corresponding to the selectors, but it's not in a suitable range, the deployment won't be chosen to host the session.

The autodeploy option will create a new deployment in the best location available. You can read more about this here.

Filter By Tags

Adding tags to the selectors list like this will make your session request search for a deployment with tags Ranked and Map A. If you don't have the autodeploy option activated and there are no deployments with these tags, your session request will be set to an unprocessable state. On the other hand, if autodeploy is activated, we will automatically create a new deployment, tag it with these tags, and then link it to your session.

A deployment needs to have all the specified tags to be considered suitable for hosting a session.

{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4"],
  "selectors": [
    {
      "tag": "Ranked"
    },
    {
      "tag": "Map A"
    }
  ]
}

Dynamically Add Environment Variables

This example applies the same concepts as above, so if no deployment is found with tags Map A and autodeploy is activated, we create a new tagged deployment. But we added the env key to the selector object, which will inject the MAP_ID environment variable with a value of 1 in the deployment. This environment variable will be available within the server.

{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4"],
  "selectors": [
    {
      "tag": "Map A",
      "env": {
        "key": "MAP_ID",
        "value": "1"
      }
    }
  ]
}

If you had created a deployment with the tag Map A before, but without the env parameter, and then you make a session request that will be linked to that deployment using the env parameter, the environment variable won't be added dynamically since we cannot modify environment variables on a running deployment.

Similar to the previous warning, if you create two different sessions with the same tag but with different environment variables, only the environment variables of the session that triggered the autodeploy will be applied.

Add Tags to Session Without Filtering

If you only want to add tags to your sessions without filtering the deployments, you can use the tag_only attribute in your session request. This allows you to add tags to the session without actually filtering the deployments.

However, note that you cannot use tag_only in combination with injecting environment variables using the env attribute.

In this example, we will add the tag Europe to each session created with this request. The tag Europe is only applied to the session and not the deployment. It does not affect the filtering of the deployments in any way.

{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4"],
  "selectors": [
    {
      "tag": "Europe",
      "tag_only": true
    }
  ]
}

Complete Example

We have a single application version with two modes: Ranked and Casual. Autodeploy is activated. We have two maps: Map A and Map B. Each mode can use each map. We want to tag each game with Matchmaker #1234, indicating the source of the request. We want this tag only for tracking purposes and won't affect the filtering of the deployments.

The game is loading the map's assets based on the injected environment variable.

Using the selectors in a scenario like this makes a lot of sense, since without them, you would need to manage a different application version for each map, which would result in more complexity and management overhead.

Someone wants to play a ranked of in Map A. This map has the ID 1. We wouldn't want to put someone who wants to play in the Map A in the Map B, so we will need to handle this properly. This would be a correct request:

{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4"],
  "selectors": [
    {
      "tag": "Ranked"
    },
    {
      "tag": "Map A",
      "env": {
        "key": "MAP_ID",
        "value": "1"
      }
    },
    {
      "tag": "Matchmaker #1234",
      "tag_only": true
    }
  ]
}

This request will search for a deployment tagged with both Ranked and Map A, and if it can't find any, it will create a new one and tag it with both tags. In both cases, the session will be tagged with Matchmaker #1234.

If we send another request for a casual game in the Map B map, the request will look like this. The Map B map has the ID 2. The expected results are the same as the other request.

{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4"],
  "selectors": [
    {
      "tag": "Casual"
    },
    {
      "tag": "Map B",
      "env": {
        "key": "MAP_ID",
        "value": "2"
      }
    },
    {
      "tag": "Matchmaker #1234",
      "tag_only": true
    }
  ]
}