Referenz

packlets.js, packlets.css, Session-Token

Alles für die Seite deiner App: die Brücke, das Stylesheet und das Token.

Als Markdown öffnen

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

packlets.js

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

Danach gibt es das Objekt packlets:

AufrufErgebnis
packlets.inPackletstrue, wenn die Seite in der Packlets-App läuft, sonst false. Kein Aufruf, sondern ein Wert.
packlets.launchStartdaten, sofort beim Laden da: { v, packlet_id, platform, theme, locale }. Kein Aufruf, sondern ein Wert.
packlets.localeSprache der App: "de" oder "en" (siehe Sprache). Kein Aufruf, sondern ein Wert.
packlets.themeDie Farben von Packlets (siehe Farben). Kein Aufruf, sondern ein Wert.
packlets.ready()Meldet, dass die Seite fertig ist. Packlets blendet dann den Platzhalter aus. Nur nötig mit data-ready="manual".
await packlets.token()Das Session-Token als Text. Direkt nach dem Laden kommt es ohne Wartezeit aus den Startdaten.
await packlets.fetch(url, init)Wie fetch(), setzt aber Authorization: Bearer <Token> mit einem frischen Token. Gibt die normale Antwort zurück.
await packlets.info(){ app: "packlets", version: 2, packlet_id: "…", platform: "iOS", theme: {…}, locale: "de" }. platform ist iOS oder android, locale ist de oder en.
packlets.toast("Gespeichert")Kurze Meldung in der App. Der Text wird nach 140 Zeichen abgeschnitten.
packlets.open("https://…")Öffnet die Adresse im Browser des Handys. Nur http(s).
packlets.haptic("success")Vibration: tap (Standard), selection, success oder error.
await packlets.storage.get(key)Gespeicherter Text oder null. Siehe Speicher.
await packlets.storage.set(key, text)Speichert Text (höchstens 16 KB).
await packlets.storage.remove(key)Löscht einen Eintrag.
await packlets.storage.keys()Alle Schlüssel dieser App.

Alle Aufrufe außer den Werten (packlets.inPacklets, packlets.launch, packlets.locale, packlets.theme) geben ein Promise zurück.

  • Außerhalb von Packlets (zum Beispiel im Browser) schlagen die Aufrufe sofort fehl. Frag deshalb zuerst packlets.inPacklets 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, Packlets ignoriert sie. Mehr unter iframes und fremde Inhalte.
  • Läuft die Seite in Packlets, trägt <html> die Klasse in-packlets. Ist das Skript geladen, feuert auf window das Ereignis packlets:ready.
  • Wieder geöffnet: Packlets 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 packlets:activated. Das ist der richtige Moment, veraltete Daten aufzufrischen. Der Knopf oben rechts neben der Glocke lädt die Seite bei Bedarf ganz neu.

Laden und Platzhalter

Bis deine Seite fertig ist, zeigt Packlets 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 packlets.ready(), wenn alles steht. Kommt nach sechs Sekunden kein ready(), blendet Packlets den Platzhalter trotzdem aus.

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

Startdaten

Packlets hängt beim Laden Startdaten an die Adresse, hinter #packlets= (Base64url-kodiertes JSON). Der Teil hinter # geht nie an deinen Server. packlets.js liest ihn sofort aus, stellt ihn als packlets.launch bereit und entfernt ihn wieder aus der Adresse. Das Session-Token aus den Startdaten liefert packlets.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 packlets.js im sessionStorage deiner Adresse ab. So funktioniert packlets auch auf weiteren Seiten, zu denen du innerhalb deiner Adresse verlinkst. Du musst dafür nichts tun.

Sprache

Packlets gibt es auf Deutsch und Englisch, je nach Sprache des Handys. Diese Sprache steht in den Startdaten als locale ("de" oder "en"), in packlets.info() und als packlets.locale. Außerhalb von Packlets nimmt packlets.locale die Sprache des Browsers: de für Deutsch, sonst en. Hat <html> noch kein lang, setzt packlets.js es auf diesen Wert.

js
const text = packlets.locale === "de" ? { save: "Speichern" } : { save: "Save" };
document.querySelector("#save").textContent = text.save;
const datum = new Intl.DateTimeFormat(packlets.locale, { dateStyle: "medium" }).format(new Date());

Baut dein Server Texte selbst, hilft der Header Accept-Language: Packlets schickt ihn beim Laden der Seite in der Sprache der App mit.

Farben

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

Abstände

In Packlets füllt deine Seite die ganze Fläche unter der schmalen Kopfzeile von Packlets bis zum unteren Rand (Vollbild). Die Kopfzeile bleibt immer gleich und verdeckt nichts. Unten setzt Packlets die CSS-Variable --packlets-inset-bottom (Home-Leiste des iPhones) und gibt <html> diesen Abstand als Innenabstand; --packlets-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(--packlets-inset-top) - var(--packlets-inset-bottom)).
  • Willst du alles selbst regeln, schreib <html data-packlets-insets="manual"> und nutz die Variablen an passender Stelle.

Speicher

packlets.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 Packlets öffnet.

AlgorithmusHS256
GeheimnisSHA-256-Hash deines Schlüssels als Hex-Text in Kleinbuchstaben. Dasselbe wie bei der Webhook-Signatur.
Gültigkeit60 Sekunden
FeldInhalt
isshttps://api.packlets.app
audID deines Packlets. Dieselbe wie packlet_id in jedem Webhook-Ereignis.
subID des Nutzers in Packlets. Bleibt für denselben Nutzer immer gleich.
emailE-Mail-Adresse des Nutzers.
nameName des Nutzers, kann fehlen.
iat, expAusgestellt und gültig bis, als Unix-Zeit.
jtiEindeutige Kennung dieses Tokens.

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 Packlets prüfen lassen

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

HTTP
POST https://api.packlets.app/v1/session-token/verify
Content-Type: application/json
FeldTypPflichtBedeutung
tokenTextjaDas Token aus dem Header Authorization der Anfrage an deinen Server.

Antwort bei einem gültigen Token:

JSON
{
  "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:

JSON
{ "valid": false, "error": "invalid_token", "message": "The token is invalid or has expired." }

Achtung: Vergleich packlet_id mit der ID deines Packlets. Sonst nimmt dein Server auch Tokens an, die für ein fremdes Packlet ausgestellt wurden. Bedient dein Server viele Packlets (zum Beispiel eine App für alle Nutzer), prüf stattdessen page_url: Das ist die Seite, die das Packlet gerade zeigt.

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

packlets.css

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

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

KlasseWofür
packletsRahmen der Seite: 16 Pixel Innenabstand, Bausteine untereinander mit 12 Pixel Abstand, mindestens so hoch wie der Bildschirm.
packlets-title, packlets-bigÜberschrift (20 px) und große Zahl (44 px).
packlets-sub, packlets-label, packlets-noteGrauer Nebentext, Abschnitts-Label in Großbuchstaben, kleiner Hinweis.
packlets-row, packlets-spread, packlets-grow, packlets-pushNebeneinander; an die Ränder verteilen; Platz füllen; nach unten schieben.
packlets-buttonKnopf wie in der App, 44 px hoch. Dazu is-secondary (hell) und is-small (32 px).
packlets-tabsUmschalter zwischen Ansichten. Der aktive Tab trägt aria-selected="true".
packlets-listListe mit feinen Trennlinien, Zeilen mindestens 44 px hoch.
packlets-tableTabelle. Zahlenspalten mit is-num rechtsbündig.
packlets-fieldEingabefeld.
packlets-chip, packlets-dotKleines Kennzeichen; Status-Punkt grün, mit is-warn rot.
packlets-barsKleines Balkendiagramm aus <i style="height: 40%">. Der aktive Balken trägt is-active.

Farben und Maße als Variablen:

VariableBedeutung
--packlets-bgHintergrund
--packlets-text, --packlets-text-2, --packlets-text-3Haupttext, Nebentext, noch hellerer Text
--packlets-iconSymbole
--packlets-cta, --packlets-on-ctaDunkelblau der Knöpfe und die Schrift darauf
--packlets-fieldHellgrau für Felder und helle Knöpfe
--packlets-selected, --packlets-barAusgewählter Tab, Balken im Diagramm
--packlets-dividerTrennlinien
--packlets-ok, --packlets-warnGrün und Rot für Status
--packlets-radiusEckenradius

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