<img src="https://certify.alexametrics.com/atrk.gif?account=bIEZv1FYxz20cv" style="display:none" height="1" width="1" alt="">

Dynamic Space Creation by Name

SECTIONS

Project Complexity: ★★★☆☆

As described in the guide "Get a JWT," High Fidelity uses JSON WebTokens (JWTs) for authenticating and routing incoming connection requests. These JWTs are used both to ensure that the connecting user is authorized to use your High Fidelity instance, and also to specify the exact space to which the user should be connected.

You provide a JWT when using the HiFiCommunicator class and its connectToHiFiAudioAPIServer() method, and it is created by your application code. This JWT should also be signed with your application's secret, to ensure it's being created by you, and should contain the following information:

  • The space to which you want to connect the user
  • The application under which that space is located
  • An optional user ID that can be used to identify the user

When the High Fidelity servers receive your user's request to connect, they will parse out these pieces of information from the JWT, and connect the user to the specified space. This is what allows the user to speak with and hear other people who are connected to the same space.

 

1. Specifying a Space

As described above, one of the pieces of information contained within your JWT is the identification of the space to which you want to connect the user. Sometimes, you will want to use the Developer Console to create a persistent space in advance of your users connecting to it, and then include its UUID as the space_id parameter of your JWT. This process is described in the guide "Get a JWT."

You can also use Programmatic Space Management and the Administrative REST API to dynamically create and delete spaces as they become needed. For example, if you run an events platform, you may want to create a space when one of your customers schedules an event, and then delete that space once the event has completed.

 

2. Connecting to a Space by Name

However, in some circumstances it may make the most sense to have spaces created automatically as soon as someone attempts to connect. Therefore, in addition to the Developer Console and the Administrative REST API, you can also use the JWT to instruct the High Fidelity API to dynamically create a space when it is requested. In this model, instead of specifying the UUID of a space, you would specify a space name in the JWT. If the space already exists, the user will immediately be connected to it; if it does not exist, it will be automatically created for you first. Space names are limited to 128 characters, can contain any Unicode characters, and should be encoded using UTF-8.

Info Icon

If you are using this approach to connect to a space by name, please be aware that space names MUST be unique among the spaces of the specified application. Because the space name is used to connect users to the appropriate space, there can only be one space with the given name within the application. If you attempt to connect to a space by name when multiple spaces exist with that name, connection attempts will fail with an error that contains the message "more than one space has the given name." (When connecting via UUID or using other space management methods such as the Developer Console or the Administrative REST API, this is not a restriction, because the space UUIDs are used for identification instead of the name.)

To connect to a space by name, all that's needed is to adjust your JWTs to use the space_name parameter rather than the space_id parameter. As an example, here is a JWT (created using the NodeJS approach described in the Get a JWT guide) that will connect the user to a space with the name "Steve's Party Space", creating that space if it doesn't exist:

 

For comparison, here is the sample code from the Get a JWT guide that shows a JWT that uses the traditional space_id approach:

In this example, if the space named "Steve's Party Space" does not already exist — i.e. if a space with the name "Steve's Party Space" has not already been created via the Developer Console or Administrative REST API — a new space will be automatically created. The space will be named "Steve's Party Space," and then the incoming user will be connected to that space. (And if a space named "Steve's Party Space" DOES exist, the user will be immediately connected to it, regardless of how that space was originally created.)
Info Icon

A space can "exist" even if that space doesn't have any users connected to it at that moment. The existence of a space just means that it has been associated with your account and is available for your users to connect to. Existing spaces can be accessed at any time simply by connecting to the space using the space by UUID or name, and are not removed or destroyed when users disconnect from them. You are not charged for spaces that exist but do not have any users connected to them.

3. Creating a Space by Name Using the REST API

You can also use the Administrative REST API to create a space by name. When using this method, the new space's UUID will be returned from the REST API call, which allows you to then use the space UUID for subsequent space-related REST API calls (such as setting audio environments).

Using this REST API call to create a space by name will also enforce the uniqueness constraint on space names, the same way it is enforced when creating a space by name using the JWT. This is important if you then want to connect to the space using a JWT and the space_name parameter described above. (Note that this differs from the behavior when you use the standard REST API call to create a space, which will allow you to create multiple spaces with the same name.)

To create a space by name using the REST API, make a GET or POST HTTP request to the api/v1/spaces/create-by-name?space_name=$SPACE_NAME&token=$TOKEN endpoint, replacing $SPACE_NAME with the new space name you want to use, and replacing $TOKEN with an Administrative JWT.

Here's an example of how to use this endpoint with cURL:

curl 'https://api.highfidelity.com/api/v1/spaces/create-by-name?name=Party%20Space&token=$TOKEN'


Requests to the api/v1/spaces/create endpoint will respond with JSON data containing the App ID embedded in your JWT and the ID of the newly-created Space. For example, a response may look like this:

 

4. Using Space Templates

When creating spaces by name, either using a JWT or using the Administrative REST API, you may wish to create the space with an initial set of properties and settings attached. For example, if your standard user interface includes "quiet zones," you may want to apply a predetermined set of attenuation zones to every space that gets created. Or, you may want to automatically set the capacity for each space that you create.

This can be accomplished through the use of space templates. A space template is an example space that you set up by hand, and then can use as a pattern for future spaces that get created. To set up a space template, you would first create a space manually through the Developer Console or the Administrative REST API. Then, use the Administrative REST API to configure the space to your liking (for instance, by assigning attenuation zones or adjusting other settings of the space).

 

Info Icon

When you use a space template to create a new space, the settings from the template are copied to the new space. There is no persistent link between the new space and the original template. Therefore, if you make changes to the template after a space is created, those changes will NOT affect existing spaces. If you want the new changes to be reflected in the existing spaces, you should delete those spaces and allow them to be recreated using the updated template.

To use this space template for space creation, you would include either the template's UUID or its name as part of the JWT, using either the space_template_id or space_template_name parameter, respectively.

For instance, you might want to create a template named "Party Space Template," and use that for all of the various spaces that you create dynamically. You would start by creating a space manually and naming it "Party Space Template." Then, adjust that manually created space as desired for all future Party Spaces — for example, you might want to adjust the attenuation or roll-off values of a Party Space in order to convey a more festive atmosphere. Once you have created that Party Space Template, make note of its UUID. Then, when you create Steve's Party Space space by name, you can use the template UUID in the JWT:

Info Icon

When specifying a template, you can use either the space_template_id or the space_template_name, but not both. Choose the one that makes the most sense for your application. Bear in mind that if you use space_template_name, the same rules apply regarding unique space names for template spaces as do when creating spaces by name. In other words, if you want to use space_template_name, you should ensure that the names for all your templates are unique.

Please refer to the connection life cycle diagram and the documentation for the HiFiConnectionStates enumeration for more details about the different states that a typical connection will encounter.
Info Icon

HiFiCommunicator sessions will always attempt to fully disconnect if a connection is interrupted. Therefore, a "Failure" state is transitory and you do not need to explicitly tell the HiFiCommunicator to disconnect when you receive this notification. A session that has been disconnected inadvertently will have its state changed to "Failure," but the state will then immediately proceed to "Disconnected." This ensures that all connections are completely disconnected if a failure occurs. If you are implementing custom reconnection logic through the use of state change handlers, we recommend that you do not attempt a new connection until the final "Disconnected" state is reached, to avoid attempting to reconnect a session that is still in the process of disconnecting.

When creating a space by name using the Administrative REST API, you can use a space template by including either the space_template_id or space_template_name parameter as part of that call.

 

5. Removing Old Spaces

When using the functionality to create a space by name, be aware that these spaces do continue to exist once users have disconnected, and the spaces will be listed in the Developer Console. This allows a space to be reused if users come back to your application after disconnecting. However, because these spaces will stick around indefinitely in the Developer Console, you may wish to clean up old spaces that are no longer needed. The best way to do this is by deleting them through the Developer Console or using the space deletion REST API call. Please refer to the "Programmatic Space Management" guide for further details on managing spaces using the Administrative REST API.

 

6. Conclusion

In this guide, you learned how to connect to a space using the name of the space rather than the UUID. You also learned that High Fidelity will create spaces by name automatically if they do not yet exist. Finally, you learned how to use a template to apply common settings to your new spaces.

For detailed technical information about the High Fidelity Spatial Audio Administrative REST API, visit the REST API documentation.

If you have any questions or comments, please contact us via support.