Skip to main content

Self-hosting CommandBar

We like to get philosophical here at CommandBar. Before talking about how to self-host CommandBar, let’s talk about what self-hosting actually means.

There are 3 components to installing CommandBar inside an application:

  • Library: the code that CommandBar needs to run
  • Config: the specification of a customer’s experiences. Command names, nudge titles, etc.
  • Analytics: where analytics events should be sent.

There is a self-hosting option for each component.

Library​

The CommandBar library refers to the code needed to run CommandBar’s experiences for end users on the client side.

There are two options for hosting the CommandBar library:

  • [Default] Cloud-hosted: using this option, the latest version of CommandBar (which we thoroughly test and QA before deploying to our customers) will be delivered to the client-side on page load, distributed via CommandBar’s CDN for fast load times.
    • This method ensures you and your users receive our latest updates and features.
    • Note: this method requires an API request to the CommandBar API. This request can be proxied behind your company’s API so that requests to https://api.commandbar.com will be hidden from your client-side.
    • We have an impressive availability record, which you can see here.
  • Bundled: when we ship updates to our product, we also publish those updates to a JavaScript Library (here). Enterprise customers can optionally use this library instead of our cloud-hosted library.
    • This means that no API request is required to load CommandBar, making this approach suitable for airgapped environments.
    • This requires customer engineers to upgrade the CommandBar library manually to ensure access to new features.

Config​

The CommandBar config refers to the experiences customers create with CommandBar.

There are three options for hosting the CommandBar config:

  • [Default] Cloud-hosted: using this option, configuration changes will be hosted on CommandBar servers and deployed to the client at run-time. This facilitates a no-code deploy experience. A change can be made to your config and immediately made available to customers.
    • Note: this method requires an API request to the CommandBar API. This request can be proxied behind your company’s API so that requests to https://api.commandbar.com will be hidden from your client-side.
  • Customer-hosted: a customer can export their CommandBar config as a .json file and host that file in a static server controlled by the company. This approach eliminates a dependency on the CommandBar API, but requires someone at the customer to manually update the config file when changes wish to be made.
    • Note: when this method is used, certain targeting rules which rely on access to the CommandBar API will be unavailable.
  • Customer-bundled: a customer can export their CommandBar config as a .json file and bundle it along with the CommandBar library into their production code. This eliminates any need for an API request to load the config, and is suitable for airgapped environments.

Analytics​

Analytics refers to the destination for events generated from end-user usage of CommandBar, like nudge clicks and command usage

There are three options for CommandBar’s analytics destination, and they are not mutually exclusive.

  • [Default] Store with CommandBar: using this approach, analytics events are stored on a CommandBar database keyed using the anonymous user id provided to CommandBar.boot in the customer’s install script. This method gives customer immediate access to analytics dashboards at https://app.commandbar.com.
  • Analytics integrations: CommandBar has integrations with many analytics providers, including Amplitude, Segment, and Heap. Turning on these integrations sends CommandBar-generated events to these destinations. Note that these integrations are proxied by the CommandBar API, and require an API request (which can optionally be proxied through a customer’s API).
  • Custom destination: Customers can choose a custom destination for analytics events and route those events to that destination on the client-side using CommandBar.addEventSubscriber. You can read more about this SDK method here.

In addition, it is possible to turn off analytics completely. This approach is not recommended (because it hampers customers’ ability to iterate on and learn from engagement with CommandBar experiences). However, this may be most suitable for airgap environments.