Apps
Eigene App bauen
Die App ist deine Webseite: im Look von Packlets, mit packlets.js, Anmeldung per Session-Token und Mitteilungen unter der Glocke.
Eine App ist eine Webseite, die du selbst baust. Packlets zeigt sie als Kachel im Tab Apps und öffnet sie unter dem Kopf der App, so breit wie der Bildschirm. Du hast alle Freiheit von HTML, und mit packlets.css sieht deine Seite trotzdem aus wie Packlets.
Wetter
Konto
Kanal oder App
| Kanal | App | |
|---|---|---|
| So geht es | Dein Tool schickt Nachrichten, Packlets zeigt sie untereinander. | Die ganze App ist deine Webseite. |
| Du brauchst | nur HTTP-Aufrufe | einen Server, der die Seite über https:// ausliefert |
| Gut für | Meldungen: ein Server fällt aus, ein Deploy schlägt fehl, eine Bestellung kommt rein | Arbeit mit Listen und Daten: Rechnungen freigeben, Bestellungen ansehen, Tickets beantworten |
| Aussehen | immer wie Packlets | mit packlets.css wie Packlets, sonst frei |
| Bedienung kommt an als | Webhook-Ereignis | normale Anfrage deiner Seite an deinen Server |
Fang mit einem Kanal an, wenn dein Tool sich vor allem melden soll. Auch dort gehen Knöpfe, Schalter, Diagramme und Tabellen, als Elemente in Nachrichten. Eine App lohnt sich, wenn du immer wieder etwas nachsehen oder abarbeiten willst.
Ideen, was eine App sein kann:
- Rechnungen freigeben: Jede offene Rechnung als Karte. Wisch nach rechts gibt sie frei, nach links lehnt sie ab.
- Server und Deploys: Status deiner Dienste, letzte Deploys, Knöpfe für Neustart und Rollback.
- Freigaben: Pull Requests oder Spesen ansehen und mit einem Tipp freigeben.
- Support-Postfach: Neue Anfragen lesen und kurz antworten.
- Bestellungen: Die Bestellungen deines kleinen Shops von heute, offen und versendet.
Wer Shopify kennt: Es ist dasselbe Prinzip wie bei eingebetteten Shopify-Apps mit App Bridge und Session-Token.
Du brauchst: einen Server mit https-Adresse, der deine Seite ausliefert.
1. Die Seite bauen
Eine normale HTML-Seite. Zwei Dateien von Packlets machen sie zur App: packlets.css für das Aussehen und packlets.js für die Verbindung zur App.
<!doctype html>
<html lang="de">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://packlets.app/embed/packlets.css">
<script src="https://packlets.app/embed/packlets.js"></script>
</head>
<body>
<main class="packlets">
<div class="packlets-row packlets-spread">
<div>
<p class="packlets-label" id="firma">Rechnung</p>
<p class="packlets-big" id="betrag">–</p>
<p class="packlets-sub" id="info"></p>
</div>
<span class="packlets-chip" id="offen"></span>
</div>
<div class="packlets-row">
<button class="packlets-button is-secondary packlets-grow" onclick="entscheide('ablehnen')">Ablehnen</button>
<button class="packlets-button packlets-grow" onclick="entscheide('freigeben')">Freigeben</button>
</div>
</main>
<script>
let rechnung;
async function naechste() {
const res = await packlets.fetch("/api/rechnungen/naechste");
rechnung = await res.json();
document.getElementById("firma").textContent = rechnung.firma;
document.getElementById("betrag").textContent = rechnung.betrag;
document.getElementById("info").textContent = `Fällig am ${rechnung.faellig} · ${rechnung.nummer}`;
document.getElementById("offen").textContent = `${rechnung.offen} offen`;
}
async function entscheide(aktion) {
const res = await packlets.fetch(`/api/rechnungen/${rechnung.id}/${aktion}`, { method: "POST" });
if (!res.ok) return packlets.toast("Das hat nicht geklappt");
packlets.haptic("success");
naechste();
}
naechste();
</script>
</body>
</html>Die Klassen wie packlets-row und packlets-button kommen aus packlets.css. Alle stehen in der Referenz.
2. Die Seite zur App machen
Tippe in Packlets im Tab Apps oben links auf das Plus, wähle Eine eigene App und gib ihr einen Namen. Dann schickt dein Tool einmal die Adresse deiner Seite:
curl -X PUT https://api.packlets.app/v1/ui \
-H "Authorization: Bearer $PACKLETS_KEY" \
-H "Content-Type: application/json" \
-d '{"page": "https://dein-server.de/rechnungen"}'Antwort: {"ok": true, "page": "https://dein-server.de/rechnungen"}. Packlets zeigt Verbunden!, und die Kachel steht im Tab Apps.
- Nur
https://. Im Body steht nurpage. - Beim ersten Öffnen zeigt Packlets die Adresse deiner Seite und fragt nach, bevor es sie lädt. Wechselst du später auf eine andere Adresse (anderer Host oder Port), fragt Packlets erneut.
- Eine andere Adresse setzt du mit einem neuen
PUT. - Einmal reicht. Was die Seite zeigt, bestimmt danach dein Server.
3. Mit der App sprechen: packlets.js
Über das Objekt packlets nutzt deine Seite, was nur die App kann:
| Aufruf | Was passiert |
|---|---|
packlets.toast("Gespeichert") | Kurze Meldung in der App. |
packlets.haptic("success") | Vibration. |
packlets.open("https://…") | Öffnet eine Adresse im Browser. |
await packlets.fetch(url, init) | Wie fetch(), aber mit Anmeldung. Siehe nächster Schritt. |
packlets.ready() | Seite ist fertig, Packlets blendet den Platzhalter aus (mit data-ready="manual"). |
packlets.storage.set("ort", "Berlin") | Speichert Text auf dem Gerät, getrennt nach Konto. |
Packlets hält geöffnete Seiten im Speicher. Kommt jemand zurück, ist deine Seite sofort da, ohne neu zu laden, und bekommt das Ereignis packlets:activated. Die Farben von Packlets stehen als CSS-Variablen bereit (--packlets-bg, --packlets-text, --packlets-cta …).
Im normalen Browser gibt es die App nicht, und die Aufrufe schlagen fehl. Frag deshalb vorher packlets.inPacklets ab, wenn deine Seite auch dort laufen soll:
<script>
if (!packlets.inPacklets) document.body.textContent = "Öffne diese Seite in Packlets.";
</script>Alle Aufrufe stehen in der Referenz.
4. Wissen, wer die Seite öffnet
Deine Seite ist öffentlich erreichbar. Zeigt sie private Daten, muss dein Server wissen, dass die Anfrage wirklich aus deiner App in Packlets kommt. Ein eigenes Login brauchst du dafür nicht: Packlets weiß schon, wer angemeldet ist, und bestätigt es deinem Server mit einem Session-Token.
- Deine Seite ruft
packlets.fetch()auf. Das holt bei Packlets ein frisches Token und schickt es alsAuthorization: Bearer …an deinen Server. - Dein Server prüft das Token. Stimmt es, weiß er, wer die Seite öffnet.
Das Token ist ein JWT, 60 Sekunden gültig und signiert mit einem Geheimnis, das nur du und Packlets kennen: dem SHA-256-Hash deines Schlüssels. Geprüft wird auf deinem Server:
import hashlib, os
import jwt # pip install pyjwt
SECRET = hashlib.sha256(os.environ["PACKLETS_KEY"].encode()).hexdigest()
PACKLET_ID = os.environ["PACKLETS_APP_ID"]
def packlets_user(request):
token = request.headers.get("Authorization", "").removeprefix("Bearer ")
claims = jwt.decode(token, SECRET, algorithms=["HS256"], audience=PACKLET_ID)
return {"id": claims["sub"], "email": claims.get("email"), "name": claims.get("name")}Schlägt die Prüfung fehl, werfen beide Funktionen einen Fehler. Antworte dann mit 401.
PACKLETS_APP_IDist die ID deines Packlets. Du bekommst sie in der Seite mit(await packlets.info()).packlet_id, und sie steht in jedem Webhook-Ereignis alspacklet_id.- Kein Cookie, keine Sitzung.
packlets.fetch()holt für jede Anfrage ein frisches Token. - Ohne JWT-Bibliothek kann dein Server das Token auch von Packlets prüfen lassen.
Achtung: Der Schlüssel gehört auf deinen Server, nie in die Seite. Was im HTML oder JavaScript steht, kann jeder lesen.
5. iframes und fremde Inhalte
Deine Seite selbst ist kein iframe: Packlets zeigt sie in einem eigenen Browser in der App. Zwei Dinge solltest du trotzdem regeln.
Fremde Inhalte in deiner Seite. Bettest du ein iframe von einer anderen Adresse ein (Video, Karte, Widget), kann es packlets nicht benutzen. Packlets gibt der Seite beim Laden einen geheimen Brücken-Schlüssel, den nur deine Seite sieht, und ignoriert jeden Aufruf ohne ihn. Was das iframe sonst tut, entscheidest du:
<iframe src="https://www.youtube-nocookie.com/embed/…"
sandbox="allow-scripts allow-same-origin"
referrerpolicy="no-referrer"></iframe>sandboximmer setzen und nur freigeben, was das iframe braucht. Ohneallow-top-navigationkann es deine Seite nicht wegschicken, ohneallow-popupskeine Fenster öffnen.- Fremde Skripte (Werbung, Tracking) direkt in deiner Seite laufen mit allen Rechten deiner Seite, auch mit
packlets.fetch(). Bind nur Skripte ein, denen du vertraust. - Inhalte von Nutzern nie als HTML einsetzen (
innerHTML), sondern als Text (textContent).
Deine Seite in fremden Seiten. Deine Adresse ist öffentlich. Eine andere Webseite könnte sie in ein iframe laden und Nutzer zu Klicks verleiten. Ein Token bekommt sie dort nicht, weil es Packlets dort nicht gibt. Verbiete das Einbetten trotzdem mit einem Header deines Servers:
Content-Security-Policy: frame-ancestors 'none'
X-Frame-Options: DENYPacklets stört das nicht, denn die App bettet deine Seite nicht in ein iframe ein.
6. Mitteilungen schicken
Deine App kann sich melden, auch wenn sie gerade niemand offen hat: Die Rechnungs-App sagt Bescheid, wenn neue Rechnungen warten, das Server-Dashboard, wenn ein Dienst ausfällt. Dafür schickt dein Server eine Nachricht, mit demselben Aufruf wie ein Kanal: POST /v1/push mit dem Schlüssel der App.
curl https://api.packlets.app/v1/push \
-H "Authorization: Bearer $PACKLETS_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "3 neue Rechnungen", "text": "Zusammen **1.284,50 €**, die erste ist am Freitag fällig."}'Die Antwort ist {"message_id": "…"}, wie bei jeder Nachricht. Dann passiert in Packlets dreierlei:
Mitteilungen
Rechnungen
Zusammen 1.284,50 €, die erste ist am Freitag fällig.
Druckerei Weber, RE-2207: Betrag stimmt nicht mit dem Angebot überein.
dein-server.de
- Push aufs Handy. Im Push steht der Name der App, dazu
titleund der Anfang vontext. Tippst du ihn an, öffnet sich die App. Der Push kommt auch, wenn die App gerade offen ist. - Zähler auf der Kachel. Im Tab Apps zeigt die Kachel, wie viele Mitteilungen ungelesen sind. Öffnest du die App, gelten alle als gelesen.
- Verlauf unter der Glocke. Oben rechts in jeder App sitzt eine Glocke. Sie zeigt alle Mitteilungen der App, die neueste oben, zehn auf einmal und weitere beim Scrollen. Der Verlauf liegt auch auf dem Handy und ist darum sofort da, ohne Netz mit dem letzten Stand. Neben der Glocke lädt ein Knopf deine Seite neu.
Was unter der Glocke steht
| Feld | Unter der Glocke |
|---|---|
title | Fett als Überschrift. Ohne title steht dort „Mitteilung“. |
text | Mit Formatierung. Lange Texte sind gekürzt und klappen beim Antippen auf. |
url | Antippen öffnet den Link. Darunter steht die Adresse. Zeig hier am besten auf die passende Stelle deiner Seite. |
priority | Wie bei Kanälen: Ton, stumm oder Push trotz Ruhezeit. Siehe Push, Ton und Ruhezeit. |
image, buttons, elements | Werden angenommen, aber nicht gezeigt. Lass sie weg: Bedienen gehört auf deine Seite. |
Tipps
- Kurz und konkret. Eine Mitteilung sagt, dass etwas wartet. Die Arbeit selbst passiert auf deiner Seite.
- Seite aktualisieren. Kommt jemand über den Push in die App, war die Seite vielleicht noch im Speicher. Lade deine Daten neu, sobald das Ereignis
packlets:activatedkommt:
<script>
addEventListener("packlets:activated", () => naechste());
</script>- Nicht für jede Kleinigkeit. Es gelten dieselben Grenzen wie für Kanäle: 60 Aufrufe pro Minute und App. Fass mehrere Ereignisse lieber zu einer Mitteilung zusammen („3 neue Rechnungen“).
- Push, Ton und Ruhezeit stellt jeder selbst in den Einstellungen der App ein. Tippe dafür in der App oben auf Avatar oder Namen.
- Ohne Code: Auch die Adressen für Slack, Discord und ntfy funktionieren mit dem Schlüssel einer App. So landen zum Beispiel Meldungen deines CI-Systems unter der Glocke.
Damit es sich wie eine App anfühlt
- Weißer Hintergrund, kein eigener Rahmen und kein Schatten außen herum.
- Kein eigener Kopf. Name und Avatar zeigt Packlets schon. Was wichtig ist, gehört nach oben.
- Tippflächen mindestens 44 Pixel hoch, Text mindestens 12 Pixel.
- Kein Hover, keine Pop-ups, kein
alert(). Für Meldungen gibt espacklets.toast(). - Links auf deiner eigenen Adresse bleiben in der App. Links zu anderen Adressen öffnen sich im Browser.
- Testen kannst du im Browser in Handy-Breite, zum Beispiel mit 375 Pixeln in den Entwicklerwerkzeugen.
Ausprobieren
Die beiden Seiten oben sind echte Apps:
- Wetter zeigt, wie frei du gestalten kannst. Jedes neue Konto hat sie in Packlets unter Apps.
- Konto zeigt das Session-Token: Die Seite holt bei jeder Anfrage ein frisches Token, ihr Server prüft es und zeigt deinen Namen. Im Browser zeigt dieselbe Seite nur einen Hinweis, denn dort gibt es kein Token.
Checkliste
- Adresse der Seite mit
PUT /v1/uiund{"page": "https://…"}geschickt. <meta name="viewport" content="width=device-width, initial-scale=1">gesetzt.packlets.cssundpacklets.jseingebunden.- Anfragen an deinen Server laufen über
packlets.fetch(). - Dein Server prüft bei jeder Anfrage Signatur, Ablauf und
auddes Tokens. - Der Schlüssel steht nur auf dem Server.
- Fremde iframes mit
sandbox, deine Seite mitframe-ancestors 'none'ausgeliefert. - Mitteilungen schickt dein Server mit
POST /v1/push, kurz und miturlauf die passende Stelle deiner Seite.
Wie es weitergeht
- Alle Aufrufe von
packlets.js, das Token undpacklets.css: Referenz. - Feld, Antwort und Fehler von
PUT /v1/ui: PUT /v1/ui. - Alle Felder einer Mitteilung: POST /v1/push.