Overview

sorai-js is the small browser runtime, under 4 KB gzipped, that every Sorai store page loads. It does three things:

1. Opens checkout from any element on the page, carrying the buyer's attribution with it.
2. Records attribution on the buyer's first landing and keeps it for 90 days, so a purchase two visits later still credits the campaign that earned it.
3. Tracks events to Sorai and to the ad and analytics tags you configure: Meta, TikTok, Google Analytics 4 and Google Tag Manager.

It has no framework and no dependencies, and there is nothing to build.

On a Sorai store pageCopy Anchor Link

Every page of a Sorai store already loads sorai-js and calls Sorai.init() with the store's own settings, before the page body. That includes a page you write yourself in HTML. You can use the custom elements in your markup and call window.Sorai from your scripts straight away:

<sorai-buy product-id="0199b0f0-0000-7000-8000-000000000021">Buy now</sorai-buy>
<button id="gift">Buy two</button>

<script>
  document.querySelector("#gift").addEventListener("click", () => {
    Sorai.checkout({ productId: "0199b0f0-0000-7000-8000-000000000021", quantity: 2 });
  });
</script>

Configuring the runtime yourselfCopy Anchor Link

Where nothing calls init() for you, call it once, before anything else and before the body, so the custom elements find it configured when they appear:

<script src="https://js.sorai.ai/v1/sorai.js"></script>
<script>
  Sorai.init({
    storeId: "0199b0f0-0000-7000-8000-000000000001",
    storeSlug: "kopi",
    publicKey: "spk_example",
    apiBase: "https://api.sorai.ai",
    checkoutBase: "https://checkout.sorai.ai",
    currency: "IDR",
    locale: "id-ID",
    pixels: { metaPixelId: "123456", ga4Id: "G-ABC123" },
  });
</script>

init() is synchronous and cheap. It stores the configuration, records attribution, loads whichever pixel scripts you configured and sends a PageView for the page. Every option is listed in the reference.

• currency is the store's default currency (ISO 4217). It picks which price <sorai-price> shows. Without it, the element shows the product's first price.
• locale is the BCP 47 tag prices are formatted in. Without it, the browser's own locale decides.

Loading the runtimeCopy Anchor Link

Load it from https://js.sorai.ai/v1/sorai.js, as a plain blocking script in <head>. Everything under /v1/ stays compatible: new options and fixes ship to the same address, and anything that would break a page gets a new version path instead. Browsers cache it for a few minutes, so a fix reaches your site without a change on your side.

Link to it rather than copying the file, so you get those fixes. Leave out an integrity hash for the same reason: the file changes with each compatible release, and a pinned hash would stop it loading.

The publishable keyCopy Anchor Link

publicKey is a publishable key (spk_...), scoped to one store. It can read that store's public catalogue and start a checkout, nothing else, so it is safe in page source. Create one under Organization, API keys in the Sorai dashboard.

A secret key (ssk_...) must never appear in a page. Anyone who views the source can read it.

Naming the pageCopy Anchor Link

Set window.SORAI_PAGE_ID before the runtime loads to attribute events to a particular page. Sorai store pages set it for you.

<script>
  window.SORAI_PAGE_ID = "0199b0f0-0000-7000-8000-000000000011";
</script>

The value is a page id, or product: followed by a product id for a product's own page. Without it, no PageView is sent and other events carry no page; nothing else changes. Any other value is rejected: the event is answered with 422 invalid_page_id instead of being recorded.

NextCopy Anchor Link

• Opening checkout: the modal, hidden fields and the paid event.
• Custom elements: buy buttons, prices and product links with no JavaScript of your own.
• Events and attribution: what is sent, and how it avoids double counting.
• Reading products: product data and prices in minor units.
• Reference: every method and type.