SDK Problems

Overview

The Asiyst Web SDK (@asiyst/sdk) is engineered to run in an isolated Shadow DOM container with zero CSS interference. However, issues can arise during client hydration, WebGL context creation, or cross-origin iframe embedding.

Initialization Failures

Symptom: No widget appears and console is silent

1. Check execution context: The SDK cannot run inside Node.js or SSR rendering pipelines. Ensure Asiyst.init() executes only after DOM mount.

1. Verify public key format: Public SDK keys must start with pk_live_ or pk_test_. Private secret keys (sk_live_) will be rejected with INVALID_CREDENTIALS.

1. Check console for DOMAIN_NOT_ALLOWED:

      [Asiyst] Handshake failed: Origin 'https://mywebsite.com' not whitelisted for project proj_9f8a2b3c4d.

   Fix: Add your domain to Project Settings > Allowed Domains in the Asiyst dashboard.

WebGL & Canvas Rendering Issues

Symptom: Chat window works, but avatar character is blank or black box

1. Browser WebGL Support: Test if WebGL 2 is active on the client by visiting chrome://gpu or running !!window.WebGL2RenderingContext in devtools.

1. Context Loss Recovery: When mobile devices switch apps, the GPU context may temporarily reset. The SDK handles context recovery automatically, but if overridden by custom canvas manipulation, call:

      Asiyst.avatar.reload();

1. Hardware Acceleration: If running inside headless browser testing (Cypress / Playwright), enable --use-gl=swiftshader in your test runner config.

Z-Index & Layer Stacking Conflicts

Symptom: Avatar is hidden beneath sticky headers, modals, or cookie banners

By default, the Asiyst container uses a z-index of 9999. If your host page contains overlays with z-index: 2147483647:

Asiyst.init({
  projectId: "proj_9f8a2b3c4d",
  publicKey: "pk_live_8e7d6c5b4a3f2e1d",
  options: {
    zIndex: 2147483640,
    offset: { x: 20, y: 80 }, // Shift away from bottom cookie banner
  },
});

Event Listeners Not Firing

If Asiyst.on("message:received", ...) does not trigger:

1. Ensure listeners are attached before dispatching messages or immediately after Asiyst.init().

1. Check if a component unmounted and called Asiyst.off() or Asiyst.destroy().

// Recommended pattern
await Asiyst.init({ projectId, publicKey });
const unsubscribe = Asiyst.on("message:received", (payload) => {
  console.log("Response text:", payload.text);
  console.log("Citations:", payload.citations);
});

Enabling Debug Telemetry

To output verbose network, animation, and state transitions to the browser console:

Asiyst.init({
  projectId: "proj_9f8a2b3c4d",
  publicKey: "pk_live_8e7d6c5b4a3f2e1d",
  options: {
    debug: true,
  },
});

Debug mode prints detailed handshakes, WebSocket ping/pong frames, and token stream timings.