samy.js, samy.css, Session-Token

Zum Nachschlagen für die Seite deiner App: die Brücke samy.js, das Session-Token und das Stylesheet samy.css.

samy.js

<script src="https://packlets.app/embed/samy.js"></script>

Danach gibt es das Objekt samy:

Alle Aufrufe außer samy.inSamy geben ein Promise zurück.

• Außerhalb von Samy (zum Beispiel im Browser) schlagen die Aufrufe sofort fehl. Frag deshalb zuerst samy.inSamy ab.
• Zeitlimit: Antwortet die App nicht innerhalb von 15 Sekunden, schlägt der Aufruf fehl.
• Nur deine Adresse: Antworten bekommen nur Seiten mit derselben Herkunft (https, Host und Port) wie die Adresse, die du als page gesetzt hast.
• Nur die Hauptseite: Jeder Aufruf trägt einen geheimen Brücken-Schlüssel aus den Startdaten. Aufrufe aus iframes fremder Adressen haben ihn nicht, Samy ignoriert sie. Mehr unter iframes und fremde Inhalte.
• Läuft die Seite in Samy, trägt <html> die Klasse in-samy. Ist das Skript geladen, feuert auf window das Ereignis samy:ready.
• Wieder geöffnet: Samy hält die zuletzt geöffneten Seiten im Speicher (bis zu vier). Kommt jemand zurück, lädt die Seite nicht neu. Stattdessen feuert auf window das Ereignis samy:activated. Das ist der richtige Moment, veraltete Daten aufzufrischen. Der Knopf oben rechts in der App lädt die Seite bei Bedarf ganz neu.

Laden und Platzhalter

Bis deine Seite fertig ist, zeigt Samy Avatar und Name der App. Normalerweise verschwindet der Platzhalter, sobald die Seite geladen ist. Lädt deine Seite danach noch Daten nach, bindest du das Skript mit data-ready="manual" ein und rufst selbst samy.ready(), wenn alles steht. Kommt nach sechs Sekunden kein ready(), blendet Samy den Platzhalter trotzdem aus.

<script src="https://packlets.app/embed/samy.js" data-ready="manual"></script>
<script>
  loadEverything().then(() => samy.ready());
</script>

Startdaten

Samy hängt beim Laden Startdaten an die Adresse, hinter #samy= (Base64url-kodiertes JSON). Der Teil hinter # geht nie an deinen Server. samy.js liest ihn sofort aus, stellt ihn als samy.launch bereit und entfernt ihn wieder aus der Adresse. Das Session-Token aus den Startdaten liefert samy.token() in den ersten 45 Sekunden ohne Umweg über die App. So weiß deine Seite schon beim ersten Aufruf deines Servers, wer sie öffnet (wie initData bei Telegram).

Den Brücken-Schlüssel aus den Startdaten legt samy.js im sessionStorage deiner Adresse ab. So funktioniert samy auch auf weiteren Seiten, zu denen du innerhalb deiner Adresse verlinkst. Du musst dafür nichts tun.

Farben

samy.theme enthält Samys Farben: bg, surface, text, text_secondary, text_tertiary, field, cta, on_cta, danger und scheme (light). samy.js setzt sie zusätzlich als CSS-Variablen auf <html>, zum Beispiel --samy-bg, --samy-text, --samy-cta oder --samy-text-secondary. Damit passt deine Seite ohne eigene Farbwerte zur App.

Abstände

In Samy füllt deine Seite die ganze Fläche unter Samys schmaler Kopfzeile bis zum unteren Rand (Vollbild). Die Kopfzeile bleibt immer gleich und verdeckt nichts. Unten setzt Samy die CSS-Variable --samy-inset-bottom (Home-Leiste des iPhones) und gibt <html> diesen Abstand als Innenabstand; --samy-inset-top gibt es weiter, ist aber 0. Normalerweise musst du nichts tun.

• Willst du die volle Höhe ohne Scrollen füllen, rechne die Abstände heraus: min-height: calc(100vh - var(--samy-inset-top) - var(--samy-inset-bottom)).
• Willst du alles selbst regeln, schreib <html data-samy-insets="manual"> und nutz die Variablen an passender Stelle.

Speicher

samy.storage speichert kleine Texte auf dem Gerät, getrennt nach Konto und App. Teilen sich zwei Konten ein Handy, sieht keins die Einträge des anderen. Das unterscheidet ihn vom normalen localStorage der Seite. Bis zu 100 Einträge je App, je höchstens 16 KB. Für Objekte nimm JSON.stringify und JSON.parse. Meldet sich jemand ab, bleiben die Einträge auf dem Gerät. Löscht er das Konto, sind sie wertlos, weil niemand sonst sie lesen kann.

Session-Token

Ein JWT, das sagt, wer die Seite gerade in Samy öffnet.

Prüf auf deinem Server immer drei Dinge: die Signatur, exp und dass aud dein Packlet ist. Erzeugst du in der App einen neuen Schlüssel, sind alle Tokens sofort ungültig.

Token von Samy prüfen lassen

Ohne eigene JWT-Bibliothek fragt dein Server Samy. Dieser Aufruf braucht keinen Schlüssel.

POST https://api.packlets.app/v1/session-token/verify
Content-Type: application/json

Antwort bei einem gültigen Token:

{
  "valid": true,
  "packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
  "page_url": "https://deine-seite.example/app",
  "user": { "id": "4f1c…", "email": "[email protected]", "name": "Du" },
  "expires_at": "2026-11-10T08:16:00.000Z"
}

Sonst Status 401:

{ "valid": false, "error": "invalid_token", "message": "Das Token ist ungültig oder abgelaufen." }

Für den Aufruf gilt das Rate-Limit, gezählt je Adresse deines Servers.

samy.css

<link rel="stylesheet" href="https://packlets.app/embed/samy.css">

Das Stylesheet bringt die Schrift Lato, die Farben der App und diese Bausteine:

Farben und Maße als Variablen:

Text lässt sich auf der Seite nicht markieren (user-select: none), wie in einer App. Eine fertige Beispielseite liegt unter /embed/beispiel.html.