# Connect your custom website

> Add the Releva JavaScript SDK to a shop on your own stack, send the page context on every page, call the catalog and order APIs from your server, and check in the Releva admin that page views, visitors and products arrive.

A shop on a custom stack connects to Releva in two places. In the browser, the Releva JavaScript SDK sends one `Releva.push()` call per page with what the visitor is looking at, and renders the product blocks, banners and stories Releva answers with. On your server, a few HTTP calls keep Releva’s copy of your catalog current and report paid orders. This page covers the whole setup and the check at the end. The full list of SDK options, context fields and cookies is in the [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/).

If you run Shopify, WooCommerce, Magento, PrestaShop, OpenCart, CS-Cart, CloudCart or Gombashop, install Releva’s app or plugin for your platform instead. It loads the same SDK for you, and adding the snippet a second time double-counts every visit.

## Before you start

* Your shop exists in Releva with **Platform** set to **Other / Custom**. The platform is chosen when the shop is created and is read-only on **Settings › Shop & Integration › General**. A custom shop gets the default catalog sync URL `{shopUrl}/api/releva/products` (change it under **Catalog Sync**) and no sync schedule.
* You can edit the HTML of every page of your storefront, or the template that renders it.
* Your storefront runs on HTTPS. The SDK’s cookies are marked `Secure` on HTTPS pages, and Releva rejects plain HTTP requests from your server.
* You have a Releva page for each page type you want to personalize (home, category, product, search, cart). The token of each page goes into the snippet. See [How product blocks work](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/#pages-and-tokens).
* Your product ids are stable and the same everywhere: in the catalog you send to Releva, in `product.id` on product pages and in `cart.products[].id`. That is what ties browsing behaviour to the catalog.

The minimum that makes Releva useful is four things: the base `Releva.push()` call on every page, `product.id` on product pages, products sent to the [catalog API](https://releva.ai/documentation/reference/catalog/overview/), and paid orders sent to the [orders API](https://releva.ai/documentation/reference/orders/overview/). Everything else on this page improves results but is not needed to go live.

## Install

Add the SDK to every page of your storefront, near the end of `<body>`. The script tag loads the SDK asynchronously; the `onload` attribute dispatches `relevaSdkLoaded`, and your code calls `Releva.push()` once that event fires. Any other way of making sure `Releva.push` runs after the script has loaded is fine too.

```plaintext
<script>
  document.addEventListener('relevaSdkLoaded', function () {
    Releva.push('<yourAccessToken>', {
      cart: {
        products: [
          { id: 'DEMO-1001', price: 39.9, currency: 'EUR', quantity: 1 }
        ]
      },
      profile: { id: 'CUST-1001' }
    }, function (results) {
      // Personalized content the SDK did not render itself.
    }, function (error) {
      console.error(error);
    });
  });
</script>
<script async type="text/javascript"
        src="https://releva.ai/sdk/v0/js/releva-sdk-js.min.js"
        onload="document.dispatchEvent(new Event('relevaSdkLoaded'));"></script>
```

What to know about the script:

* There is one URL and no version pinning. Releva publishes new SDK versions to the same path with a one-hour cache, so every shop runs the current version within about an hour of a release. `Releva.version()` in the browser console prints the version your page loaded.
* The bundle exposes one global, `Releva`. It is compiled for browsers with more than 0.5% usage share; there is no documented minimum browser version.
* Send `cart` on every page, with `products: []` when the cart is empty. `price` and `quantity` are required numbers on every cart line; a price sent as a string (`"39.90"`) is rejected.
* Send `profile` only when you know who the visitor is. Anonymous visitors are tracked under a device id that the SDK keeps in a cookie, and their history is merged into the profile when they log in and your push sends `profile.id` or `profile.email`.
* Single-page application: call `Releva.push()` again on every route change and pass `{ clearRelevaElements: true }` as the fifth argument so the previous page’s blocks are removed first.

## Configure

Nothing is configured in Releva for the SDK itself. You copy two kinds of values out of the admin and put them in your snippet.

### 1. Copy your Access Token

Open **Settings › Shop & Integration**. On the **General** tab, copy **Access Token** with the copy icon next to the field. It is the first argument of `Releva.push()`. It is public by design and ships in your page source. Guide: [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

The **Secret Key** below it is for your server only: it authenticates the catalog, order and profile calls as `authorization: Bearer <secretKey>`. Never put it in front-end code. Both keys are UUIDs, so the format does not tell them apart; a push with the secret key answers `400` with `Domain with the provided access token cannot be found.`

### 2. Copy one page token per page type

Open **Personalization › Product Blocks** and pick a page in the page list. Its token is shown as **Token:** at the top, with a copy icon. Send that token as `page.token` on every URL of that page type: the product page’s token on every product URL, the category page’s token on every category URL, and so on. If a page type has no Releva page yet, create one with **New Page**.

A page token is optional. Open **Page Settings** (the settings icon next to the token) and set **URL Path** to the pathname of the page, without the trailing slash, and Releva matches a push that carries no token by the pathname of the page URL instead. That works for pages with a fixed path, such as a home page or a landing page, not for a page type with many URLs.

### 3. Add the page-specific fields

The same `Releva.push()` call takes a few extra fields depending on the page type. The field-by-field reference is in [the JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/#the-context-object).

| Page type                | Add to the context                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Every page               | `cart`, and `profile` when the visitor is known (`wishlist` if you have one)                                                   |
| Product page             | `page.token`, `product.id`                                                                                                     |
| Category or listing page | `page.token`, `page.ids` (the product ids shown), `page.categories`, optionally `page.filter`                                  |
| Search results           | `page.token`, `page.query`, `page.ids`, optionally `page.filter`                                                               |
| Cart page                | `page.token` of your cart page, and `cart.products` with every line in the cart                                                |
| Checkout success         | `cart.cartPaid: true`, `cart.orderId`, `cart.products` as the lines of the order, and `profile.email` or `profile.phoneNumber` |

Product page:

```plaintext
{
  "cart": { "products": [] },
  "page": { "token": "<yourProductPageToken>", "locale": "en", "categories": ["women/shirts"] },
  "product": { "id": "DEMO-1001" }
}
```

Category or listing page:

```plaintext
{
  "cart": { "products": [] },
  "page": {
    "token": "<yourCategoryPageToken>",
    "locale": "en",
    "categories": ["women/shirts"],
    "ids": ["DEMO-1001", "DEMO-1002", "DEMO-1003"],
    "filter": {
      "operator": "and",
      "nested": [
        { "key": "price", "operator": "gte,lte", "value": "10,50", "action": "include" },
        { "key": "custom.string.size", "operator": "eq", "value": "M", "action": "include" }
      ]
    }
  }
}
```

`page.ids` lists the products shown on the page. Send `page.filter` only when the visitor applied filters; the syntax is in [Filter syntax](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/#filter-syntax).

Search results:

```plaintext
{
  "cart": { "products": [] },
  "page": { "token": "<yourSearchPageToken>", "query": "linen shirt", "ids": ["DEMO-1001", "DEMO-1002"] }
}
```

Cart page:

```plaintext
{
  "cart": {
    "products": [
      { "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 },
      { "id": "DEMO-1002", "variantId": "DEMO-1002-M", "price": 24.5, "currency": "EUR", "quantity": 2 }
    ]
  },
  "page": { "token": "<yourCartPageToken>", "locale": "en", "currency": "EUR" }
}
```

The cart page has its own page in **Personalization › Product Blocks**, so its token is not the product or home page token. Copy it from that page. The token makes the push count as a **Viewed Page** on the cart page and returns the product blocks you set up on the cart page. The cart lines are the same lines you send on every other page. When the visitor changes a quantity or removes a line on the cart page without a page reload, call `Releva.push()` again with the new `cart.products`, so Releva records the change.

Logged-in visitor, on any page:

```plaintext
{
  "cart": { "products": [] },
  "page": { "token": "<yourHomePageToken>", "locale": "en" },
  "profile": {
    "id": "CUST-1001",
    "email": "maria@example.com",
    "firstName": "Maria",
    "addCustom": {
      "string": [{ "key": "preferredStore", "values": ["sofia-center"] }]
    }
  }
}
```

Use `addCustom`, not `custom`, for profile custom fields in the push. `custom` replaces all custom fields of the profile. If your server sets other custom fields through the [profiles API](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/), such as `loyaltyTier`, a push with `custom` deletes them. `addCustom` changes only the keys it names and keeps the others. The push does not accept tags: `addTags` in `profile` answers `400` with a forbidden-key error. Set tags from your server with `addTags` and `removeTags` in the profiles API.

Checkout success:

```plaintext
{
  "cart": {
    "cartPaid": true,
    "orderId": "DEMO-ORDER-1001",
    "products": [{ "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 }]
  },
  "profile": { "email": "maria@example.com" }
}
```

The checkout push is a fallback, not the record of the sale. Releva holds it for 90 seconds so that the order your server reports with the orders API wins the deduplication on `orderId`. Without `cartPaid` the push only records a cart change; without `orderId` the order cannot be deduplicated against the one your server reports, so always send both.

`cart.orderId` must be exactly the same string your server sends as `orderId` to `POST /api/v0/carts`. Releva treats a different id as a second order and counts the revenue twice. Send it as a string (`"100012345"`, not `100012345`): a numeric `orderId` fails validation and the push answers `400`.

### 4. Pass your consent state

If data protection law applies to your shop, pass a `hasConsent` function in the options (the fifth argument). The SDK calls it on every push and sends `profile.consent` as `cookiesPolicy` when it returns `true` and `mandatoryCookies` otherwise.

```plaintext
Releva.push('<yourAccessToken>', context,
  function (results) {},
  function (error) { console.error(error); },
  {
    hasConsent: function () {
      return Releva.getCookie('cookielaw') === '1'; // your consent banner's cookie
    }
  });
```

`hasConsent` only labels the profile. It does not stop the SDK from setting its cookies or from sending the push, and Releva still records the visit. If visitors must not be tracked before they consent, do not load the SDK, or do not call `Releva.push()`, until your consent banner says yes.

### 5. Connect your server

These calls run on your server with the **Secret Key** and keep Releva’s data complete. Each answers `202` with an empty body when accepted.

| Call                                                                                                                                            | When                                                                                                                                                               | Needed?                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/)                                                        | Whenever a product changes: price, stock, name, custom fields                                                                                                      | Required                         |
| [Report paid orders](https://releva.ai/documentation/reference/orders/report-paid-orders/)                                                                       | When an order is paid                                                                                                                                              | Required                         |
| [The catalog pull-sync endpoint you build](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/)                                      | An endpoint on your side that Releva calls on a schedule to walk the whole catalog. Set its URL and a schedule on **Settings › Shop & Integration › Catalog Sync** | Strongly recommended             |
| [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/)                                                                               | When an order is refunded                                                                                                                                          | If you take refunds              |
| [Delete a product](https://releva.ai/documentation/reference/catalog/delete-a-product/)                                                                          | When a product is gone for good. For out of stock, send `available: false` instead                                                                                 | Optional                         |
| [Record a registration](https://releva.ai/documentation/reference/profiles/overview/#record-a-registration)                                                      | When a customer creates an account                                                                                                                                 | Optional                         |
| [Subscribe](https://releva.ai/documentation/reference/consent/subscribe-a-customer/) and [unsubscribe](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/) | When a customer opts in or out of marketing messages. For a sign-up form on the storefront, `Releva.requestSubscribe()` in the SDK is simpler                      | If you send messages with Releva |

Guide for the pull sync: [Schedule a full catalog sync](https://releva.ai/documentation/guides/shop-settings/schedule-a-catalog-sync/).

### 6. Web push (optional)

To send web push notifications, host the SDK’s service worker on your own origin and pass its URL as `serviceWorkerUrl` in the options. Download `https://releva.ai/sdk/v0/js/service-worker.min.js` and serve it from the root of your site. After each successful push the SDK asks the visitor for notification permission if they have not decided yet, registers the worker and sends the subscription to Releva.

```plaintext
Releva.push('<yourAccessToken>', context,
  function (results) {},
  function (error) { console.error(error); },
  { serviceWorkerUrl: '/service-worker.min.js' });
```

The worker shows a notification only for payloads that come from Releva and opens the notification’s link on click. Guide: [Create a web push notification](https://releva.ai/documentation/guides/push-notifications/create-a-web-push-notification/).

## Verify

In the browser, open a page of your shop with DevTools on the **Network** tab, filtered to `push`. One `POST` to `https://releva.ai/api/v0/push/<yourAccessToken>` with status `200` per page means the snippet runs and the token is right. The request body is a base64 form field, not readable JSON; to see the context the SDK sent, open the page with `?rlv_mode=debug` in the URL, and the SDK logs every request to the console for the rest of the tab session.

Then check in the Releva admin that the pushes were stored. The screens are the same for every integration, so follow [Check that your store data arrives](https://releva.ai/documentation/integrations/check-that-your-store-data-arrives/): **Data Platform › Events** filtered by **Viewed Page** and **Viewed Product**, then **Data Platform › Products** and **Data Platform › Profiles**. In **Raw Data**, **url** and **pageToken** are the page URL and page token from your push.

Three things are specific to a custom integration:

* A visitor who is not logged in is listed under their device id, so select **Include Anonymous Profiles** on **Data Platform › Profiles** to see them. They become named profiles when your push sends **profile.id** or an email address.
* Every **product.id** and **cart.products\[].id** your pushes send must match an **Id** on **Data Platform › Products**.
* A product you send with the catalog API usually appears in that list within about ten seconds. A test order appears in your analytics about a minute after the orders call.

## Troubleshooting

**The push answers `400` with `Domain with the provided access token cannot be found.`** The first argument is not your shop’s **Access Token**. Usually it is the **Secret Key** or a token copied from another shop. `The access token you provided is invalid.` means the value is not a UUID at all.

**The push answers `400` with `The object '...' contains forbidden keys: '...'`.** The context is validated strictly. Remove the named key: the message names the object (`page`, `events[0]`, `cart.products[0]`) and the key. Likewise, `The 'cart.products[0].price' field must be a number.` means a price or quantity was sent as a string.

**The push answers `200`, but there is no Viewed Page event.** A page view is stored only when the push resolves to a Releva page, by `page.token` or by the **URL Path** of a page. A push with neither still records product views, cart changes, searches and custom events, but no **Viewed Page** row and no product blocks. Check that the token is a page token from **Personalization › Product Blocks**, not the access token, and that it belongs to this shop.

**Viewed Page rows arrive but product blocks do not render.** The page’s blocks are switched off, out of schedule, or limited to a segment the visitor is not in. Open the page with `?rlv_mode=debug` to see blocks that are off or scheduled, and read [Why a block is not shown](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/#why-a-block-is-not-shown).

**The push answers `402`.** `Domain is disabled. Please reach out to support@releva.ai to enable it.` means the shop is switched off. `Value delivery is paused for this domain because usage exceeded the plan limit.` means the shop is over its plan; until it is lifted, the push route answers `402` and no browser events are recorded either.

**A profile named `undefined` appears under Profiles.** Your snippet sent `profile.id` as the string `"undefined"` for a visitor who is not logged in. Omit `profile` or `profile.id` instead of passing an empty variable.

**Every visit creates a new anonymous profile.** The device id lives in the `rlv_p` cookie. A consent tool or a cookie-cleaning script that deletes `rlv_*` cookies resets the visitor. The cookies are first-party, `path=/` and `SameSite=Lax`; on a plain HTTP page they are set without `Secure`.

**Your custom events do not reach the callback, and blocks stop rendering on that page.** When your shop has a Google Tag Manager container connected under **Settings › Google**, the SDK pushes every custom event to the `dataLayer` and reads all three `custom` lists of the event without checking that they exist. Send `custom` with `string`, `numeric` and `date` arrays, even empty ones.

**Visitors are asked for notification permission on every page.** With `serviceWorkerUrl` set, the SDK calls `Notification.requestPermission()` after each push while the permission is undecided. Pass `serviceWorkerUrl` only on pages where you want the prompt, or only after a visitor interaction.

## What syncs

| Data                                                                               | Direction                     | Endpoint                                                                                      | When                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page views, product views, cart changes, wishlist changes, searches, custom events | Storefront (SDK)              | `POST /api/v0/push/{accessToken}`                                                             | On every `Releva.push()`. A Viewed Page event needs a resolved page; a Viewed Product event needs `product.id`; cart and wishlist events are recorded when their contents changed since the last push; a Search event needs `page.query` or a filter; one custom event per item in `events[]`. The response carries the product blocks, banners and stories for the page. |
| Visitor profiles                                                                   | Storefront (SDK)              | same push                                                                                     | The profile is created or updated from `profile.*` on the first push of a device and whenever the profile fields change. Anonymous visitors are keyed by device id; the SDK sends `profile.consent` on every push.                                                                                                                                                        |
| Paid orders (fallback)                                                             | Storefront (SDK)              | same push, with `cart.cartPaid` and `cart.orderId`                                            | Queued 90 seconds after the push so the server-side order wins the deduplication.                                                                                                                                                                                                                                                                                         |
| Block and banner impressions                                                       | Storefront (SDK)              | `POST /api/v0/impressions/{accessToken}`                                                      | When a rendered block or banner becomes visible, once per block per page load.                                                                                                                                                                                                                                                                                            |
| Page engagement, banner clicks, story interactions                                 | Storefront (SDK)              | `POST /api/v0/push/events/{accessToken}`                                                      | When the visitor leaves the page or hides the tab (scroll depth and active time), and on banner and story interactions.                                                                                                                                                                                                                                                   |
| Web push subscriptions                                                             | Storefront (SDK)              | `POST /api/v0/pushSubscriptions/{accessToken}`                                                | After a push, when `serviceWorkerUrl` is set and the visitor granted permission.                                                                                                                                                                                                                                                                                          |
| Storefront newsletter sign-up                                                      | Storefront (SDK)              | `POST /api/v0/subscribe/request`                                                              | When your code calls `Releva.requestSubscribe()`. What happens next depends on **Subscription Request Behavaior** in **Settings › Messaging**.                                                                                                                                                                                                                            |
| Products                                                                           | Your server                   | `POST /api/v0/products`, `POST /api/v0/products/availability`, `DELETE /api/v0/products/{id}` | Whenever a product changes.                                                                                                                                                                                                                                                                                                                                               |
| Products (full catalog)                                                            | Releva pulls from your server | `GET <your sync URL>?page=&cursor=` with `authorization: Bearer <secretKey>`                  | On **Sync Now**, and on the **Catalog Sync Schedule** once you set one. About two minutes after a complete pass, products the pass did not return are deleted.                                                                                                                                                                                                            |
| Orders and refunds                                                                 | Your server                   | `POST /api/v0/carts`, refunds endpoint                                                        | When an order is paid or refunded. The record of the sale.                                                                                                                                                                                                                                                                                                                |
| Registrations, marketing consent                                                   | Your server                   | `POST /api/v0/register`, `POST /api/v0/subscribe`, `POST /api/v0/unsubscribe`                 | On account creation and on opt-in or opt-out.                                                                                                                                                                                                                                                                                                                             |

Releva calls your server only for the catalog pull sync and, if you set them up, the [subscriber sync](https://releva.ai/documentation/reference/profiles/build-the-subscriber-sync-endpoint/) and [webhooks](https://releva.ai/documentation/reference/webhooks/overview/). A catalog pull runs only when you select **Sync Now** or on a **Catalog Sync Schedule** you set.

## Next steps

* [Check that your store data arrives](https://releva.ai/documentation/integrations/check-that-your-store-data-arrives/): Confirm that events, products and customers reach Releva.
* [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/): See every option and context field the SDK accepts.
* [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/): Copy the two keys that identify your shop.
* [How Releva connects to your shop](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/): Learn what the tracking snippet does and how the catalog sync works.