Install

Load staysignals.js on every page of your site and forward the session ID at checkout.

Add one <script> tag to the <head> of every page. The SDK is designed to observe the full booking flow, so loading it only on checkout leaves most of the useful signal behind.

Script tag

<script
  src="https://cdn.staysignals.com/v1/staysignals.js"
  data-key="pk_<project>_abc123"
></script>

Attributes

Prop

Type

Placement recommendations

Load the tag in <head>, not at the bottom of <body>.
Load it synchronously (no async or defer) so the session starts before the first page interaction.
Load it on every page of your site — landing, search, hotel detail, cart, checkout. Not just checkout.

Sessions

On first page load, the SDK generates a session ID (a UUID) and writes it to three places for redundancy:

localStorage
sessionStorage
a first-party cookie

On subsequent page loads, the SDK reads whichever storage has the session ID and reuses it. You do not call any JavaScript API.

The SDK also observes navigation changes (including SPA URL transitions), viewport changes, and form interactions for the lifetime of the session.

Forward the session ID at checkout

When your checkout form submits, your server needs the session ID to include in POST /v1/risk. Two common patterns:

The SDK writes a first-party cookie named staysignals_sid scoped to your domain. Your server can read it directly from the request's Cookie header.

Read from JavaScript and submit with the form

<form id="checkout" method="POST" action="/checkout">
  <input type="hidden" name="staysignals_session_id" />
  <!-- other fields -->
</form>

<script>
  document.querySelector('input[name="staysignals_session_id"]').value =
    window.staysignals.sessionId;
</script>

window.staysignals.sessionId is available after staysignals.js loads. It's the same UUID stored in the cookie and localStorage.