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
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
npm install @nomac/phoneimport { NomacPhone } from "@nomac/phone/react";
<NomacPhone url={url} onEvent={(e) => e.type === "ended" && refresh()} style={{ height: 720 }} />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" }}. endedcomes once, when a phone that was shown ends. A link that never worked is anerror.- While the phone starts, the view waits for it, and after a dropped connection it reconnects by itself.
- Only view links of
https://nomac.appare 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.comcovers the subdomains.http://localhost:3000works 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:
subis your user's id,sidthe phone's id andexpat 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.
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
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.