Skip to content
Documentation
Open app

Prophecy

Install Orbital Vision's embeddable room-visualisation SDK for OV25 configurators or any product catalogue.

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.

Version

These examples load @orbital.vision/prophecy@1, the major version. Fixes and new features reach your site without you editing anything, and a breaking change would be a deliberate move to @2. If you would rather freeze one exact build, pin the full version instead and update it yourself.

Installation

Script tag with OV25

One line, with nothing in it:

product-page.html
<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:

product-page.html
<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:

product-page.html
<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:

room-preview.ts
prophecy.mountOverlay();

npm

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

npm install @orbital.vision/prophecy
room-preview.ts
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:

room-preview.ts
// 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.

external-product.ts
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.

ModeWho can generateWhat your site needs
AnyoneAny shopper on an authorised domainThe script tag
A few free, then sign inAnyone, up to a daily allowance per browser, then signed-in customersThe script tag and the session endpoint below
Signed-in customers onlyOnly customers your server has identifiedThe session endpoint below

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:

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

The free allowance is a prompt, not a limit

It is counted against a marker Prophecy keeps in the browser, so a shopper who clears their browser data starts again. Its job is to move people towards signing in. Spending is capped by the organisation's daily limits and token balance, which are enforced on our servers.

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.

Keep the server key on the server

Never expose ORBITAL_PROPHECY_SERVER_KEY in HTML, JavaScript, a public environment variable, or Prophecy options. Orbital derives organizationId from the key and returns it in the short-lived 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.

app/api/orbital/prophecy/session/route.ts
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:

product-page.html
<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().

custom-button.ts
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

WhatKept for
The room photo a shopper uploadsDeleted the moment the preview is generated
A room photo uploaded but never usedUnder a day
The generated preview30 days from generation

Copy a preview you need to keep

The 30 days is a download window, not storage. It does not extend because you saved your own copy, so a URL of ours linked from your records will stop working after 30 days. Copy the file into your own storage when you save the result.

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.

DataRecommended fieldsStorage rule
Room photosID, private object key, dimensions, created timeReturn short-lived same-origin or CORS URLs
ResultsOrbital job ID, product identity, selection, result keyVerify the job server-side before saving
OwnershipYour internal customer IDAlways derive it from the signed session
history-adapter.ts
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.

verify-result.ts
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.

analytics.ts
const prophecy = Prophecy.create({
  sessionEndpoint: '/api/orbital/prophecy/session',
  onResult(result) {
    // Forward only the metadata your analytics needs.
    analytics.track('prophecy_generation_complete', {
      product_reference: result.productReference
    });
  },
  onError(error) {
    errorReporter.capture(error);
  }
});
 
const unsubscribe = prophecy.on('*', (event) => {
  console.log(event.type, event.detail);
});
EventOption callbackWhen it fires
readyonReadyInitialisation completes
availability-changeonAvailabilityChangePreflight availability changes
sign-in-requiredonSignInRequiredA shopper has used their free allowance and needs to sign in
orderonOrderThe shopper pressed Order this product
open / closeonOpen / onCloseDialog visibility changes
view-changeonViewChangeUpload, library, phone, preview, generating, or result view changes
product-changeonProductChangeProduct identity or source changes
account-changeonAccountChangeAccount context is replaced
selection-changeonSelectionChangeOV25 configuration selections change
photo-selected / photo-clearedonPhotoSelected / onPhotoClearedThe active room photo changes
phone-handoff-startonPhoneHandoffStartPhone capture handoff begins
phone-photo-receivedonPhonePhotoReceivedA phone photo reaches the desktop
generation-startonGenerationStartA generation request starts
generation-progressonGenerationProgressPolling returns generation progress
generation-completeonResultA browser result is ready
generation-erroronGenerationErrorGeneration fails or times out
history-load / history-saveonHistoryLoad / onHistorySaveAccount history reads or writes
history-erroronHistoryErrorA history adapter operation fails
erroronErrorAny integration or runtime error
destroyedonDestroyThe instance is permanently removed

Google Analytics and Google Tag Manager

Send Prophecy interactions into your own Google Analytics 4 (GA4) property to measure usage, generation outcomes and subsequent purchases. Prophecy exposes the events; it does not load Google Analytics or forward them automatically.

Shopper uses Prophecy → event listener → your dataLayer → GTM → your GA4 property

You need an existing GA4 web data stream, Google Tag Manager (GTM) on your website, and permission to edit both. Keep your existing Google tag and consent configuration. You do not give Orbital your GA4 measurement ID.

These examples use the public API in Prophecy 1.2.2. If you pin an older version, check that it supports the hooks you use. Choose one installation method below. Installing both sends duplicate events.

Events to track

Prophecy eventGA4 eventMeaning
openprophecy_openThe dialog opens
photo-selectedprophecy_photo_selectedThe active room photo is selected; this is not necessarily a new upload
phone-handoff-startprophecy_phone_handoff_startThe shopper starts the phone-photo flow
phone-photo-receivedprophecy_phone_photo_receivedA phone photo reaches the desktop
generation-startprophecy_generation_startA generation request starts
generation-completeprophecy_generation_completeA generated preview is ready in the browser
generation-errorprophecy_generation_errorGeneration fails or times out
sign-in-requiredprophecy_sign_in_requiredThe shopper must sign in to continue
orderprophecy_order_clickThe shopper presses Order this product

An order click is not a confirmed basket addition or purchase. Keep your existing add_to_cart and purchase events on the website's basket and checkout. Do not send generation-progress polling events to GA4.

Step 1: Connect a script-tag installation

Place this code before your existing Prophecy script, after any other code that sets window.prophecyOptions. Keep your existing script attributes, such as your session endpoint. Do not add a second Prophecy script.

The example preserves existing options and callbacks. It forwards only the event name and catalogue reference, not the full event payload.

product-page.html
<script>
(function () {
  if (window.__prophecyGtmInstalled) return;
  window.__prophecyGtmInstalled = true;
 
  var events = {
    'open': 'prophecy_open',
    'photo-selected': 'prophecy_photo_selected',
    'phone-handoff-start': 'prophecy_phone_handoff_start',
    'phone-photo-received': 'prophecy_phone_photo_received',
    'generation-start': 'prophecy_generation_start',
    'generation-complete': 'prophecy_generation_complete',
    'generation-error': 'prophecy_generation_error',
    'sign-in-required': 'prophecy_sign_in_required',
    'order': 'prophecy_order_click'
  };
 
  var options = window.prophecyOptions || {};
  var previousOnEvent = options.onEvent;
 
  window.prophecyOptions = Object.assign({}, options, {
    onEvent: function (event) {
      if (Object.prototype.hasOwnProperty.call(events, event.type)) {
        window.dataLayer = window.dataLayer || [];
        window.dataLayer.push({
          event: 'prophecy_event',
          prophecy_event_name: events[event.type],
          prophecy_product_reference: event.productReference || ''
        });
      }
 
      if (typeof previousOnEvent === 'function') {
        return previousOnEvent.call(this, event);
      }
    }
  });
})();
</script>
<!-- Keep your existing Prophecy script and its attributes here. -->
<script src="https://cdn.jsdelivr.net/npm/@orbital.vision/prophecy@1/dist/prophecy.js"></script>

For a single-page application, install this once in the shared page shell before Prophecy initialises. Changing window.prophecyOptions after the instance exists does not attach a listener to that instance; use prophecy.on() below instead.

Alternative: Connect an npm or existing-instance installation

Add this listener immediately after creating your existing Prophecy instance. Do not create another instance for analytics. For a script-tag instance that has already initialised, use window.prophecy.on() instead.

prophecy-analytics.js
const trackedEvents = new Set([
  'open',
  'photo-selected',
  'phone-handoff-start',
  'phone-photo-received',
  'generation-start',
  'generation-complete',
  'generation-error',
  'sign-in-required',
  'order'
]);
 
const unsubscribeAnalytics = prophecy.on('*', (event) => {
  if (!trackedEvents.has(event.type)) return;
 
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'prophecy_event',
    prophecy_event_name: event.type === 'order'
      ? 'prophecy_order_click'
      : `prophecy_${event.type.replace(/-/g, '_')}`,
    prophecy_product_reference: event.productReference || ''
  });
});
 
// Call unsubscribeAnalytics() when your integration tears down,
// before attaching another listener to the same instance.

Step 2: Configure GTM

  1. In Variables, create a Data Layer Variable named DLV - prophecy_event_name. Set Data Layer Variable Name to prophecy_event_name and use version 2.
  2. Create another named DLV - prophecy_product_reference, with Data Layer Variable Name set to prophecy_product_reference.
  3. In Triggers, create a Custom Event trigger with Event name set to prophecy_event. Use an exact match.
  4. In Tags, create a Google Analytics: GA4 Event tag. Set Measurement ID to your existing GA4 web stream's G-... ID.
  5. Set Event Name to {{DLV - prophecy_event_name}}.
  6. Add an event parameter named prophecy_product_reference, with value {{DLV - prophecy_product_reference}}.
  7. Attach the prophecy_event trigger. Apply the same consent requirements as your other analytics tags.
  8. Save and test in Preview before publishing the container.

One tag handles all the listed events. Pushing an object into dataLayer alone does not send it to GA4; the trigger and tag complete the connection. See Google's data layer guide and GA4 event setup.

Step 3: Make product details available in reports

In GA4, open Admin → Custom definitions → Create custom dimension. Name it Prophecy product reference, choose scope Event, and set Event parameter to prophecy_product_reference.

Create this before collecting the data you want to report on. Custom definitions do not backfill earlier reporting data. Use a stable catalogue reference, never a customer identifier. See Google's event parameter guide.

Step 4: Verify and publish

  1. Open the product page through GTM Preview with the relevant analytics consent granted.
  2. Open Prophecy, select a room photo and generate a preview. Generating a preview uses your normal token allowance.
  3. In Tag Assistant, confirm that each action creates a prophecy_event with the expected prophecy_event_name, and that the GA4 tag fires once.
  4. In GA4 DebugView, confirm that the named events and product reference arrive. Use a debug-enabled test session; check Realtime as well.
  5. Verify the phone flow if offered. Check sign-in and failure events in a test environment where those states can be exercised.
  6. If you test Order this product, remember that your existing order handler may add the product to a basket or navigate. The analytics listener does not cancel it.
  7. Test with analytics consent declined and confirm the tag follows your site's intended consent behaviour. A data-layer event by itself does not grant consent.
  8. Publish the GTM container after these checks pass.

Standard reports can take 24–48 hours to populate. Tracking begins when the integration is active; it cannot reconstruct earlier dialog opens or abandoned journeys.

Optional: Send directly with gtag.js

If your website uses gtag.js without GTM, keep the event allowlist and replace the data-layer push in your chosen listener with this call. Do not send through both routes.

direct-ga4.js
const name = event.type === 'order'
  ? 'prophecy_order_click'
  : `prophecy_${event.type.replace(/-/g, '_')}`;
 
if (typeof window.gtag === 'function') {
  window.gtag('event', name, {
    send_to: 'G-XXXXXXXXXX', // Replace with your existing GA4 measurement ID.
    prophecy_product_reference: event.productReference || ''
  });
}

Load and configure your Google tag before the listener runs. Keep the same consent controls and GA4 custom dimension. Skip the GTM setup steps. Do not detect GTM by checking whether dataLayer exists: direct gtag.js installations also use it.

Build a usage report

Use GA4 Explorations to examine:

  • Adoption: sessions with a Prophecy interaction compared with sessions visiting product pages where the feature is offered.
  • Generation journey: generation starts, completed previews and failures. The configurator widget can generate without opening the dialog, and shoppers can reuse photos, so do not require every generation to pass through open and photo-selected.
  • Product interest: completed previews grouped by Prophecy product reference.
  • Sales association: compare subsequent basket additions and purchases in sessions with and without Prophecy use. This comparison does not prove that Prophecy caused a sales increase.

Event counts are actions, not unique people. Use GA4's user or session metrics for audience size. Completion events can be missed if a shopper leaves before the preview returns, so browser event counts are not a billing ledger.

Orbital's generation records can support reporting on generation activity, outcomes and token usage. They do not reconstruct the full browser journey. Contact Orbital to confirm which account-specific reports are available; this integration sends data into your own GA4 property.

Privacy and troubleshooting

Keep analytics parameters limited to the listed event name and a non-sensitive product reference. Do not forward the full event.detail, room photos, generated-image URLs, prompts, account details, session tokens or raw error messages.

  • No data-layer events: check that the script-tag callback was installed before Prophecy initialised, or that the instance listener is attached to the active instance.
  • Data-layer events but no GA4 events: check the exact trigger name, measurement ID, tag firing and consent settings. Browser blockers can also prevent collection.
  • Duplicate events: use one bridge only. Remove repeated instance listeners during application cleanup, and check that only one GA4 tag handles prophecy_event.
  • Missing product breakdown: check the parameter mapping and event-scoped custom dimension. Allow time for standard reports to process.

For the separate 3D viewer events, use Configurator analytics.

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.

order.ts
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:

product-page.html
<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:

FieldMeaning
skuThe configurator's SKU for the configuration in the preview
pageUrlThe page the preview was made from, query string and all
productUrlWhere Prophecy sends the shopper unless you call preventDefault()
productReference / selectionStringThe product and its configuration
resultUrl / jobIdThe preview image and the job that made it

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

Instance API

MethodPurpose
checkAvailability()Preflight setup, origin access, entitlement, and token balance
open() / close() / isOpen()Control and inspect dialog visibility
mount(target)Mount Prophecy's default launcher
mountOverlay(target?)Put the widget on the configurator, or another element; the script tag does this for you
useLauncher(target) / releaseLauncher()Move the launcher to another element, or detach it
setProductId(id)Synchronise an OV25 product change in an SPA
setProduct(product)Atomically switch an external product, its images, and URL
setAccountContext(key)Invalidate sessions and memory on login, logout, or account switching
getState()Read the current public state without subscribing
refreshHistory() / clearHistory()Reload or remove customer-owned history
on(name, handler) / off(name, handler)Add or remove event handlers
destroy()Abort work and remove UI, listeners, and temporary object URLs

Core options

OptionTypePurpose
sessionEndpointstringSame-origin retailer route returning a short-lived session
sessionProviderfunctionProgrammatic alternative to sessionEndpoint
endpointstringOrbital API host for a staging environment; normally omit
configuratorselector | iframeDisambiguate multiple configurators; normally omit
buttonselector | buttonAttach Prophecy to an existing site-owned control
productReferencestringStable SKU, variant ID, or product handle for external images
productImages(string | Blob)[]One to four CORS-readable URLs or image blobs
productUrlstringResult call-to-action and history URL
resolution'1K' | '2K' | '4K'Requested output resolution, subject to entitlement
historyHistoryAdapterAccount-backed load, save, and clear operations
accountKeystring | nullNon-sensitive browser marker for account changes
localHistorybooleanOpt device history in or out
developmentbooleanOverride automatic localhost development behaviour
timeoutMsnumberGeneration polling timeout; default four minutes
buttonLabelstringWording on Prophecy's own launcher button

Declarative attributes

AttributePurpose
data-prophecy-session-endpointSame-origin browser-session endpoint
data-prophecy-configuratorSelector for a specific OV25 iframe
data-prophecy-buttonSelector for a site-owned launcher
data-prophecy-endpointOrbital API host for a staging environment; normally omit
data-prophecy-product-idExplicit OV25 product ID for migration cases
data-prophecy-product-referenceStable external product reference
data-prophecy-product-imagesJSON array containing one to four product-image URLs
data-prophecy-product-urlProduct page URL used by results and history
data-prophecy-resolutionRequested 1K, 2K, or 4K resolution
data-prophecy-local-historyExplicitly enable or disable device history
data-prophecy-autoEnable or disable automatic initialisation

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.