Active deployment telemetry is used to find the live server deployments that have the best telemetry to a player or a group of players.
But first, we recommend verifying if the Sessions would be better suited for your needs. You can read the documentation here.
Imagine multiple deployments are running in a region, and a group of players wants to join a game instance. You could randomly put them on a server in that region. However, a better option could be to use active deployment telemetry to determine the servers with the best telemetry to your players.
Once you get the best deployment, you can make that your backend assigns your group of players to this one.
You can easily use active deployment telemetry with simple API request. You send us a list of RequestID corresponding to your deployments and a list of IPs corresponding to the players you want to assign a server. Note that you are not limited to only one player.
The request will send you a unique retrieval key that you can use to get information about your request. See API documentation.
We will then take live telemetry as we would do with a new deployment. The API request will send you back the list of RequestID with the first one as the best one for the specific IPs list given.
To get your results, we are recommending using a webhook because looping until you have a response is rarely a good pattern. Alternatively, you can make a GET request with the retrieval key to our API.
You can include the webhook (POST URL) in your initial request. We are expecting a 2xx status code from your API and we will retry 5 times until we get that status.
The response we will send you back will look like this.
A normal telemetry request takes about 5-10 seconds to complete. To complement the use of the webhook, we recommend creating a fallback mechanism in case you do not receive the webhook. For example, you can make a GET request with your retrieval key to the API 15 seconds after the start of your initial request if you have not received the call.
You might ask yourself why you wouldn't receive the webhook call. Here are the most common reasons.
- One or more given deployment is not in READY state.
- One or more given deployment is TERMINATED.
- More rarely case where our location could be in maintenance or in error.
All the above reasons result in a partial response, which means we couldn't get the telemetry on one or more given deployments. We do not currently support webhook on partial response and that's why we are recommending using a fallback mechanism.