Prophecy

Prophecy adds a complete View it in your room experience to a product page. It can discover the current OV25 configuration automatically, or accept one to four images of any other product.

Installation

Script tag with OV25

One line, with nothing in it:

<iframe
  src="https://configurator.orbital.vision/89-public-key/7218"
></iframe>
 
<script src="https://cdn.jsdelivr.net/npm/@orbital.vision/prophecy@1/dist/prophecy.js"></script>

Prophecy detects the configurator.orbital.vision iframe, reads the organisation, public key and product from its URL, and follows the shopper's selections. You do not pass an organisation ID, key, product ID, product images, configurator selector, or button.

The script does not need to come after the iframe. Prophecy waits for the configurator, so a page that mounts it after hydration, or on a later route of a single-page site, still works. That is true even when the tag has attributes such as data-prophecy-session-endpoint. Include the line once; a second copy will not add a second launcher.

The running instance is available as window.prophecy. Use data-prophecy-configurator only if the page contains multiple configurators.

The dialog carries a small footer reading "Powered by OV25 from Orbital Vision". It is part of the experience and is not configurable.

Placing the launcher

By default Prophecy adds its own button, fixed to the corner of the page. To place it yourself, mark a button in your own markup:

<button type="button" data-prophecy-launcher>See it in your room</button>

Prophecy attaches to the first marked element and follows one that a single-page site mounts and unmounts per route. Once a page has marked a launcher, Prophecy stops offering its own. The button stays hidden until Prophecy has confirmed the shop can generate, so a shopper never sees a control that cannot work.

The widget on the configurator

Prophecy also puts a small control in the top right corner of the configurator itself, so a shopper can add what they are looking at to their room without opening the dialog.

Before they have made anything it is a single pill reading "View this product in your room". After that it becomes a stack of the previews they have made with a plus over the corner. Pressing the plus starts a preview of the current product in the room they last used, without opening anything: the plus becomes a filling ring, then a tick, and the new picture joins the stack. Pressing the stack opens the dialog on their previews.

The plus appears only when the product on screen has no preview yet, and only once the configurator has finished changing to it. Changing the fabric while one is being made offers to make that one too, up to the number of previews your account allows at once.

The widget comes with the script tag. A page that sets data-prophecy-button gets the launcher on that element and no widget:

<iframe src="https://configurator.orbital.vision/89-public-key/7218"></iframe>
 
<script
  src="https://cdn.jsdelivr.net/npm/@orbital.vision/prophecy@1/dist/prophecy.js"
  data-prophecy-button="#see-it-in-your-room"
></script>

From npm, add the widget yourself with one call:

prophecy.mountOverlay();

npm

Use the package when Prophecy is part of your application bundle or you need programmatic control.

npm install @orbital.vision/prophecy

import Prophecy from '@orbital.vision/prophecy';
 
const prophecy = Prophecy.create({
  sessionEndpoint: '/api/orbital/prophecy/session'
});
 
prophecy.mount('#room-preview');

Prophecy.create() does not wait for the configurator. The iframe must already be on the page, or it throws. On a page that mounts the configurator later, create Prophecy after it:

// Runs once the product page, and its configurator iframe, are on screen.
function onProductPageReady() {
  const prophecy = Prophecy.create({
    sessionEndpoint: '/api/orbital/prophecy/session'
  });
 
  prophecy.mount('#room-preview');
  prophecy.mountOverlay();
}

The npm package ships an ES module, an IIFE browser bundle, source maps, and TypeScript declarations. jsDelivr is the recommended browser CDN; npm itself is not a browser asset server.

Non-OV25 products

Pass a stable catalogue reference and one to four JPEG, PNG, or WebP images of the exact same product. Images may be CORS-readable HTTP(S) URLs or browser Blob values, with a maximum of 12 MB per image.

const prophecy = Prophecy.create({
  productReference: 'shopify:variant:SKU-42',
  productImages: [frontUrl, sideUrl, detailBlob],
  productUrl: location.href,
  sessionEndpoint: '/api/orbital/prophecy/session'
});
 
// Replace identity, images and the result URL together during SPA navigation.
prophecy.setProduct({
  reference: 'shopify:variant:SKU-43',
  images: [nextFrontUrl, nextSideUrl],
  url: nextProductUrl
});

For a declarative integration, provide data-prophecy-product-reference, data-prophecy-product-images, data-prophecy-product-url, and data-prophecy-session-endpoint on the script tag.

Who can generate

The organisation chooses one access mode in the dashboard. It decides whether the section below applies to you at all.

In free-trial mode, a shopper who has used their allowance does not get an error. Prophecy tells your page, and you send them to your login:

const prophecy = Prophecy.create({
  sessionEndpoint: '/api/orbital/prophecy/session',
  onSignInRequired({ freeGenerations }) {
    showSignInPrompt(`You have used your ${freeGenerations} free previews.`);
  }
});

Server-side session exchange

The browser calls a same-origin endpoint on your site. That endpoint authenticates the shopper with your normal session, validates the product being viewed, then exchanges your Prophecy server key for a short-lived, product-bound browser session.

Create the key on your API Keys page and pick the Prophecy Server Key type. It only buys previews. The general Private API Key also reads your product list and swatches, which is more than a preview integration should be able to do if the key ever leaks.

export async function POST(request: Request) {
  const account = await requireSignedInAccount(request);
  const input = await request.json();
 
  // Confirm this product is genuinely available on the current page.
  await assertCustomerCanViewProduct(account, input);
 
  const response = await fetch(
    'https://demo.orbital.vision/api/configurator/room-ai/server/session',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.ORBITAL_PROPHECY_SERVER_KEY}`
      },
      body: JSON.stringify({
        productId: input.productId,
        productReference: input.productReference,
        productSource: input.productSource,
        resolution: input.resolution,
        origin: new URL(request.url).origin,
        customerId: account.id
      })
    }
  );
 
  return new Response(response.body, {
    status: response.status,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-store'
    }
  });
}

Your route must:

• accept only authenticated, same-origin JSON POST requests;
• derive customerId from the signed-in account, never from request input;
• validate productId or productReference against the page being viewed;
• keep the Prophecy server key in a server-only environment variable;
• return Orbital's status and session JSON without caching it.

OV25 products use productSource: 'ov25-configurator'. Supplied-image products use productSource: 'external-images' and may have a null productId.

Availability and token balance

Before showing anything, Prophecy asks whether the site may offer previews at all. Orbital checks the public key against the organisation, that the requesting origin is on the authorised domains list, and that Prophecy is switched on.

That check opens no session and uses none of the shopper's allowance. It does not depend on the product, so one cached answer covers your whole catalogue and it is asked once per page. A session begins only when a shopper opens the dialog.

If the answer is no, Prophecy keeps the launcher hidden, emits availability-change and error, and logs the reason to the console instead of showing a broken interface. Localhost uses development behaviour by default: the launcher stays visible and a failed session shows its message inside the dialog, so errors remain visible while integrating.

On localhost, Prophecy still calls the live API. Until that origin is on your authorised domains list, the dialog shows the live API's refusal. To use a staging host instead:

<script
  src="https://cdn.jsdelivr.net/npm/@orbital.vision/prophecy@1/dist/prophecy.js"
  data-prophecy-endpoint="https://staging.example"
></script>

From npm, pass endpoint: 'https://staging.example' to Prophecy.create().

const availability = await prophecy.checkAvailability();
 
if (availability.available) {
  customButton.hidden = false;
}
 
prophecy.on('availability-change', ({ detail }) => {
  customButton.hidden = !detail.available;
});

How long we keep things

The room photo is the sensitive half, and it does not survive generation: it is deleted as soon as the generator reads it, before the preview exists.

Account-owned history

For signed-in customers, keep room photos and generated results in your database and private object storage rather than local storage. Every history route should derive ownership from your signed session instead of accepting an account ID from the browser.

const prophecy = Prophecy.create({
  sessionEndpoint: '/api/orbital/prophecy/session',
  accountKey: signedInAccountVersion,
  history: {
    async load({ signal }) {
      const response = await fetch('/api/orbital/prophecy/history', { signal });
      if (!response.ok) throw new Error('History could not be loaded');
      return response.json(); // { roomPhotos, results }
    },
 
    async saveRoom(photo) {
      const body = new FormData();
      body.append('file', photo.blob, 'room.jpg');
      body.append('width', String(photo.width));
      body.append('height', String(photo.height));
      body.append('aspectRatio', photo.aspectRatio);
 
      const response = await fetch('/api/orbital/prophecy/rooms', {
        method: 'POST',
        body,
        signal: photo.signal
      });
      if (!response.ok) throw new Error('Room photo could not be saved');
      return response.json(); // { id }
    },
 
    async saveResult(result) {
      const response = await fetch('/api/orbital/prophecy/results', {
        method: 'POST',
        keepalive: true,
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(result),
        signal: result.signal
      });
      if (!response.ok) throw new Error('Result could not be saved');
    },
 
    async clear({ signal }) {
      const response = await fetch('/api/orbital/prophecy/history', {
        method: 'DELETE',
        signal
      });
      if (!response.ok) throw new Error('History could not be cleared');
    }
  }
});
 
// Fence cached sessions and in-memory history when authentication changes.
await prophecy.setAccountContext(nextAccountVersion);

Adapters should honour the supplied AbortSignal. Returned room-photo URLs must be same-origin or CORS-enabled. accountKey is only a stable, non-sensitive browser-side change marker; never use an email address, customer ID, access token, or session token.

Verify results before persistence

Do not trust result metadata posted by the browser. Retrieve the job from Orbital with the same private key and customer identity, then persist only the verified server fields.

const verified = await fetch(
  `https://demo.orbital.vision/api/configurator/room-ai/server/jobs/${jobId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ORBITAL_PROPHECY_SERVER_KEY}`,
      'X-Orbital-Customer-Id': account.id
    }
  }
).then((response) => response.json());
 
if (verified.status !== 'COMPLETED' || !verified.resultUrl) {
  throw new Error('Unverified Prophecy result');
}
 
await saveResult({
  orbitalJobId: verified.jobId,
  productId: verified.productId,
  productReference: verified.productReference,
  productSource: verified.productSource,
  selectionString: verified.selectionString,
  sourceUrl: verified.resultUrl
});

Events and hooks

Subscribe with a named option callback, onEvent, prophecy.on(), a wildcard listener, or the bubbling prophecy DOM event emitted from the launcher.

const prophecy = Prophecy.create({
  sessionEndpoint: '/api/orbital/prophecy/session',
  onResult(result) {
    analytics.track('prophecy_generation_complete', result);
  },
  onError(error) {
    errorReporter.capture(error);
  }
});
 
const unsubscribe = prophecy.on('*', (event) => {
  console.log(event.type, event.detail);
});

Order this product

Every preview remembers two things: the configurator's SKU for that exact configuration, and the page it was generated from, query string and all. When a shopper presses Order this product, Prophecy tells your page first.

Call preventDefault() to keep the shopper on the page and take the order yourself. If you do not, they go to the page the preview was made from.

const prophecy = Prophecy.create({
  onOrder(order) {
    order.preventDefault();
    addToBasket(order.sku);
    // order.pageUrl is the page it was made from, query string and all
  }
});

With the script tag, set the hook before the script loads:

<script>
  window.prophecyOptions = {
    onOrder(order) {
      order.preventDefault();
      addToBasket(order.sku);
    }
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@orbital.vision/prophecy@1/dist/prophecy.js"></script>

What order carries:

sku and pageUrl are also on every generation-complete result and every saved preview.

Instance API

Core options

Declarative attributes

Go-live checklist

• Test against the version you ship. The @1 URL follows fixes automatically; pin an exact version only if you want to control updates yourself.
• Keep the Prophecy server key on your server only.
• Ask Orbital Vision to authorise every production origin.
• Confirm Prophecy is switched on and the organisation has enough tokens.
• Test login, logout, account switching, and anonymous-to-account transitions.
• Keep room photos and results in account-owned private storage.
• Verify completed jobs from your server before saving result metadata.
• Exercise the unavailable state so your launcher never exposes a broken feature.

For access, private API keys, authorised origins, or billing setup, contact Orbital Vision.