Self-hosting the Userpilot SDK

The Userpilot SDK is the Javascript that runs in your web application and allows us to trigger Userpilot content, capture user feedback and collect analytical insights. 

Typically, we recommend loading the Userpilot SDK directly from our Content Delivery Network (CDN) to ensure that you're using the most current version. You can find more about our standard installation in this article

Due to certain security or compliance restrictions, you might opt to self-host Userpilot's SDK locally. This ensures locking the SDK to a certain version – this makes updating it completely dependent on your organization.


Standard Installation Self-Host Setup
Received automated product updates and feature enhancements Requires updating the SDK to the latest recent version to receive updates
One time setup Requires additional engineering time and effort

Technical Overview

Userpilot SDK is comprised of two main components, the shim, and the app. The shim is a wrapper of our SDK and is used to speed up the loading of the SDK as well as to buffer up operations being called on it before it's fully loaded.

Self-Hosting Setup

There are multiple options for setup depending on the purpose of self-hosting the script as described below.

A. If the SDK is intended to be self-hosted in order to ensure locking the version, then it is preferred to simply use the version option while initializing the SDK and passing an exact version to use. This defaults to the latest version we have but it can be overridden to pull a specific version.

B. If the SDK is intended to be self-hosted for compliance reasons then one of the following steps is required:

  • The latest app component of the SDK must be downloaded from our CDNs and then hosted by the customer.
    • This can be done by following the link
    • The version v0 is the latest app component version, which is updated periodically to reflect the latest SDK version (0.817 as of the writing of this article).
    • Make note of the new uploaded location of the app.js file as this is required in the next steps.
  • The shim component of the SDK must be downloaded from our CDNs and then hosted by the customer.
  • Finally passing the version option

C. If the SDK is intended to be self-hosted only in order to avoid passing end-users IPs to Userpilot related services, then the previous steps used described to full self-host the SDK would be sufficient, but a simpler way would be to simply proxy Userpilot's SDK CDN, this is similar to the steps used to proxy Userpilot's APIs

If you have questions about the basics of flows, please reach out to us at

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.