Ably's Enterprise customers optionally have access to custom environments, dedicated clusters and the capability to restrict all traffic, data and storage to specific regions. Customers using custom environments can benefit from our Active Traffic management service.


Note: We also support custom CNAME domains such as yourcompany.com. Get in touch if you would like to set this up as the setup instructions differ from custom environments.


If you have been assigned a custom environment and/or set of custom fallback hosts, you must followz these steps when configuring your client library SDKs:


1. Get your environment set up with the help of Ably


Please speak with your customer success manager about configuring your custom environment.  A custom environments will have one or more of the following provided by the Ably platform


Your customer success manager will provide you with one or more of the following ClientOptions (constructor options) that must be used in all your Ably client library SDKs:

  • environment
  • fallbackHostsUseDefault (optional)
  • fallbackHosts (optional)


Once you have been provided with a custom environment, you can test this is working by visiting the following URLs (replace [ENVIRONMENT] with your supplied environment):


You can do the same with any fallback hosts you are provided.


You are now ready to set up your clients.  However, please bear in mind:

  • If you have regional constraints for your account (see links above), Ably will not yet have this enabled.  This is to ensure that any traffic arriving in an incorrect region due to clients not being configured correctly is not yet rejected. One you confirm all clients are configured with the correct environment and fallbacks, the regional constraints will be added and enforced.


2. Modify your client library SDKs to use the correct environment settings


The ClientOptions provided to you by your customer success manager must be used in all of your client library SDKs. Here is an example of a Javascript client initialized with a custom environment and set of fallback hosts:


var ably = new Ably.Realtime({
  authUrl: '/get-token', /* your token callback code, authUrl, or key */
  environment: 'environment-example',
  fallbackHosts: [
     'environment-example-a-fallback.ably-realtime.com',
     'environment-example-b-fallback.ably-realtime.com'
  ]
});


Whilst this is a Javascript example, all client SDKs offer the same options and should be identical apart from the language syntax and style.


You can see this in a browser at https://jsbin.ably.io/etadus/2/edit.


3. Test your setup


We recommend you test all client SDKs can connect, publish and receive messages (where applicable) before rolling these changes out.  Additionally, where possible, please inspect your client SDK traffic to ensure it is embedding the environment setting in the endpoint i.e. instead of connections to realtime.ably.io you should see [ENVIRONMENT]-realtime.ably.io now.


4. Confirm you are read and Ably can roll this into production


Once all your client library SDKs are using the new environment and traffic is arriving at our default endpoints, the team at Ably will be able to actively reroute your traffic based on the environment settings.


If you have regional constraints on your account, then please contact your customer success manager who will ensure the regional constraints are applied and tested too.