Docs · Show the phone

Show the phone

Your user sees and uses their phone in your product, and their agent or your worker drives it with a token for that phone alone. Neither needs a NoMac account.

A link

TypeScript
const { url, expires_at } = await phone.viewLink({ control: true, minutes: 120 });

The link is the permission: whoever opens it watches the phone, or with control, uses it, unless you keep it to your site and your user (below). It works until it expires, after 2 hours by default and a day at most, or until the phone ends.

With a control link, one viewer holds input at a time and another can take over. A person's input counts as activity, so the phone does not stop as idle while your user works on it.

In your page

Terminal
npm install @nomac/phone
React
import { NomacPhone } from "@nomac/phone/react";

<NomacPhone url={url} onEvent={(e) => e.type === "ended" && refresh()} style={{ height: 720 }} />
Any page
import { embedPhone } from "@nomac/phone";

const phone = embedPhone(document.getElementById("phone"), url, {
  onEvent: (event) => console.log(event.type), // ready, app_launched, ended, error
});
phone.home();
phone.tap(0.5, 0.5);
const png = await phone.screenshot();
  • The box keeps an iPhone's shape. For an iPad, pass style={{ aspectRatio: "834 / 1210" }}.
  • ended comes once, when a phone that was shown ends. A link that never worked is an error.
  • While the phone starts, the view waits for it, and after a dropped connection it reconnects by itself.
  • Only view links of https://nomac.app are framed.

Only on your site

const { url } = await phone.viewLink({ control: true, allowedOrigins: ["https://app.example.com"] });
  • The link then opens only in a frame on one of those sites. It does not open on its own page or on another site.
  • Give each as https://, a host and an optional port. https://*.example.com covers the subdomains. http://localhost:3000 works for testing.
  • Up to 10 sites per link. Browsers keep to them; to stop a copied link anywhere, sign your user too.

Only for your user

import { signVisitor } from "@nomac/sdk";

// Once. Keep the secret on your server (here NOMAC_EMBED_SECRET), never in a browser.
const { secret } = await nomac.embed.newSecret();

// On your server, for each page load: the link names your user, and you sign them.
const { url } = await phone.viewLink({ control: true, allowedOrigins: ["https://app.example.com"], visitor: user.id });
const visitor = await signVisitor({ secret: process.env.NOMAC_EMBED_SECRET, sessionId: phone.id, visitor: user.id });
const src = `${url}#visitor=${visitor}`;

// In your page: embedPhone(element, src)
  • The link opens only with your server's signature for that user. A copied link opens nothing.
  • The signature is a JWT signed with HS256 and the secret: sub is your user's id, sid the phone's id and exp at most 15 minutes ahead. Any JWT library can make it.
  • It goes after #visitor=, so it never reaches a server log, and the page takes it out of its address. The page then keeps working until the link expires, and reconnects by itself, also while the phone waits to start.
  • A new secret replaces the old one at once. Views already open keep working.

For every link

await nomac.embed.set({ allowedOrigins: ["https://app.example.com"], requireVisitor: true });

Both then apply to every link made over the API from then on: the view and control links in each phone's answer, and a phone token's links too. A link can name fewer sites, never others. Links made before keep what they had.

Over REST, a link takes allowed_origins and visitor on POST /api/v1/simulator/sessions/{id}/view. The defaults are GET and PUT /api/v1/embed with { "allowed_origins": [...], "require_visitor": true }, and the secret POST /api/v1/embed/secret.

A token for one phone

TypeScript
const { token } = await phone.token({ minutes: 60 });
// Hand it to your user's agent or your worker:
const theirs = new NoMac({ token }).phone(phone.id);

An nmp_… token reaches that phone's tools, files, saved states, view, replay and tunnel, until it expires after 2 hours by default and a day at most. Once the phone ends, it still reads the phone and its replay. In Python: NoMac(token=token).

It cannot start, list or stop phones, make another token, use the account's secrets, delete a label or reach your webhooks. It stops working when the API key that made it is revoked.

phone.revokeTokens() revokes every token and link the phone has so far, view, control, file and replay links included. A view already open closes within 20 seconds, and the phone keeps running. Links and tokens made afterwards work.