Admin UI in your own app

Browser (your admin page)          Your backend                         Snakkbar
──────────────────────────         ─────────────                         ────────
mountAdmin(el, { token })  ──►  GET /snakkbar/operator-token
                                 (checks your own session)
                                 POST /api/v1/server/operator-tokens ──►  upserts operator,
                                   Authorization: Bearer sk_snakkbar_…     returns JWT (1 h)
                           ◄──   { token }
admin UI calls /api/v1/operator/* with the token, refreshes it before expiry

// Example: Next.js route handler — app/api/snakkbar/operator-token/route.ts
export async function POST() {
  const user = await requireStaffUser(); // your own auth; throw 401 if not staff
  const res = await fetch(`${process.env.SNAKKBAR_HOST}/api/v1/server/operator-tokens`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.SNAKKBAR_SECRET_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      externalId: user.id,              // stable id in your system
      name: user.displayName,           // shown to visitors
      email: user.email,                // optional
      avatarUrl: user.avatarUrl,        // optional, https URL
      role: user.isAdmin ? "admin" : "agent",
      ttlSeconds: 3600,                 // optional, max 86400
    }),
  });
  if (!res.ok) return new Response("Snakkbar token failed", { status: 502 });
  const { token, expiresAt } = await res.json();
  return Response.json({ token, expiresAt });
}

<?php
// modules/snakkbar/Module.php — register in config/app.php: 'modules' => ['snakkbar' => modules\snakkbar\Module::class], 'bootstrap' => ['snakkbar']
namespace modules\snakkbar;

use Craft;
use craft\elements\User;
use craft\events\ElementEvent;
use craft\events\UserEvent;
use craft\events\UserGroupsAssignEvent;
use craft\services\Elements;
use craft\services\Users;
use yii\base\Event;

class Module extends \yii\base\Module
{
    public function init(): void
    {
        parent::init();
        Craft::setAlias('@modules/snakkbar', __DIR__);
        $this->controllerNamespace = Craft::$app->request->isConsoleRequest ? 'modules\snakkbar\console' : 'modules\snakkbar\controllers';

        $sync = fn(?User $user) => $user && Craft::$app->queue->push(new SyncOperator(['userId' => $user->id, 'uid' => $user->uid]));
        foreach ([Elements::EVENT_AFTER_SAVE_ELEMENT, Elements::EVENT_AFTER_DELETE_ELEMENT, Elements::EVENT_AFTER_RESTORE_ELEMENT] as $name) {
            Event::on(Elements::class, $name, fn(ElementEvent $e) => $e->element instanceof User && $sync($e->element));
        }
        foreach ([Users::EVENT_AFTER_SUSPEND_USER, Users::EVENT_AFTER_UNSUSPEND_USER] as $name) {
            Event::on(Users::class, $name, fn(UserEvent $e) => $sync($e->user));
        }
        Event::on(Users::class, Users::EVENT_AFTER_ASSIGN_USER_TO_GROUPS, fn(UserGroupsAssignEvent $e) => $sync(User::find()->id($e->userId)->status(null)->trashed(null)->one()));
    }

    public static function isStaff(?User $user): bool
    {
        return $user && !$user->trashed && $user->getStatus() === User::STATUS_ACTIVE && ($user->admin || $user->isInGroup('kundeservice'));
    }

    public static function client(): \GuzzleHttp\Client
    {
        return Craft::createGuzzleClient([
            'base_uri' => rtrim(getenv('SNAKKBAR_HOST'), '/') . '/api/v1/server/',
            'headers' => ['Authorization' => 'Bearer ' . getenv('SNAKKBAR_SECRET_KEY')],
        ]);
    }

    public static function remove(string $uid): void
    {
        self::client()->delete('operators/' . rawurlencode($uid));
    }

    /** PUT for staff, DELETE for everyone else. */
    public static function push(User $user): void
    {
        if (!self::isStaff($user)) {
            self::remove($user->uid);
            return;
        }
        $body = ['name' => $user->getFriendlyName(), 'email' => $user->email, 'role' => $user->admin ? 'admin' : 'agent'];
        $photo = $user->getPhoto()?->getUrl();
        if ($photo && str_starts_with($photo, 'https://')) {
            $body['avatarUrl'] = $photo; // left out otherwise, so a photo set in Snakkbar survives
        }
        self::client()->put('operators/' . rawurlencode($user->uid), ['json' => $body]);
    }
}

<?php
// modules/snakkbar/SyncOperator.php
namespace modules\snakkbar;

use craft\elements\User;
use craft\queue\BaseJob;

class SyncOperator extends BaseJob
{
    public int $userId;
    public string $uid;

    public function execute($queue): void
    {
        $user = User::find()->id($this->userId)->status(null)->trashed(null)->one();
        // Hard-deleted users are gone from Craft by now; remove them by uid.
        $user ? Module::push($user) : Module::remove($this->uid);
    }

    protected function defaultDescription(): string
    {
        return 'Snakkbar: synkroniser bruker';
    }
}

<?php
// modules/snakkbar/console/SyncController.php — run nightly: php craft snakkbar/sync
namespace modules\snakkbar\console;

use craft\console\Controller;
use craft\elements\User;
use modules\snakkbar\Module;

class SyncController extends Controller
{
    public function actionIndex(): int
    {
        $staff = [];
        foreach (User::find()->status(null)->each() as $user) {
            if (Module::isStaff($user)) {
                Module::push($user);
                $staff[$user->uid] = true;
            }
        }
        $list = json_decode((string) Module::client()->get('operators')->getBody(), true);
        foreach ($list['operators'] as $operator) {
            if (!$operator['deactivatedAt'] && !isset($staff[$operator['externalId']])) {
                Module::remove($operator['externalId']);
            }
        }
        return 0;
    }
}

<div id="snakkbar-admin" style="height: calc(100vh - 64px)"></div>
<script src="https://<host>/admin.js"></script>
<script>
  let cached = null;
  async function token() {
    if (cached && Date.parse(cached.expiresAt) - Date.now() > 60_000) return cached.token;
    cached = await (await fetch("/api/snakkbar/operator-token", { method: "POST" })).json();
    return cached.token;
  }
  const admin = Snakkbar.mountAdmin(document.getElementById("snakkbar-admin"), {
    host: "https://<host>",
    token,               // string or (async) function; called before every request
    language: "no",      // "en" for English UI
    theme: "auto",       // "light" | "dark" | "auto": until the person picks one themselves
    // onThemeChange: (theme) => …, // optional: told when they pick (e.g. to match your page)
    // look: "snakkbar", // optional: Snakkbar's own look (as in the hosted panel) instead of the
    //                   // neutral default in the tenant's brand colour
  });
  // admin.unmount() when leaving the page
</script>

<div class="live" style="position: relative; overflow: hidden">
  <iframe
    name="snakkbar-mirror"
    sandbox="allow-scripts allow-same-origin"
    referrerpolicy="no-referrer"
    style="position: absolute; top: 0; left: 0; border: 0; transform-origin: 0 0; pointer-events: none"
  ></iframe>
  <div class="cursor" style="position: absolute; pointer-events: none"></div>
</div>

import { isMirrorMessage, type MirrorMessage } from "@snakkbar/sdk";
// `staff` is your createOperatorClient(...) from sdk.md; `visitorId` the visitor to watch.

const frame = document.querySelector<HTMLIFrameElement>("iframe[name=snakkbar-mirror]")!;
const box = frame.parentElement!;
const cursor = box.querySelector<HTMLElement>(".cursor")!;
let mirrorReady = false;
let fallback: ReturnType<typeof setTimeout> | undefined;

// No `ready` from the mirror within a few seconds: the site refused framing (or has no widget).
function load(url: string) {
  mirrorReady = false;
  frame.src = url;
  clearTimeout(fallback);
  fallback = setTimeout(() => !mirrorReady && showSchematicView(), 6000);
}

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow || !isMirrorMessage(event.data)) return;
  if (event.data.type === "ready") { mirrorReady = true; clearTimeout(fallback); hideSchematicView(); }
});

const visitor = await staff.visitors.get(visitorId);
if (visitor.currentPage) load(visitor.currentPage.url);

const send = (message: MirrorMessage, url: string) =>
  frame.contentWindow?.postMessage(message, new URL(url).origin);

const stopWatching = staff.visitors.watch(visitorId);
const sub = staff.subscribe((event) => {
  if (event.type !== "pointer" || event.visitorId !== visitorId || !event.visible) return;
  if (event.url !== frame.src) load(event.url); // the visitor moved on
  if (event.viewport) {
    // Render the page at the visitor's viewport size, scaled to fit the box.
    const scale = box.clientWidth / event.viewport.width;
    frame.style.width = `${event.viewport.width}px`;
    frame.style.height = `${event.viewport.height}px`;
    frame.style.transform = `scale(${scale})`;
    box.style.height = `${event.viewport.height * scale}px`;
    const last = event.samples.at(-1);
    if (last) cursor.style.transform = `translate(${last[1] * scale}px, ${last[2] * scale}px)`;
    // event.clicks: draw a short ripple at each [t, x, y] (scaled the same way)
  }
  if (event.scroll) send({ snakkbar: "mirror", type: "scroll", x: event.scroll.x, y: event.scroll.y }, event.url);
});
// leaving: stopWatching(); sub.close();